webpacker 5.2.1 → 6.0.0.pre.1

data/docs/deployment.md

@@ -128,3 +128,21 @@ namespace :deploy do
   end
 end
 ```
+
+If you use [nvm](https://github.com/nvm-sh/nvm) to manage node versions for your deployment user, use the below snippet instead:
+
+```ruby
+before "deploy:assets:precompile", "deploy:yarn_install"
+namespace :deploy do
+  desc "Run rake yarn install"
+  task :yarn_install do
+    on roles(:web) do
+      within release_path do
+        execute("source ~/.nvm/nvm.sh && cd #{release_path} && yarn install --silent --no-progress --no-audit --no-optional")
+      end
+    end
+  end
+end
+```
+The `source ~/.nvm/nvm.sh` is required because [nvm is not automatically loaded in non-interactive shells](https://github.com/nvm-sh/nvm/issues/1718).
+

data/docs/docker.md

@@ -17,7 +17,7 @@ services:
     volumes:
       - .:/webpacker-example-app
     ports:
-      - '3035:3035'
+      - '127.0.0.1:3035:3035'
 ```
 
 add nodejs and yarn as dependencies in Dockerfile,
@@ -56,7 +56,7 @@ then add the webpacker host name environment variable to the web/app service:
     volumes:
       - .:/usr/src/app
     ports:
-      - "3000:3000"
+      - "127.0.0.1:3000:3000"
     environment:
       - WEBPACKER_DEV_SERVER_HOST=webpacker
 ```

data/docs/engines.md

@@ -99,7 +99,7 @@ Now you can use `stylesheet_pack_tag` and `javascript_pack_tag` from within your
 
 Add Rake task to compile assets in production (`rake my_engine:webpacker:compile`)
 
-- File `my_engine_rootlib/tasks/my_engine_tasks.rake`
+- File `lib/tasks/my_engine_tasks.rake`
 
 ```ruby
 def ensure_log_goes_to_stdout

data/docs/env.md

@@ -49,6 +49,11 @@ dotenvFiles.forEach((dotenvFile) => {
   dotenv.config({ path: dotenvFile, silent: true })
 })
 
