Frontrunner

🔥 Webpack for Rails

Note: Rails now supports Webpack, so use that instead

Why Webpack?

• Manage your JavaScript and CSS dependencies with npm, the JavaScript package manager
• Use modules to keep your code organized
• Optional Use hot module replacement for faster iteration

But there are also a few drawbacks:

• More complex development process
• Longer build times, as there is currently no way to cache between builds

As with the Rails asset pipeline (Sprockets), you also get:

• Minification and compression
• Digests for long-term caching
• Coffeescript and Sass support
• Source maps (Sprockets 4+)
• ES6 support (Sprockets 4+)
• Optional JSX support for React

Frontrunner plays nicely with the Rails asset pipeline. This makes it easy to transition existing apps at your own pace. While it may be tempting to remove Sprockets, some Rails engines like RailsAdmin depend on it. You never know when you’ll want to add one of these, so we recommend keeping it around.

Like Rails, jQuery, jQuery UJS, and Turbolinks are added to start, but these can be easily removed if desired.

The Setup

Here are the files and directories we’ll use.

Files	Description
package.json	Gemfile for npm
npm-shrinkwrap.json	Gemfile.lock for npm
webpack.config.js	Webpack config
node_modules	npm packages
app/webpack	app/assets equivalent

Installation

Add this line to your application’s Gemfile

gem 'frontrunner'

And run:

bundle install

Generate files

rails generate frontrunner:install

And run:

npm install && npm shrinkwrap --dev

Then, add to your layout:

<%= webpack_include_tag "application" %>

Development

Run:

npm run server

This will start the webpack-dev-server at http://localhost:8080.

It’s possible to serve Webpack assets through Sprockets rather than a separate web server in development, but this can be significantly slower.

If you use Foreman, you can create a Procfile.dev with:

web: bin/rails server
webpack: npm run server

And run it with:

foreman start -f Procfile.dev

Packages

Add new packages with npm.

npm install underscore -S

Use the -S option to save it to package.json.

You can now include the package in your JavaScript.

var _ = require("underscore");
var trips = _.map([1, 2, 3], function (i) { return i * 3; });
console.log(trips);

Bootstrap

Run:

npm install bootstrap-sass -S

For CSS, in application.scss, add:

$icon-font-path: "~bootstrap-sass/assets/fonts/bootstrap/";
@import "bootstrap-sass/assets/stylesheets/bootstrap";

Or only include specific components with:

@import "bootstrap-sass/assets/stylesheets/bootstrap/variables";
@import "bootstrap-sass/assets/stylesheets/bootstrap/mixins";
@import "bootstrap-sass/assets/stylesheets/bootstrap/alerts";

For JavaScript, in application.js, add:

require("bootstrap-sass/assets/javascripts/bootstrap");

Or only include specific components with:

require("bootstrap-sass/assets/javascripts/bootstrap/alert");

React

Run:

npm install react react-dom -S

Support for jsx is already included.

Add React Hot Loader with:

npm install react-hot-loader -D

See Hot Module Replacement for how to activate.

Entry Points

During installation, a single entry point - application - is created.

To add another entry point - for instance, for a blog - create blog.js and add it to webpack.config.js.

{
  entry: {
    application: "application",
    blog: "blog"
  }
}

To include it in your views, use:

<%= webpack_include_tag "blog" %>

Hot Module Replacement

Use hot module replacement to update code without reloading the page.

Just run npm run server:hot instead of npm run server.

If you use React, this includes the React Hot Loader.

Deployment

Node.js is required to build the assets. As part of the build process, run:

npm run assets:precompile

Heroku

On Heroku, you’ll need to use multiple buildpacks.

heroku buildpacks:clear
heroku buildpacks:add heroku/nodejs
heroku buildpacks:add heroku/ruby

And ask Heroku to install dev dependencies from package.json.

heroku config:set NPM_CONFIG_PRODUCTION=false

And in package.json, under scripts, add:

{
  "scripts": {
    "heroku-postbuild": "npm run assets:precompile"
  }
}

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features