Toast v3

Toast is a promise-based JS/CSS loader for the browser. It aims to optimize web site performance by loading your assets asynchronoulsy.

Quick note on IE9/10 support

Support has been dropped for these browsers since Mocha/Sinon (which is used to run our tests) does not support them anymore. Since it would take some time to migrate the tests, that IE9/10 is not supported anymore by Microsoft, and that its market share have dropped under 1%, we took the decision to stop our support too.

For the time being, Toast 3.0.2 will work with IE9/10. Since the code shouldn't evolve too much, you should be safe in the far future until Toast reaches a breaking change.

Compatibility list

Toast is tested against:

Chrome 83 (older version should be good too)
Firefox 76 (older version should be good too)
Edge 83 (older version should be good too)
Safari 11-13
IE11
Android 4.4-10
iOS 10-13

Set up

The preferred way to load toast in your application is to install it via NPM (or Yarn), and import it directly in your codebase (it has a very small footprint, and the sooner it's loaded the better).

npm install toast-loader

You have several options to load it in your code depending on your application environment:

by inlining it in a <script> tag
with const { toast } = require('toast-loader')
with import { toast } from 'toast-loader'

You can also load it from the usual <script> tag in your <head>, but I advise you to use a CDN instead of loading it from your own server:

<head>
    <script src="https://cdn.jsdelivr.net/npm/toast-loader@3.0.4"></script>
</head>

Be sure to use the latest version of Toast and keep a fixed version in production environment (to avoid breaking changes).

The API

toast.css(url: string): Promise
toast.js(url: string): Promise
toast.all(urls: string[]): Promise

Examples

if (dark_mode === true) {
    toast.css('styles/dark.css')
} else {
    toast.css('styles/light.css')
}

const handleErrors = error => {
    console.log(error)
}

toast.js('http://some.cdn.com/jquery.js')
    .then(() => {
        toast.js('http://some.cdn.com/jquery-myplugin.js')
            .then(() => $('.someClass').myPlugin())
            .catch(handleErrors)
        })
    })
    .catch(handleErrors)

await toast.all([
    'assets/css/styles1.css',
    'assets/js/script1.js',
    'assets/js/script2.js',
    'assets/css/styles2.css',
    'assets/js/script3.js',
])
console.log('Everything has been loaded, yay!')

toast.all relies on automatic extension detection. If your URL does not contain a file extension you'll need to use Promise.all instead and do some extra work:

await Promise.all([
    toast.css('assets/css/styles1'),
    toast.js('assets/js/script1'),
    toast.js('assets/js/script2'),
    toast.css('assets/css/styles2'),
    toast.js('assets/js/script3'),
])
console.log('Everything has been loaded, yay!')

Browser compatibility

IE10 support (and prior) has been removed since it's not supported by Microsoft anymore and their market share have dropped under 1%
Toast is using built-in promises, so if you need to support I11, you must add the promise-polyfill library before loading toast: here's the compatibility table for the Promise feature
for your information, IE11 and Edge never trigger error event on CSS loading if something goes wrong; keep this in mind when you're using catch promise block
if you want to learn more about SCRIPT/LINK node feature support details, you can take a look at this compatibility table

Development

Install the dependencies with:

npm install

And build the lib with:

npm run build

Look at the scripts in package.json file for more details.

Testing

Tests are written with Mocha and Sinon, and can be run with:

npm run test

It should open your default browser (under a Gnome desktop). If not, just drag and drop the tests/index.html in your preferred browser.

These tests are just for local debugging when in development phase but they need to pass the Karma tests. Karma is a tool to execute unit tests on remote browsers with Selenium/Appium. To be able to run them, you'll need an account on BrowserStack. It's the only service that have a free plan for open-source projects.

When your account is ready, you must prepare your environment by setting global variables in a file that is loaded when your console initializes, like .bashrc, .zshrc or .profile:

go to the Automate page
display your ACCESS KEY (it's accessible on the right of the search bar)

set your env variables like so:

export BROWSERSTACK_USERNAME="<your_username>"
export BROWSERSTACK_ACCESS_KEY="<your_access_key>"

Then, run the karma tests with:

npm run karma:all

The results will be displayed in the console and on the Automate page of your account.

If you want to only run tests on a specific browser you can use one of the following commands:

npm run karma:chrome
npm run karma:firefox
npm run karma:safari13
npm run karma:safari12
npm run karma:safari11
npm run karma:edge
npm run karma:ie11
npm run karma:android10
npm run karma:android9
npm run karma:android8
npm run karma:android7
npm run karma:android6
npm run karma:android5
npm run karma:android44
npm run karma:ios13
npm run karma:ios12
npm run karma:ios11
npm run karma:ios10

Note: I don't know why but the tests can be unstable in some VMs when running all Karma tests in parallel; don't hesitate to re-run tests on a specific VM to verify.

License

MIT.

pyrsmk / toast