soutaro / webpack_rails

Webpack integration for Rails

webpack_rails

Provides Webpack integration for Rails apps.

Getting Started

Add this line to your app's Gemfile.

gem 'webpack_rails'

It is recommended to have a package.json in your Rails app, which at least contains dependencies to webpack, webpack-dev-middleware, and express. The following is a example extracted from the dummy application in this repository.

{
  "name": "dummy",
  "version": "1.0.0",
  "description": "dummy application for webpack_rails",
  "author": "Dummy author",
  "dependencies": {
    "express": "^4.13.3",
    "webpack": "^1.11.0",
    "webpack-dev-middleware": "^1.2.0"
  }
}

Run npm install in your app's root.

$ npm install

Now, you can require JS modules in your application.js.

var message = require(message);
console.log(message);

Write the following in message.js.

module.exports = "Hello webpack_rails!";

Load application.js in your application, and you will see the welcome message.

Configuration

Configuration can be done through Rails.application.config.webpack_rails.

Rails.application.config.webpack_rails.port = 3001
Rails.application.config.webpack_rails.node_bin = "/opt/bin/node"
Rails.application.config.webpack_rails.webpack_bin = "/opt/bin/webpack"
Rails.application.config.webpack_rails.silent = true

Add a file config/initializers/webpack_rails.rb for configuration, or you can write them in config/application.rb or config/environments/developmentrb.

All of the configuration above are optional. It should work out of box.

Webpack Entry

If you want to process JS files other than application.js, add the file to Rails.application.config.webpack_rails[:entries].

jss = []
jss += %w(login.js)

Rails.application.config.webpack_rails[:entries] += jss
Rails.application.config.assets.precompile += jss

The entry files should be in app/assets/javascripts. You can not put them in other directories.

The files usually should be also in Rails.application.config.assets.precompile. You may want to write the lines in config/initializer/assets.rb.

Restart your Rails application when you add new files to webpack_rails.entries or assets.precompilie.

//= require

//= require jquery
//= require jquery_ujs
//= require turbolinks

var app = require(app);

Since the entry files are processed by asset pipeline, you can //= require files. Other modules does not go through asset pipeline, you cannot //= require.

CoffeeScript

The entry can be a CoffeeScript files. However, this plugin does not help writing CoffeeScript in other modules.

The CoffeeScript compilation of entry is done by Rails asset pipeline.

Other webpack Configuration

You can give a configuration to webpack via Rails.application.config.webpack_rails.config hash, or write it to config/webpack.config.json. The configuration is merged to the configuration generated by Webpack Rails, except entry option.

Using npm modules

npm install --save bootstrap

Debugging

The plugin uses webpack-dev-middleware to compile JS files. It starts an Express app on startup, and every processing are done by the server.

webpack configuration is generated and saved in tmp/webpack_rails/webpack.config.js. The assets precompiled JS file will be save in tmp/webpack_rails/input directory. You can check them if something goes wrong.

Server Starting Failure

When you see a message like the following:

events.js:85
      throw er; // Unhandled 'error' event
            ^
Error: listen EADDRINUSE
    at exports._errnoException (util.js:746:11)
    at Server._listen2 (net.js:1146:14)
    at listen (net.js:1172:10)
    at Server.listen (net.js:1257:5)
    at EventEmitter.listen (.../webpack_rails/node_modules/express/lib/application.js:617:24)
    at Object.<anonymous> (.../webpack_rails/lib/webpack_rails/server.js:14:18)
    at Module._compile (module.js:460:26)
    at Object.Module._extensions..js (module.js:478:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)

Express server is not properly shutdown.

Try the following to shutdown the running server.

$ killall node

Developers

• Soutaro Matsumoto

Copying

This project rocks and uses MIT-LICENSE.