# webpack_rails

Provides Webpack integration for Rails apps.

## Getting Started

Add this line to your app's `Gemfile`.

```ruby
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.

```json
{
  "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`.

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

Write the following in `message.js`.

```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`.

```rb
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]`.

```rb
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

```js
//= 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.
