README.md
# Sprockets::Preload
[](http://badge.fury.io/rb/sprockets-preload)
[](https://travis-ci.org/inossidabile/sprockets-preload)
[](https://codeclimate.com/github/inossidabile/sprockets-preload)
Ever had heavy Javascript assets that were taking a while to download? **Sprockets::Preload** allows you to preload it using only the directives of **Sprockets**.
Show your users nice loading bar instead of just white loading screen!
## Usage
Imagine that you are riding on Rails and have the following `application.js` where `jquery`, `jquery-ui` and `front` (MVC front-end application) take around 500kb compressed altogether:
```javascript
//= include helpers
//= include jquery
//= include jquery-ui
//= include front
$(function(){
// Starting application
Front.start();
});
```
Let's make user experience smooth:
1. Add `sprockets-preload` to your `Gemfile` and run `bundle install`
2. Change `//= include` to `//= preload` for the assets you want to detach:
```javascript
//= include helpers
//= preload jquery
//= preload jquery-ui
//= preload front
$(function(){
// Starting application
Front.start();
});
```
3. Delay initialization to the moment when detached assets are loaded:
```javascript
//= include helpers
//= preload jquery
//= preload jquery-ui
//= preload front
SprocketsPreload.success = function() {
// Starting application
Front.start();
}
```
4. Track loading and show progress to user
```javascript
//= include helpers
//= preload jquery
//= preload jquery-ui
//= preload front
SprocketsPreload.success = function() {
// Starting application
Front.start();
}
SprocketsPreload.progress = function(percent) {
// User isn't going to see percents at console
// but that's just an example after all
console.log(percent);
}
```
5. **IMPORTANT**: Rails development environment uses stub to ease debugging. Thus while things keep working, assets don't really get detached. To force production-grade loading (just to make sure things work fine) add `//= preload!` to your manifest:
```javascript
//= preload!
//= include helpers
//= preload jquery
//= preload jquery-ui
//= preload front
SprocketsPreload.success = function() {
// Starting application
Front.start();
}
SprocketsPreload.progress = function(percent) {
// User isn't going to see percents at console
// but that's just an example after all
console.log(percent);
}
```
Make sure to remove `//= preload!` when your tests are done.
-----------
By the way, there's also `//= preload_tree` directive that works similar to `//= require_tree`.
## Caching options
To make loading progress tracking smooth and cache manually controllable, **Sprockets::Preload** uses `localStorage` to cache assets (it falls back to default browser cache automatically). **Sprockets** provides digests and logic-aware dependency system that work much better and much more predictable than more common default HTTP caching.
That's said – you really want to keep `localStorage` strategy in the vast majority of cases. If however for some reason you still want to make it use default browser cache, set `SprocketsPreload.localStorage` to `false` like this:
```javascript
//= preload!
//= include helpers
//= preload jquery
//= preload jquery-ui
//= preload front
SprocketsPreload.localStorage = false;
SprocketsPreload.success = function() {
// Starting application
Front.start();
}
SprocketsPreload.progress = function(percent) {
// User isn't going to see percents at console
// but that's just an example after all
console.log(percent);
}
```
**Note** that default caching strategy will still try to emulate loading progress tracking but it works MUCH worse.
## Compatibility
**Sprockets::Preload** does not depend on Rails. However it has proper rail-ties and is fully-functional on Rails out of box. If you want to use it outside of Rails with clean **Sprockets** – see `lib/sprockets/preload/engine.rb` for required initialization settings.
## History
**Sprockets::Preload** is a mutated fork of [Joosy](http://joosy.ws) 1.x preloaders. For Node.js-based applications please refer to [Loada](https://github.com/inossidabile/loada).
## Maintainers
* Boris Staal, [@inossidabile](http://staal.io)
## License
It is free software, and may be redistributed under the terms of MIT license.
[](https://bitdeli.com/free "Bitdeli Badge")