Prepare docs for new release (#1076)

CHANGELOG.md

@@ -25,7 +25,7 @@ const jsonLoader =  {
   loader: 'json-loader'
 }
 
-environment.loaders.set('json', jsonLoader)
+environment.loaders.append('json', jsonLoader)
 environment.loaders.prepend('json', jsonLoader)
 environment.loaders.insert('json', jsonLoader, { after: 'style' } )
 environment.loaders.insert('json', jsonLoader, { before: 'babel' } )
@@ -36,7 +36,7 @@ manifestPlugin.opts.writeToFileEmit = false
 
 // Update coffee loader to use coffeescript 2
 const babelLoader = environment.loaders.get('babel')
-environment.loaders.set('coffee', {
+environment.loaders.insert('coffee', {
   test: /\.coffee(\.erb)?$/,
   use:  babelLoader.use.concat(['coffee-loader'])
 }, { before: 'json' })
@@ -45,7 +45,7 @@ environment.loaders.set('coffee', {
 - Expose `resolve.modules` paths like loaders and plugins
 
 ```js
-environment.resolvedModules.set('vendor', 'vendor')
+environment.resolvedModules.append('vendor', 'vendor')
 ```
 
 - Enable sourcemaps in `style` and `css` loader
@@ -75,6 +75,13 @@ watch_options:
   ignored: /node_modules/
 ```
 
+- `pretty` option to disable/enable color and progress output when running dev server
+
+```yml
+dev_server:
+  pretty: false
+```
+
 - Enforce deterministic loader order in desc order, starts processing from top to bottom
 
 - Enforce the entire path of all required modules match the exact case of the actual path on disk using [case sensitive paths plugin](https://github.com/Urthen/case-sensitive-paths-webpack-plugin).
@@ -97,6 +104,9 @@ WEBPACKER_PRECOMPILE=false bundle exec rails assets:precompile
 
 - Use `WEBPACKER_ASSET_HOST` instead of `ASSET_HOST` for CDN
 
+- Alias `webpacker:compile` task to `assets:precompile` if is not defined so it works
+without sprockets
+
 
 ## [3.0.2] - 2017-10-04
 

docs/assets.md

@@ -42,7 +42,7 @@ It's possible to link to assets that have been precompiled by Sprockets. Add the
 <%# app/javascript/my_pack/example.js.erb %>
 
 <% helpers = ActionController::Base.helpers %>
-var railsImagePath = "<%= helpers.image_path('rails.png') %>"
+const railsImagePath = "<%= helpers.image_path('rails.png') %>"
 ```
 
 This is enabled by the `rails-erb-loader` loader rule in `config/webpack/loaders/erb.js`.

docs/css.md

@@ -89,6 +89,23 @@ file for the entry point.  Loading the stylesheet will also load the
 CSS for any nested components.
 
 ```erb
-<%= stylesheet_pack_tag 'hello_vue' %> 
+<%= stylesheet_pack_tag 'hello_vue' %>
 <%= javascript_pack_tag 'hello_vue' %>
 ```
+
+## Resolve url loader
+
+Since `Sass/libsass` does not provide url rewriting, all linked assets must be relative to the output. Add the missing url rewriting using the resolve-url-loader. Place it directly after the sass-loader in the loader chain.
+
+
+```bash
+yarn add resolve-url-loader
+```
+
+```js
+// webpack/environment.js
+const { environment } = require('@rails/webpacker')
+
+const sassLoader = environment.loaders.get('sass')
+sassLoader.use.push({ loader: 'resolve-url-loader' })
+```

docs/deployment.md

@@ -30,6 +30,44 @@ git push heroku master
 ```
 
 
+## Nginx
+
+Webpacker doesn't serve anything in production. You’re expected to configure your web server to serve files in public/ directly.
+
+Some servers support sending precompressed versions of files with the `.gz` extension when they're available. For example, nginx offers a `gzip_static` directive.
+
+Here's a sample nginx site config for a Rails app using Webpacker:
+
+```nginx
+upstream app {
+  # ...
+}
+
+server {
+  server_name www.example.com;
+  root /path/to/app/public;
+
+  location @app {
+    proxy_pass http://app;
+    proxy_redirect off;
+
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+
+  location / {
+    try_files $uri @app;
+  }
+
+  location ^~ /packs/ {
+    gzip_static on;
+    expires max;
+  }
+}
+```
+
 ## CDN
 
 Webpacker out-of-the-box provides CDN support using your Rails app `config.action_controller.asset_host` setting. If you already have [CDN](http://guides.rubyonrails.org/asset_pipeline.html#cdns) added in your Rails app

docs/docker.md

@@ -0,0 +1,49 @@
+# Docker
+
+To setup webpacker with a dockerized Rails application is trivial.
+
+First, add a new service for webpacker in docker-compose.yml:
+
+```Dockerfile
+version: '3'
+services:
+  webpacker:
+    build: .
+    env_file:
+      - '.env.docker'
+    command: bundle exec webpack-dev-server
+    volumes:
+      - .:/webpacker-example-app
+    ports:
+      - '3035:3035'
+```
+
+add nodejs and yarn as dependencies in Dockerfile,
+
+```dockerfile
+FROM ruby:2.4.1
+RUN apt-get update -qq
+
+RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
+RUN curl -sL https://deb.nodesource.com/setup_8.x | bash
+RUN echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list
+
+RUN apt-get install -y nodejs
+RUN apt-get update && apt-get install yarn
+
+# Rest of the commands....
+```
+
+and create an env file to load environment variables from:
+
+```env
+NODE_ENV=development
+RAILS_ENV=development
+WEBPACKER_DEV_SERVER_HOST: 0.0.0.0
+```
+
+Lastly, rebuild your container:
+
+```bash
+docker-compose up --build
+```

docs/webpack-dev-server.md

@@ -1,4 +1,4 @@
-# webpack Dev Server
+# webpack-dev-server
 
 
 ## HTTPS

docs/webpack.md

@@ -28,25 +28,32 @@ module.exports = {
   }
 }
 
-// config/webpack/development.js
-const merge = require('webpack-merge')
+// config/webpack/environment.js
 const environment = require('./environment')
 const customConfig = require('./custom')
 
-module.exports = merge(environment.toWebpackConfig(), customConfig)
-```
+// Set nested object prop using path notation
+environment.config.set('resolve.extensions', ['.foo', '.bar'])
+environment.config.set('output.filename', '[name].js')
 
-If you need access to configs within Webpacker's configuration, you can import them like this:
-```js
-const config = require('@rails/webpacker/package/config');
-const asset_host = require('@rails/webpacker/package/asset_host');
+// Merge custom config
+environment.config.merge(customConfig)
+
+// Delete a property
+environment.config.delete('output.chunkFilename')
 
-console.log(asset_host.publicPathWithHost);
+module.exports = environment
 ```
 
-**Note:** You will have to merge custom config to all env where you want that config
-to be available. In above case, it will be applied to development environment.
+If you need access to configs within Webpacker's configuration,
+you can import them like so:
 
+```js
+const { config, asset_host } = require('@rails/webpacker')
+
+console.log(asset_host.publicPathWithHost)
+console.log(config.source_path)
+```
 
 ## Loaders
 
@@ -61,11 +68,18 @@ yarn add json-loader
 // config/webpack/environment.js
 const { environment } = require('@rails/webpacker')
 
-environment.loaders.set('json', {
+environment.loaders.append('json', {
   test: /\.json$/,
   use: 'json-loader'
 })
 
+// Insert json loader at the top of list
+environment.loaders.prepend('json', jsonLoader)
+
+// Insert json loader after/before a given loader
+environment.loaders.insert('json', jsonLoader, { after: 'style'} )
+environment.loaders.insert('json', jsonLoader, { before: 'babel'} )
+
 module.exports = environment
 ```
 
@@ -79,13 +93,58 @@ the `babel` loader as an example:
 // config/webpack/environment.js
 const { environment } = require('@rails/webpacker')
 
-// Update an option directly
 const babelLoader = environment.loaders.get('babel')
 babelLoader.options.cacheDirectory = false
 
 module.exports = environment
 ```
 
+### Coffeescript 2
+
+Out of the box webpacker supports coffeescript 1,
+but here is how you can use Coffeescript 2:
+
+```
+yarn add coffeescript@2.0.1
+```
+
+```js
+// config/webpack/environment.js
+const { environment } = require('@rails/webpacker')
+
+const babelLoader = environment.loaders.get('babel')
+
+// Replace existing coffee loader with CS2 version
+environment.loaders.insert('coffee', {
+  test: /\.coffee(\.erb)?$/,
+  use:  babelLoader.use.concat(['coffee-loader'])
+})
+
+module.exports = environment
+```
+
+### React SVG loader
+
+To use react svg loader, you should append svg loader before file loader:
+
+```js
+const { environment } = require('@rails/webpacker')
+
+const babelLoader = environment.loaders.get('babel')
+
+environment.loaders.insert('svg', {
+  test: /\.svg$/,
+  use: babelLoader.use.concat([
+    {
+      loader: 'react-svg-loader',
+      options: {
+        jsx: true // true outputs JSX tags
+      }
+    }
+  ])
+}, { before: 'file' })
+```
+
 ### Overriding Loader Options in webpack 3+ (for CSS Modules etc.)
 
 In webpack 3+, if you'd like to specify additional or different options for a loader, edit `config/webpack/environment.js` and provide an options object to override. This is similar to the technique shown above, but the following example shows specifically how to apply CSS Modules, which is what you may be looking for:
@@ -126,10 +185,11 @@ const { environment } = require('@rails/webpacker')
 const webpack = require('webpack')
 
 // Get a pre-configured plugin
-environment.plugins.get('ExtractText') // Is an ExtractTextPlugin instance
+const manifestPlugin = environment.plugins.get('Manifest')
+manifestPlugin.opts.writeToFileEmit = false
 
 // Add an additional plugin of your choosing : ProvidePlugin
-environment.plugins.set(
+environment.plugins.prepend(
   'Provide',
   new webpack.ProvidePlugin({
     $: 'jquery',
@@ -143,9 +203,27 @@ environment.plugins.set(
   })
 )
 
+// Insert before a given plugin
+environment.plugins.insert('CommonChunkVendor',
+  new webpack.optimize.CommonsChunkPlugin({
+    name: 'vendor', // Vendor code
+    minChunks: (module) => module.context && module.context.indexOf('node_modules') !== -1
+  })
+, { before: 'manifest' })
+
 module.exports = environment
 ```
 
+## Resolved modules
+
+To add new paths to `resolve.modules`, the API is same as loaders and plugins:
+
+```js
+const { environment } = require('@rails/webpacker')
+
+// Resolved modules list API - prepend, append, insert
+environment.resolvedModules.append('vendor', 'vendor')
+```
 
 ### Add common chunks
 
@@ -156,18 +234,18 @@ Add the plugins in `config/webpack/environment.js`:
 ```js
 const webpack = require('webpack')
 
-environment.plugins.set(
+environment.plugins.append(
   'CommonsChunkVendor',
   new webpack.optimize.CommonsChunkPlugin({
     name: 'vendor',
     minChunks: (module) => {
       // this assumes your vendor imports exist in the node_modules directory
-      return module.context && module.context.indexOf('node_modules') !== -1;
+      return module.context && module.context.indexOf('node_modules') !== -1
     }
   })
 )
 
-environment.plugins.set(
+environment.plugins.append(
   'CommonsChunkManifest',
   new webpack.optimize.CommonsChunkPlugin({
     name: 'manifest',