+environment.plugins.insert(
+  "Environment",
+  new webpack.EnvironmentPlugin(process.env)
+)
+
 module.exports = environment
 ```
 

data/docs/es6.md

@@ -42,7 +42,7 @@ The comment you see above (`/* webpackChunkName */`) is not arbitrary, it is one
 **Warning**: You should not attempt to dynamically load anything from your `packs/` folder. Instead, try to make your `pack` scripts a hub from which you dynamically load `non-pack` scripts.
 
 - [Docs for using magic comments](https://webpack.js.org/api/module-methods/#magic-comments)
-- [Docs for configuring `splitChunks` in webpacker](https://github.com/rails/webpacker/blob/master/docs/webpack.md#add-splitchunks-webpack-v4).
+- [Docs for configuring `splitChunks` in webpacker](/docs/webpack.md#add-splitchunks-webpack-v4).
 - [Docs for using dynamic `import()`](https://webpack.js.org/guides/code-splitting#dynamic-imports).
 
 ## Module import vs require()

data/docs/integrations.md

@@ -213,7 +213,7 @@ in `app/javascript/packs` so that you can experiment with CoffeeScript right awa
 
 To add [Erb](https://apidock.com/ruby/ERB) support in your JS templates,
 run `bundle exec rails webpacker:install:erb` on a Rails app already
-setup with Webpacker.
+setup with Webpacker and add extension 'erb' on file `config/webpacker.yml`.
 
 An example `hello_erb.js.erb` file will also be added to your project
 in `app/javascript/packs` so that you can experiment with Erb-flavoured

data/docs/props.md

@@ -1,45 +1,9 @@
 # Props
 
+How do you pass props from your view to your JavaScript component? Here you go.
 
 ## React
-
-If you need more advanced React-integration, like server rendering, redux, or react-router, see [shakacode/react_on_rails](https://github.com/shakacode/react_on_rails), [react-rails](https://github.com/reactjs/react-rails), and [webpacker-react](https://github.com/renchap/webpacker-react).
-
-If you're not concerned with view helpers to pass props or server rendering, can do it yourself:
-
-```erb
-<%# views/layouts/application.html.erb %>
-
-<%= content_tag :div,
-  id: "hello-react",
-  data: {
-    message: 'Hello!',
-    name: 'David'
-}.to_json do %>
-<% end %>
-```
-
-```js
-// app/javascript/packs/hello_react.js
-
-const Hello = props => (
-  <div className='react-app-wrapper'>
-    <img src={clockIcon} alt="clock" />
-    <h5 className='hello-react'>
-      {props.message} {props.name}!
-    </h5>
-  </div>
-)
-
-// Render component with data
-document.addEventListener('DOMContentLoaded', () => {
-  const node = document.getElementById('hello-react')
-  const data = JSON.parse(node.getAttribute('data'))
-
-  ReactDOM.render(<Hello {...data} />, node)
-})
-```
-
+See [docs/react.md](./react.md#props-hydration-and-server-side-rendering-ssr).
 
 ## Vue
 

data/docs/react.md

@@ -0,0 +1,183 @@
+# React
+
+## Props Hydration and Server-Side Rendering (SSR)
+You only _need_ props hydration if you need SSR. However, there's no good reason to
+have your app make a second round trip to the Rails server to get initialization props.
+
+Server-Side Rendering (SSR) results in Rails rendering HTML for your React components.
+The main reasons to use SSR are better SEO and pages display more quickly. 
+
+### Rails and React Integration Gems
+If you desire more advanced React-integration, like server-side rendering, SSR with react-router, SSR with code splitting, then you should consider these gems:
+
+| Gem | Props Hydration | Server-Side-Rendering (SSR) | SSR with HMR | SSR with React-Router | SSR with Code Splitting | Node SSR |
+| --- | --------------- | --- | --------------------- | ----------------------| ------------------------|----|
+| [shakacode/react_on_rails](https://github.com/shakacode/react_on_rails) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| [react-rails](https://github.com/reactjs/react-rails)  | ✅ | ✅ |  | | | | |
+| [webpacker-react](https://github.com/renchap/webpacker-react) | ✅ | | | | | | |
+
+Note, Node SSR for React on Rails requires [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro).
+
+### Hydration of Props the Manual Way
+
+If you're not concerned with view helpers to pass props or server-side rendering, you can do it like this:
+
+```erb
+<%# views/layouts/application.html.erb %>
+
+<%= content_tag :div,
+  id: "hello-react",
+  data: {
+    message: 'Hello!',
+    name: 'David'
+}.to_json do %>
+<% end %>
+```
+
+```js
+// app/javascript/packs/hello_react.js
+
+const Hello = props => (
+  <div className='react-app-wrapper'>
+    <img src={clockIcon} alt="clock" />
+    <h5 className='hello-react'>
+      {props.message} {props.name}!
+    </h5>
+  </div>
+)
+
+// Render component with data
+document.addEventListener('DOMContentLoaded', () => {
+  const node = document.getElementById('hello-react')
+  const data = JSON.parse(node.getAttribute('data'))
+
+  ReactDOM.render(<Hello {...data} />, node)
+})
+```
+
+----
+
+## HMR and React Hot Reloading
+
+Before turning HMR on, consider upgrading to the latest stable gems and packages:
+https://github.com/rails/webpacker#upgrading
+
+Configure `config/webpacker.yml` file:
+
+```yaml
+development:
+  extract_css: false
+  dev_server:
+    hmr: true
+    inline: true
+```
+
+This basic configuration alone will have HMR working with the default webpacker setup. However, an code saves will trigger a full page refresh each time you save a file.
+
+Webpack's HMR allows the replacement of modules for React in-place without reloading the browser. To do this, you have two options:
+
+1. Steps below for the [github.com/pmmmwh/react-refresh-webpack-plugin](https://github.com/pmmmwh/react-refresh-webpack-plugin).
+1. Deprecated steps below for using the [github.com/gaearon/react-hot-loader](https://github.com/gaearon/react-hot-loader).
+
+### React Refresh Webpack Plugin
+[github.com/pmmmwh/react-refresh-webpack-plugin](https://github.com/pmmmwh/react-refresh-webpack-plugin)
+
+You can see an example commit of adding this [here](https://github.com/shakacode/react_on_rails_tutorial_with_ssr_and_hmr_fast_refresh/commit/7e53803fce7034f5ecff335db1f400a5743a87e7).
+
+1. Add react refresh packages:
+   `yarn add @pmmmwh/react-refresh-webpack-plugin react-refresh -D`
+2. Update `babel.config.js` adding
+   ```js
+   plugins: [
+     process.env.WEBPACK_DEV_SERVER && 'react-refresh/babel',
+     // other plugins
+   ```
+3. Update `config/webpack/development.js`, only including the plugin if running the WEBPACK_DEV_SERVER
+   ```js
+   const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
+   const environment = require('./environment')
+   
+   const isWebpackDevServer = process.env.WEBPACK_DEV_SERVER;
+   
+   //plugins
+   if (isWebpackDevServer) {
+       environment.plugins.append(
+           'ReactRefreshWebpackPlugin',
+           new ReactRefreshWebpackPlugin({
+               overlay: {
+                   sockPort: 3035
+               }
+           })
+       );
+   }
+   ```
+
+### React Hot Loader (Deprecated)
+
+1. Add the `react-hot-loader` and ` @hot-loader/react-dom` npm packages.
+  ```sh
+  yarn add --dev react-hot-loader @hot-loader/react-dom
+  ```
+
+2. Update your babel config, `babel.config.js`. Add the plugin `react-hot-loader/babel`
+with option `"safetyNet": false`:
+
+```
+{
+    "plugins": [
+        [
+            "react-hot-loader/babel",
+            {
+            "safetyNet": false
+            }
+        ]
+    ]
+}
+```
+
+3. Add changes like this to your entry points:
+
+```diff
+// app/javascript/app.jsx
+
+import React from 'react';
++ import { hot } from 'react-hot-loader/root';
+
+const App = () => <SomeComponent(s) />
+
+- export default App;
++ export default hot(App);
+```
+
+4. Adjust your webpack configuration for development so that `sourceMapContents` option for the sass
+loader is `false`:
+
+```diff
+// config/webpack/development.js
+
+process.env.NODE_ENV = process.env.NODE_ENV || 'development'
+
+const environment = require('./environment')
+
+// allows for editing sass/scss files directly in browser
++ if (!module.hot) {
++   environment.loaders.get('sass').use.find(item => item.loader === 'sass-loader').options.sourceMapContents = false
++ }
++ 
+module.exports = environment.toWebpackConfig()
+```
+
+5. Adjust your `config/webpack/environment.js` for a 
+
+```diff
+// config/webpack/environment.js
+
+// ...
+
+// Fixes: React-Hot-Loader: react-🔥-dom patch is not detected. React 16.6+ features may not work.
+// https://github.com/gaearon/react-hot-loader/issues/1227#issuecomment-482139583
++ environment.config.merge({ resolve: { alias: { 'react-dom': '@hot-loader/react-dom' } } });
+
+module.exports = environment;
+```
+

data/docs/testing.md

@@ -134,3 +134,14 @@ Make sure you configure Rails to serve static files from the public directory in
 # Configure public file server for tests with Cache-Control for performance.
 config.public_file_server.enabled = true
 ```
+
+## Webpacker Configuration and Rails Tests
+
+Webpacker ships with three javascript configuration files: `test.js`,
+`development.js`, and `production.js`. The `NODE_ENV` environment
+variable determines which config will be used. `NODE_ENV` is
+independent of `RAILS_ENV` and is set to `development` by [default](/lib/install/bin/webpack#L4).
+This means that `rails test` or `rspec` will use `development.js`
+by default, _not_ `test.js`.
+
+For more information see [Why doesn't Webpacker use my test config when I run Rails tests?](https://rossta.net/blog/why-doesnt-webpacker-use-my-test-config-when-i-run-rails-tests.html)

data/docs/typescript.md

@@ -37,7 +37,7 @@ The default installation only transpiles your TypeScript code using Babel. If yo
     );
     ```
 
-    If you are `fork-ts-checker-webpack-plugin` older than 5.0, the `tsconfig` option also needs to be specified:
+    If you are using `fork-ts-checker-webpack-plugin` older than 5.0, the `tsconfig` option also needs to be specified:
 
     ```js
     const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
@@ -83,7 +83,7 @@ If you update your App to `webpacker >= 5.1` and had TypeScript installed before
 
 ## TypeScript with React
 
-1. Setup react using Webpacker [react installer](../README.md#react). Then run the TypeScript installer
+1. Setup react using Webpacker [react installer](integrations.md#react). Then run the TypeScript installer
 
 ```bash
 bundle exec rails webpacker:install:typescript

data/docs/webpack-dev-server.md

@@ -1,6 +1,5 @@
 # webpack-dev-server
 
-
 ## HTTPS
 
 If you're using the `webpack-dev-server` in development, you can serve your packs over HTTPS
@@ -13,24 +12,28 @@ so your web browser will display a warning/exception upon accessing the page. If
 in your console, simply open the link in your browser and accept the SSL exception.
 Now if you refresh your Rails view everything should work as expected.
 
-
-## HOT module replacement
+## Hot Module Replacement
 
 Webpacker out-of-the-box supports HMR with `webpack-dev-server` and
-you can toggle it by setting `dev_server/hmr` option inside `webpacker.yml`.
-
-Check out this guide for more information:
+you can toggle it by setting options in `config/webpacker.yml`:
 
-- https://webpack.js.org/configuration/dev-server/#devserver-hot
+```yaml
+development:
+  # ...
+  dev_server:
+    # ...
+    hmr: true
+    inline: true
+    # ...
+```
 
-To support HMR with React you would need to add `react-hot-loader`. Checkout this guide for
-more information:
+`dev_server/hmr` option inside `webpacker.yml`.
 
-- https://gaearon.github.io/react-hot-loader/getstarted/
+Check out this guide for more information:
 
-**Note:** Don't forget to disable `HMR` if you are not running `webpack-dev-server`
-otherwise you will get not found error for stylesheets.
+- https://webpack.js.org/configuration/dev-server/#devserver-hot
 
+To support HMR with React, see [docs/react.md](./react.md#hmr-and-react-hot-reloading).
 
 ## Nginx
 
@@ -77,9 +80,8 @@ server {
 ## Customizing Logging
 
 By default, the dev server will display a colored progress notification while
-your code is being compiled.  (Under the hood, we are using `webpack-dev-server
---progress --color`).  However, this might cause issues if you don't use
-`foreman` and/or try to log webpack-dev-server's output to a file.  You can
+your code is being compiled. (Under the hood, we are using `webpack-dev-server --progress --color`). However, this might cause issues if you don't use
+`foreman` and/or try to log webpack-dev-server's output to a file. You can
 disable this stylized output by adding `pretty: false` to your `dev_server`
 config:
 

data/docs/webpack.md

@@ -14,6 +14,7 @@ if you do need to customize or add a new loader, this is where you would go.
 
 Here is how you can modify webpack configuration:
 
+You might add separate files to keep your code more organized.
 ```js
 // config/webpack/custom.js
 module.exports = {
@@ -27,7 +28,11 @@ module.exports = {
     }
   }
 }
+```
+
+Then `require` this file in your `config/webpack/environment.js`:
 
+```js
 // config/webpack/environment.js
 const { environment } = require('@rails/webpacker')
 const customConfig = require('./custom')
@@ -38,6 +43,8 @@ environment.config.set('output.filename', '[name].js')
 
 // Merge custom config
 environment.config.merge(customConfig)
+
+// Merge other options
 environment.config.merge({ devtool: 'none' })
 
 // Delete a property
@@ -59,36 +66,36 @@ console.log(config.source_path)
 ## Loaders
 
 You can add additional loaders beyond the base set that Webpacker provides by
-adding it to your environment. We'll use `json-loader` as an example:
+adding it to your environment. We'll use `url-loader` as an example:
 
 ```
-yarn add json-loader
+yarn add url-loader
 ```
 
 ```js
 // config/webpack/environment.js
 const { environment } = require('@rails/webpacker')
 
-const jsonLoader = {
-  test: /\.json$/,
-  use: 'json-loader'
+const urlLoader = {
+  test: /\.png$/,
+  use: 'url-loader'
 }
 
-// Insert json loader at the end of list
-environment.loaders.append('json', jsonLoader)
+// Insert url loader at the end of list
+environment.loaders.append('url', urlLoader)
 
-// Insert json loader at the top of list
-environment.loaders.prepend('json', jsonLoader)
+// Insert url loader at the top of list
+environment.loaders.prepend('url', urlLoader)
 
-// Insert json loader after/before a given loader
-environment.loaders.insert('json', jsonLoader, { after: 'style'} )
-environment.loaders.insert('json', jsonLoader, { before: 'babel'} )
+// Insert url loader after/before a given loader
+environment.loaders.insert('url', urlLoader, { after: 'style'} )
+environment.loaders.insert('url', urlLoader, { before: 'babel'} )
 
 module.exports = environment
 ```
 
-Finally add `.json` to the list of extensions in `config/webpacker.yml`. Now if you `import()` any `.json` files inside your JavaScript
-they will be processed using `json-loader`. Voila!
+Finally, add `.png` to the list of extensions in `config/webpacker.yml`. Now if you `import()` any `.png` files inside your JavaScript
+they will be processed using `url-loader`. Voila!
 
 You can also modify the loaders that Webpacker pre-configures for you. We'll update
 the `babel` loader as an example:
@@ -132,6 +139,7 @@ module.exports = environment
 To use react svg loader, you should append svg loader before file loader:
 
 ```js
+// config/webpack/environment.js
 const { environment } = require('@rails/webpacker')
 
 const babelLoader = environment.loaders.get('babel')
@@ -155,61 +163,31 @@ fileLoader.exclude = /\.(svg)$/i
 
 ### Url Loader
 
+Be sure to add the default options from the file loader, as those are applied with the file loader if the size is greater than the `limit`.
+
 ```js
-// config/webpack/loaders/url.js
+// config/webpack/environment.js
 
-module.exports = {
+const { environment } = require('@rails/webpacker');
+const rules = environment.loaders;
+
+const urlFileSizeCutover = 10000;
+const urlLoaderOptions = Object.assign({ limit: urlFileSizeCutover }, fileLoader.use[0].options);
+const urlLoader = {
   test: [/\.bmp$/, /\.gif$/, /\.jpe?g$/, /\.png$/],
-  use: [{
+  use: {
     loader: 'url-loader',
-    options: {
-      limit: 10000,
-      name: '[name]-[hash].[ext]'
-    }
-  }]
-}
-
-// config/webpack/environment.js
-
-const { environment } = require('@rails/webpacker')
-const url = require('./loaders/url')
+    options: urlLoaderOptions,
+  },
+};
 
-environment.loaders.prepend('url', url)
+environment.loaders.prepend('url', urlLoader)
 
 // avoid using both file and url loaders
+// Note, this list should take into account the config value for static_assets_extensions
 environment.loaders.get('file').test = /\.(tiff|ico|svg|eot|otf|ttf|woff|woff2)$/i
 ```
 
-### 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:
-
-```javascript
-const { environment } = require('@rails/webpacker')
-const merge = require('webpack-merge')
-
-const myCssLoaderOptions = {
-  modules: {
-    localIdentName: '[name]__[local]___[hash:base64:5]'
-  },
-  sourceMap: true,
-}
-
-const CSSLoader = environment.loaders.get('sass').use.find(el => el.loader === 'css-loader')
-
-CSSLoader.options = merge(CSSLoader.options, myCssLoaderOptions)
-
-module.exports = environment
-```
-
-See [issue #756](https://github.com/rails/webpacker/issues/756#issuecomment-327148547) for additional discussion of this.
-
-For this to work, don't forget to use the `stylesheet_pack_tag`, for example:
-
-```
-<%= stylesheet_pack_tag 'YOUR_PACK_NAME_HERE' %>
-```
-
 ## Plugins
 
 The process for adding or modifying webpack plugins is the same as the process
@@ -239,14 +217,6 @@ environment.plugins.prepend(
   })
 )
 
-// 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
 ```
 
@@ -261,7 +231,7 @@ const { environment } = require('@rails/webpacker')
 environment.resolvedModules.append('vendor', 'vendor')
 ```
 
-### Add SplitChunks (Webpack V4)
+### Add SplitChunks (Webpack V4+)
 Originally, chunks (and modules imported inside them) were connected by a parent-child relationship in the internal webpack graph. The CommonsChunkPlugin was used to avoid duplicated dependencies across them, but further optimizations were not possible.
 
 Since webpack v4, the CommonsChunkPlugin was removed in favor of optimization.splitChunks.
@@ -303,8 +273,6 @@ get duplicated chunks on the page.
 <%= javascript_packs_with_chunks_tag 'map' %>
 ```
 
-For the old configuration with the CommonsChunkPlugin see below. **Note** that this functionality is deprecated in Webpack V4.
-
 #### Preloading
 
 Before preload or prefetch your assets, please read [https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content](https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content).
@@ -319,46 +287,29 @@ You can preload your assets with the `preload_pack_asset` helper if you have Rai
 
 **Warning:** You don't want to preload the css, you want to preload the fonts and images inside the css so that fonts, css, and images can all be downloaded in parallel instead of waiting for the browser to parse the css.
 
-### Add common chunks (deprecated in Webpack V4)
-
-The CommonsChunkPlugin is an opt-in feature that creates a separate file (known as a chunk), consisting of common modules shared between multiple entry points. By separating common modules from bundles, the resulting chunked file can be loaded once initially, and stored in the cache for later use. This results in page speed optimizations as the browser can quickly serve the shared code from the cache, rather than being forced to load a larger bundle whenever a new page is visited.
-
-Add the plugins in `config/webpack/environment.js`:
-
-```js
-const webpack = require('webpack')
-
-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
-    }
-  })
-)
-
-environment.plugins.append(
-  'CommonsChunkManifest',
-  new webpack.optimize.CommonsChunkPlugin({
-    name: 'manifest',
-    minChunks: Infinity
-  })
-)
-```
+More detailed guides available here: [webpack guides](https://webpack.js.org/guides/)
 
-Now, add these files to your `layouts/application.html.erb`:
+## Webpack Multi-Compiler and Server-Side Rendering
+You can export an Array of Object to have both `bin/webpack` and `bin/webpack-dev-server`
+use multiple configurations. This is commonly done for React server-side rendering (SSR).
 
-```erb
-<%# Head %>
+For an example of this, see the configuration within the [`/config/webpack` dir of the React on Rails Example](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/config/webpack).
 
-<%= javascript_pack_tag "manifest" %>
-<%= javascript_pack_tag "vendor" %>
+Take special care in that you need to make a deep copy of the output from the the basic "client" configuration.
 
-<%# If importing any styles from node_modules in your JS app %>
+In the example below, you _cannot_ modify the clientConfigObject as that would mutate the "environment" that is global.
 
-<%= stylesheet_pack_tag "vendor" %>
+```js
+  const environment = require('./environment');
+  
+  // make a deep copy
+  const clientConfigObject = environment.toWebpackConfig();
+  const serverWebpackConfig = merge({}, clientConfigObject);
+  
+  // make whatever changes you want for the serverWebpackConfig
+  
+  // No splitting of chunks for a server bundle
+  serverWebpackConfig.optimization = {
+    minimize: false,
+  };
 ```
-
-More detailed guides available here: [webpack guides](https://webpack.js.org/guides/)