README.md in webpacker-1.1 vs README.md in webpacker-1.2
- old
+ new
@@ -1,16 +1,28 @@
# Webpacker
+[](https://nodejs.org/en/)
+[](https://github.com/rails/webpacker)
-Webpacker makes it easy to use the JavaScript preprocessor and bundler [Webpack](https://webpack.github.io)
+Webpacker makes it easy to use the JavaScript preprocessor and bundler [Webpack 2.x.x+](https://webpack.js.org/)
to manage application-like JavaScript in Rails. It coexists with the asset pipeline,
-as the purpose is only to use Webpack for app-like JavaScript, not images, css, or
-even JavaScript Sprinkles (that all continues to live in app/assets).
+as the primary purpose for Webpack is app-like JavaScript, not images, css, or
+even JavaScript Sprinkles (that all continues to live in app/assets). It is, however,
+possible to use Webpacker for CSS and images assets as well, in which case you may not
+even need the asset pipeline. This is mostly relevant when exclusively using component-based
+JavaScript frameworks.
It's designed to work with Rails 5.1+ and makes use of the [Yarn](https://yarnpkg.com) dependency management
that's been made default from that version forward.
+## Prerequisites
+
+* Ruby 2.2+
+* Rails 4.2+
+* Node.js 6.4.0+
+* Yarn
+
## Installation
Webpacker is currently compatible with Rails 4.2+, but there's no guarantee it will still be
in the future.
@@ -25,29 +37,18 @@
You can also see a list of available commands by running `./bin/rails webpacker`
## Binstubs
-Webpacker ships with three binstubs: `./bin/webpack`, `./bin/webpack-watcher` and `./bin/webpack-dev-server`.
-They're thin wrappers around the standard webpack.js executable, just to ensure that the right configuration
-file is loaded.
+Webpacker ships with two binstubs: `./bin/webpack` and `./bin/webpack-dev-server`.
+They're thin wrappers around the standard webpack.js executable, just to ensure that the right configuration file is loaded depending on your environment.
-
A binstub is also created to install your npm dependencies,
and can be called via `./bin/yarn`.
-In development, you'll need to run `./bin/webpack-watcher` in a separate terminal from
-`./bin/rails server` to have your `app/javascript/packs/*.js` files compiled as you make changes.
-If you'd rather not have to run the two processes separately by hand, you can use
-[Foreman](https://ddollar.github.io/foreman).
+In development, you'll need to run `./bin/webpack-dev-server` in a separate terminal from `./bin/rails server` to have your `app/javascript/packs/*.js` files compiled as you make changes. If you'd rather not have to run the two processes separately by hand, you can use [Foreman](https://ddollar.github.io/foreman). `./bin/webpack-dev-server` launches the [Webpack Dev Server](https://webpack.js.org/configuration/dev-server/), which serves your pack files on http://localhost:8080/, and provides advanced Webpack features, such as [Hot Module Replacement](https://webpack.js.org/guides/hmr-react/).
-Alternatively, you can run `./bin/webpack-dev-server`. This will launch a
-[Webpack Dev Server](https://webpack.github.io/docs/webpack-dev-server.html) listening on http://localhost:8080/
-serving your pack files. This setup allows you to leverage advanced Webpack features, such
-as [Hot Module Replacement](https://webpack.github.io/docs/hot-module-replacement-with-webpack.html).
-
-
## Configuration
Webpacker gives you a default set of configuration files for development and production. They
all live together with the shared points in `config/webpack/*.js`. By default, you shouldn't have to
make any changes for a basic setup out the box. But this is where you do go if you need something
@@ -70,17 +71,38 @@
app/javascript/calendar/styles/grid.sass
app/javascript/calendar/models/month.js
```
```erb
-<%# app/views/layout/application.html.erb %>
+<%# app/views/layouts/application.html.erb %>
<%= javascript_pack_tag 'calendar' %>
<%= stylesheet_pack_tag 'calendar' %>
```
But it could also look a million other ways.
+**Note:** You can also namespace your packs using directories, similar to a Rails app.
+
+```
+app/javascript/packs/admin/orders.js
+app/javascript/packs/shop/orders.js
+```
+
+and reference them in your views like this:
+
+```erb
+<%# app/views/admin/orders/index.html.erb %>
+<%= javascript_pack_tag 'admin/orders' %>
+```
+
+and
+
+```erb
+<%# app/views/shop/orders/index.html.erb %>
+<%= javascript_pack_tag 'shop/orders' %>
+```
+
## Advanced Configuration
By default, webpacker offers simple conventions for where the webpack configs, javascript app files and compiled webpack bundles will go in your rails app,
but all these options are configurable from `config/webpack/paths.yml` file.
@@ -107,26 +129,21 @@
```
By default, `webpack-dev-server` uses `output` option specified in
`paths.yml` as `contentBase`.
-**Note:** Don't forget to disable `webpack-dev-server` incase you are using
-`./bin/webpack-watcher` to serve assets in development mode otherwise
-you will get 404 for assets because the helper tag will use webpack-dev-server url
-to serve assets instead of public directory.
-
## Linking to static assets
Static assets like images, fonts and stylesheets support is enabled out-of-box so, you can link them into your javascript app code and have them compiled automatically.
```js
// React component example
// app/javascripts/packs/hello_react.jsx
import React from 'react'
import ReactDOM from 'react-dom'
import helloIcon from '../hello_react/images/icon.png'
-import './hello-react.sass'
+import '../hello_react/styles/hello-react.sass'
const Hello = props => (
<div className="hello-react">
<img src={helloIcon} alt="hello-icon" />
<p>Hello {props.name}!</p>
@@ -212,10 +229,10 @@
when loading a view in browser it's because Webpack is still compiling packs.
Webpacker uses a `manifest.json` file to keep track of packs in all environments,
however since this file is generated after packs are compiled by webpack. So,
if you load a view in browser whilst webpack is compiling you will get this error.
Therefore, make sure webpack
-(i.e `./bin/webpack-watcher` or `./bin/webpack-dev-server`) is running and has
+(i.e `./bin/webpack-dev-server`) is running and has
completed the compilation successfully before loading a view.
## Wishlist
- Improve process for linking to assets compiled by sprockets - shouldn't need to specify