webpacker 5.1.0 → 6.0.0.pre.2

data/docs/integrations.md

@@ -91,7 +91,7 @@ You can read more about this in the [Vue docs](https://vuejs.org/v2/guide/instal
 
 ### Lazy loading integration
 
-See [docs/es6](docs/es6.md) to know more about Webpack and Webpacker configuration.
+See [docs/es6](es6.md) to know more about Webpack and Webpacker configuration.
 
 For instance, you can lazy load Vue JS components:
 
@@ -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/target.md

@@ -0,0 +1,22 @@
+# Target browsers
+
+By default webpacker provides these front-end tools:
+- [@babel/preset-env](https://github.com/babel/babel/tree/master/packages/babel-preset-env)
+- [Autoprefixer](https://github.com/postcss/autoprefixer)
+- [postcss-preset-env](https://github.com/csstools/postcss-preset-env)
+
+All these tools use [Browserslist](https://github.com/browserslist/browserslist) to detect which environment your users have
+
+Webpacker browserslist default target:
+```
+defaults
+```
+
+`defaults`: `(> 0.5%, last 2 versions, Firefox ESR, not dead)`, [browserl.ist](https://browserl.ist/) is an online tool to check what browsers will be selected by some query.
+
+To keep browsers data up to date, you need to run:
+```bash
+yarn upgrade caniuse-lite
+```
+
+at least once every few months, to prevent such [problems](https://github.com/browserslist/browserslist/issues/492)

data/docs/testing.md

@@ -32,7 +32,7 @@ It is beneficial to use the same webpack configuration file (generated by webpac
 ```js
 // config/webpack/test.js
 const environment = require('./environment')
-environment.plugins.get('Manifest').opts.writeToFileEmit = process.env.NODE_ENV !== 'test'
+environment.plugins.get('Manifest').options.writeToFileEmit = process.env.NODE_ENV !== 'test'
 environment.loaders.append('istanbul-instrumenter', {
   test: /\.ts$/,
   enforce: "post",
@@ -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/troubleshooting.md

@@ -4,11 +4,13 @@
 
 1. Read the error message carefully. The error message will tell you the precise key value
    that is not matching what Webpack expects.
-2. Put a `debugger` statement in your Webpack configuration and run `bin/webpack --debug`.
+2. Put a `debugger` statement in your Webpack configuration and run `bin/webpack --debug-webpacker`.
    If you have a node debugger installed, you'll see the Chrome debugger for your webpack
    config. For example, install the Chrome extension [NiM](https://chrome.google.com/webstore/detail/nodejs-v8-inspector-manag/gnhhdgbaldcilmgcpfddgdbkhjohddkj) and
    set the option for the dev tools to open automatically. For more details on debugging,
    see the official [Webpack docs on debugging](https://webpack.js.org/contribute/debugging/#devtools)
+3. Any arguments that you add to bin/webpack get sent to webpack. For example, you can pass `--debug` to switch loaders to debug mode. See [webpack CLI debug options](https://webpack.js.org/api/cli/#debug-options) for more information on the available options.
+4. You can also pass additional options to the command to run the webpack-dev-server and start the webpack-dev-server with the option `--debug-webpacker`
 
 ## ENOENT: no such file or directory - node-sass
 

data/docs/typescript.md

@@ -1,18 +1,98 @@
-# Typescript
+# TypeScript
 
+## Installation
 
-## Typescript with React
+1. Run the TypeScript installer
 
-1. Setup react using Webpacker [react installer](../README.md#react). Then run the typescript installer
+```bash
+bundle exec rails webpacker:install:typescript
+```
+
+After that, a new file called `hello_typescript.ts` will be present in your `packs` directory (or rather the `source_entry_path` of your `webpacker.yml` configuration). You're now ready to write TypeScript. 
+
+## (Optional) Adding Compile-Time Type Checking
+
+The default installation only transpiles your TypeScript code using Babel. If you would like to enable type checking as part of the Webpack compilation process (i.e. fail the build if there are TS errors), you can do the following:
+
+1. Install the Fork TS Checker Webpack Plugin
+
+    ```sh
+    yarn add --dev fork-ts-checker-webpack-plugin
+    ```
+
+2. Then add it to your development environment config in `config/webpack/development.js`
+
+    ```js
+    const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
+    const path = require("path");
+
+    environment.plugins.append(
+      "ForkTsCheckerWebpackPlugin",
+      new ForkTsCheckerWebpackPlugin({
+        typescript: {
+          configFile: path.resolve(__dirname, "../../tsconfig.json"),
+        },
+        async: false,
+      })
+    );
+    ```
+
+    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");
+    const path = require("path");
+
+    environment.plugins.append(
+      "ForkTsCheckerWebpackPlugin",
+      new ForkTsCheckerWebpackPlugin({
+        // this is a relative path to your project's TypeScript config
+        tsconfig: path.resolve(__dirname, "../../tsconfig.json"),
+        // non-async so type checking will block compilation
+        async: false,
+      })
+    );
+    ```
+
+## Upgrading to 5.1
+
+If you update your App to `webpacker >= 5.1` and had TypeScript installed before, you need to add some new/remove some old configurations:
+
+1. Remove old packages:
+    - `yarn remove ts-loader`
+
+2. Add new packages:
+    - `yarn add @babel/preset-typescript`
+
+3. Remove old configuration files: 
+    - Delete this file: `config/webpack/loaders/typescript.js`
+
+4. Remove the following lines from `config/webpack/environment.js`:
+    - `const typescript = require('./loaders/typescript')`
+    - `environment.loaders.prepend('typescript', typescript)`
+
+5. Add the TypeScript preset to your `babel.config.js`:
+    - This line `['@babel/preset-typescript', { 'allExtensions': true, 'isTSX': true }]` has to be added as the last item to the `presets` array in your `babel.config.js`
+
+### Upgrading to 5.1 for Vue users
+
+1. Remove old packages:
+    - `yarn remove ts-loader pnp-webpack-plugin`
+
+2. Follow point 3 and 4 from the `TypeScript with Vue components` section
+
+## TypeScript with React
+
+1. Setup react using Webpacker [react installer](integrations.md#react). Then run the TypeScript installer
 
 ```bash
 bundle exec rails webpacker:install:typescript
 ```
 
-2. Rename the generated `hello_react.js` to `hello_react.tsx`. Make the file valid typescript and
-now you can use typescript, JSX with React.
+2. Rename the generated `hello_react.js` to `hello_react.tsx`. Make the file valid TypeScript and
+now you can use TypeScript, JSX with React.
 
-## Typescript with Vue components
+## TypeScript with Vue components
 
 1. Setup Vue using the Webpacker [Vue installer](../README.md#vue). Then run the TypeScript installer
 
@@ -21,7 +101,8 @@ bundle exec rails webpacker:install:typescript
 ```
 
 2. Rename generated `hello_vue.js` to `hello_vue.ts`.
-3. Change the generated `babel.config.js` from
+3. Install the right Babel preset: `yarn add babel-preset-typescript-vue`
+4. Change the generated `babel.config.js` from
 
 ```js
 ["@babel/preset-typescript", { "allExtensions": true, "isTSX": true }]
@@ -35,7 +116,7 @@ to
 
 and now you can use `<script lang="ts">` in your `.vue` component files. See [the babel-preset-typescript-vue docs](https://www.npmjs.com/package/babel-preset-typescript-vue) for more info.
 
-## HTML templates with Typescript and Angular
+## HTML templates with TypeScript and Angular
 
 After you have installed Angular using `bundle exec rails webpacker:install:angular`
 you would need to follow these steps to add HTML templates support:

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