UPGRADING.md

Guide to upgrading from Sprockets 3.x to 4.x

Make sure that you're running the latest Sprockets 3 release. This document is a work in progress and not at all autoritative. It is meant to underline the biggest features and changes from Sprockets 3 to 4. If you're not already on Sprockets 3 check out https://github.com/rails/sprockets/blob/3.x/UPGRADING.md.

Sprockets 3 is a compatability release to bridge Sprockets 4. Deprecated things have been removed. The big feature added is source maps.

As a word of warning, source maps were half finished when this project was transitioned between maintainers. Please try things and if they don't work correctly open an issue with what you expected to happen, what happened and a small sample app showing the problem.

This upgrading guide touches on:

• Source Maps
• Manifest.js
• es6 support
• Deprecated processor interface in 3.x is removed in 4.x

Source Maps

First, what is a source map? There's a whole guide that talks about what a source map is and how it is used by the browser and generated by sprockets https://github.com/rails/sprockets/blob/master/guides/source_maps.md. The short answer is that source maps are a standard way to make debugging concatenated or compiled assets easier. If you were using Rails and Sprockets, in development mode no assets were concatenated, if your app used 10 js files all of them would be served independently. This helped with debugging so you got helpful errors like Error in file <file.js> on line <number> that pointed at the problem instead of at an unrelated jumbled minified JS file. Source maps eliminate the need to serve these seperate files, instead a special source map file can be read by the browser to help it understand how to unpack your assets. It "maps" the current modified asset to it's "source" so you can view the source when debugging. This way you can serve assets in development the exact same way as in production, fewer suprises is always better.

How do you use this feature? Well, upgrade to Sprockets 4 and you get it for free. How do you know if it's working right? Try adding a syntax error to one of your assets and use the console to debug, does it show the correct file and source location or does it reference the top level application.js file?

Here's the last issue where Source maps where talked about before the beta release rails#157

Manifest.js

Rails is the largest consumer of Sprockets, so we'll talk about how Sprockets relates with manifest.js. Previously if you wanted Rails to serve a non-standard named asset (any CSS not application.css or JS not application.js) you would have to add those files to a precompile list. For example if you needed a marketing page with it's own css you might add something like this:

# In your Rails configuration
config.assets.precompile += ["marketing.css"]

Instead of doing this Sprockets 3 introduced the concept of a "manifest" file that could list all assets you want to make available using the link directive. In this case you to compile the marketing.css you would set precompile to

config.assets.precompile = ["manifest.js"]

Then you will link to that css file in your manifest.js file. In sprockets the link directive declares that your file has a dependency on the thing you are linking, so it guarantees it will be compiled. Here's our example manifest file:

// app/assets/config/manifest.js
//
//= link application.css
//= link marketing.css
//
//= link application.js

Caution The "link" directive should have an explicit content type or file extension.

Now you'll be able to use a <%= stylesheet_link_tag "marketing" %> in your code. This is a standard way to let Sprockets know what files need to be compiled.

Some assets will be compiled when they are referenced from inside of another asset for example the asset_url erb helper will automatically link assets:

.logo {
  background: url(<%= asset_url("logo.png") %>)
}

When you do this Sprockets will "link" logo.png behind the scenes. This lets Sprockets know that this file needs to be compiled and made publically available. If that logo file changes, Sprockets will automatically see that change and re-compile the css file.

One benifit of using a manifest.js file for this type of configuration is that now Sprockets is using Sprockets to understand what files need to be generated instead of a non-portable framework specific interface.

ES6 Support

Sprockets 4 ships with a babel processor and allows you to compile es6 to JS just like you would compile coffee script to JS. To use this you'll first need to modify your Gemfile:

gem 'babel-transpiler'

Now write some es6. Here we are writing our application.js file in es6. Use the extension es6:

// app/assets/javascript/application.es6

var square = (n) => n * n

console.log(square);

When you turn on your Rails server in development mode and visit localhost:3000/assets/application.js you'll see this transpiled to regular JS:

var square = function square(n) {
  return n * n;
};

console.log(square);

Supporting All Versions of Sprockets in Processors

If you are extending sprockets you may want to support all current major versions of sprockets (2, 3, and 4). The processor interface was deprecated from Sprockets 2 and a legacy shim was put into Sprockets 3. Now that Sprockets 4 is out that shim no longer is active, so you'll need to update your gem to either only use the new interface or use both interfaces.

Please see the "Supporting all versions of Sprockets in Processors" section in the [extending sprockets guide for details.