Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pyrsmk/toast
A modern JS/CSS asset loader, written in TypeScript.
https://github.com/pyrsmk/toast
assets-management css js loader
Last synced: about 2 months ago
JSON representation
A modern JS/CSS asset loader, written in TypeScript.
- Host: GitHub
- URL: https://github.com/pyrsmk/toast
- Owner: pyrsmk
- License: mit
- Created: 2011-11-06T23:07:22.000Z (almost 13 years ago)
- Default Branch: master
- Last Pushed: 2020-07-31T16:34:45.000Z (about 4 years ago)
- Last Synced: 2024-07-21T10:07:51.620Z (2 months ago)
- Topics: assets-management, css, js, loader
- Language: JavaScript
- Homepage:
- Size: 1.99 MB
- Stars: 118
- Watchers: 8
- Forks: 13
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
Awesome Lists containing this project
README
# 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](https://yarnpkg.com/)), and import it directly in your codebase (it has a very small footprint, and the sooner it's loaded the better).
```sh
npm install toast-loader
```
You have several options to load it in your code depending on your application environment:
- by inlining it in a `` 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](https://www.jsdelivr.com/) instead of loading it from your own server:
```html
<head>
<script src="https://cdn.jsdelivr.net/npm/[email protected]">
```
Be sure to use the latest version of Toast and keep a fixed version in production environment (to avoid breaking changes).
## The API
```js
toast.css(url: string): Promise
toast.js(url: string): Promise
toast.all(urls: string[]): Promise
```
## Examples
```js
if (dark_mode === true) {
toast.css('styles/dark.css')
} else {
toast.css('styles/light.css')
}
```
```js
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)
```
```js
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:
```js
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](https://github.com/taylorhakes/promise-polyfill) library before loading toast: here's the compatibility table for the [Promise feature](https://www.caniuse.com/#feat=promises)
- 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](https://pie.gd/test/script-link-events/)
## Development
Install the dependencies with:
```sh
npm install
```
And build the lib with:
```sh
npm run build
```
Look at the scripts in `package.json` file for more details.
## Testing
Tests are written with [Mocha](https://mochajs.org/) and [Sinon](https://sinonjs.org/), and can be run with:
```sh
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](https://karma-runner.github.io/latest/index.html) 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](https://www.browserstack.com/). 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](https://automate.browserstack.com/dashboard/v2)
- display your `ACCESS KEY` (it's accessible on the right of the search bar)
- set your env variables like so:
```sh
export BROWSERSTACK_USERNAME=""
export BROWSERSTACK_ACCESS_KEY=""
```
Then, run the karma tests with:
```sh
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:
```sh
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](LICENSE.txt).