From b5570efa2950237e513074c12f13434afa4896b3 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Mon, 21 Jan 2019 19:36:34 -0700 Subject: [PATCH 1/5] Add a Webpacker v4 Upgrade Guide to docs. Credit to @justin808 for the original v4 upgrade guide this is based on. --- docs/v4-upgrade.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 docs/v4-upgrade.md diff --git a/docs/v4-upgrade.md b/docs/v4-upgrade.md new file mode 100644 index 000000000..dc035b871 --- /dev/null +++ b/docs/v4-upgrade.md @@ -0,0 +1,18 @@ +To update a Webpacker v3.5 app to v4, follow these steps: + +1. Update the `webpacker` gem and the `@rails/webpacker` package to v4. This will upgrade webpack itself from 3.x to 4.x, make sure you're aware of [any deprecations which might effect you](https://webpack.js.org/migrate/4/). Also make sure any other packages you depend on support webpack 4 and don't require any changes, e.g. if you explicitly include `webpack` you need to upgrade it to 4.x, and if you use `webpack-dev-server` you need to upgrade it to 3.x. +1. Browser support definitions have been moved to [`.browserslistrc`](../lib/install/config/.browserslistrc) to `/`. +1. Merge any differences between [`config/webpacker.yml`](../lib/install/config/webpacker.yml) and your `config/webpacker.yml`. +1. Webpacker v4 upgrades Babel to [v7](https://babeljs.io/docs/en/v7-migration), see also [the release blog post](https://babeljs.io/blog/2018/08/27/7.0.0). Many packages were moved to the `@babel/` namespace, any babel plugins you have will need to be updated. It may be worth checking out [babel-upgrade](https://github.com/babel/babel-upgrade) if you have problems. ([#1564](https://github.com/rails/webpacker/pull/1564)) +1. `.babelrc` should be replaced with `babel.config.js` and `.postcssrc.yml` should be replaced with `postcss.config.js` ([#1822](https://github.com/rails/webpacker/pull/1822)). If you never changed these files from their defaults, the versions of [babel.config.js](../lib/install/config/babel.config.js) and [postcss.config.js](../lib/install/config/postcss.config.js) in the webpacker repository should be usable. +1. Due to the change in [#1625](https://github.com/rails/webpacker/pull/1625), you'll want to make sure that `extract_css` is set to true for the `default` environment in `webpacker.yml` if you want to have Webpacker supply your CSS. + +Package-specific notes: + +- If you're using React, you need to add `"@babel/preset-react"`, to the list of `presets` in your babel config. +- If you're using Vue Loader, you'll need to upgrade to [v15](https://vue-loader.vuejs.org/migrating.html) for webpack 4. +- To see what webpacker generates for a given framework with v4, you may want to re-run `bundle exec rake webpacker:install:FRAMEWORK` and let it override the files for your given JavaScript framework, and then compare them to see what changes you'll need to make. + +This is what an upgrade to Webpacker 4 looked like for existing Rails apps (please contribute yours!): + +- https://github.com/connorshea/ContinueFromCheckpoint/pull/77 From 1e0add35725da92c76e4ae1be40073ed07d50225 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Mon, 21 Jan 2019 20:13:15 -0700 Subject: [PATCH 2/5] Add a section on the splitChunks change. --- docs/v4-upgrade.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/v4-upgrade.md b/docs/v4-upgrade.md index dc035b871..ed534ab8e 100644 --- a/docs/v4-upgrade.md +++ b/docs/v4-upgrade.md @@ -7,6 +7,43 @@ To update a Webpacker v3.5 app to v4, follow these steps: 1. `.babelrc` should be replaced with `babel.config.js` and `.postcssrc.yml` should be replaced with `postcss.config.js` ([#1822](https://github.com/rails/webpacker/pull/1822)). If you never changed these files from their defaults, the versions of [babel.config.js](../lib/install/config/babel.config.js) and [postcss.config.js](../lib/install/config/postcss.config.js) in the webpacker repository should be usable. 1. Due to the change in [#1625](https://github.com/rails/webpacker/pull/1625), you'll want to make sure that `extract_css` is set to true for the `default` environment in `webpacker.yml` if you want to have Webpacker supply your CSS. +If you're using split chunks, pay special attention to the [`CommonsChunkPlugin` removal in Webpack 4](https://webpack.js.org/migrate/4/#commonschunkplugin) ([This gist](https://gist.github.com/sokra/1522d586b8e5c0f5072d7565c2bee693) may also be useful for upgrading). + +Where previously you'd have code like this: + +```js +environment.plugins.append( + 'CommonsChunk', + new CommonsChunkPlugin({ + name: 'something-vendor', + chunks: ['something'], + minChunks(module) { + return module.context && module.context.includes('node_modules'); + }, + }), +); +``` + +It would now be more like: + +```js +environment.config.optimization.splitChunks = { + cacheGroups: { + vendor: { + name: 'something-vendor', + chunks: chunk => chunk.name === something', + reuseExistingChunk: true, + priority: 1, + test: /[\\/]node_modules[\\/]/, + minChunks: 1, + minSize: 0, + }, + }, +}; +``` + +When using the new Webpack 4 `splitChunks` API, also consider using the `javascript_packs_with_chunks_tag` and `stylesheet_packs_with_chunks_tag` helpers, which create HTML tags for the packs and all its dependent chunks. + Package-specific notes: - If you're using React, you need to add `"@babel/preset-react"`, to the list of `presets` in your babel config. From 5d913b8600efa85b7ff72c171bf6b0f054d13919 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Mon, 21 Jan 2019 20:16:25 -0700 Subject: [PATCH 3/5] Fix syntax error in JavaScript code example. --- docs/v4-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v4-upgrade.md b/docs/v4-upgrade.md index ed534ab8e..7c71c45a6 100644 --- a/docs/v4-upgrade.md +++ b/docs/v4-upgrade.md @@ -31,7 +31,7 @@ environment.config.optimization.splitChunks = { cacheGroups: { vendor: { name: 'something-vendor', - chunks: chunk => chunk.name === something', + chunks: chunk => chunk.name === 'something', reuseExistingChunk: true, priority: 1, test: /[\\/]node_modules[\\/]/, From 0225b602479c2030abacc7b306f050540f8e7a2c Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Mon, 21 Jan 2019 20:25:27 -0700 Subject: [PATCH 4/5] Add link to splitChunks plugin docs. --- docs/v4-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v4-upgrade.md b/docs/v4-upgrade.md index 7c71c45a6..c78046864 100644 --- a/docs/v4-upgrade.md +++ b/docs/v4-upgrade.md @@ -42,7 +42,7 @@ environment.config.optimization.splitChunks = { }; ``` -When using the new Webpack 4 `splitChunks` API, also consider using the `javascript_packs_with_chunks_tag` and `stylesheet_packs_with_chunks_tag` helpers, which create HTML tags for the packs and all its dependent chunks. +When using the new Webpack 4 [`splitChunks` API](https://webpack.js.org/plugins/split-chunks-plugin/), also consider using the `javascript_packs_with_chunks_tag` and `stylesheet_packs_with_chunks_tag` helpers, which create HTML tags for the packs and all its dependent chunks. Package-specific notes: From c97d343f60f8f13ac4e52a9110e6c3d6f4cfe8c0 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Tue, 22 Jan 2019 17:52:49 -0700 Subject: [PATCH 5/5] Replace splitChunks section. --- docs/v4-upgrade.md | 70 +++++++++++++++++++++++++++------------------- 1 file changed, 41 insertions(+), 29 deletions(-) diff --git a/docs/v4-upgrade.md b/docs/v4-upgrade.md index c78046864..7e63868ff 100644 --- a/docs/v4-upgrade.md +++ b/docs/v4-upgrade.md @@ -7,49 +7,61 @@ To update a Webpacker v3.5 app to v4, follow these steps: 1. `.babelrc` should be replaced with `babel.config.js` and `.postcssrc.yml` should be replaced with `postcss.config.js` ([#1822](https://github.com/rails/webpacker/pull/1822)). If you never changed these files from their defaults, the versions of [babel.config.js](../lib/install/config/babel.config.js) and [postcss.config.js](../lib/install/config/postcss.config.js) in the webpacker repository should be usable. 1. Due to the change in [#1625](https://github.com/rails/webpacker/pull/1625), you'll want to make sure that `extract_css` is set to true for the `default` environment in `webpacker.yml` if you want to have Webpacker supply your CSS. -If you're using split chunks, pay special attention to the [`CommonsChunkPlugin` removal in Webpack 4](https://webpack.js.org/migrate/4/#commonschunkplugin) ([This gist](https://gist.github.com/sokra/1522d586b8e5c0f5072d7565c2bee693) may also be useful for upgrading). +### Add SplitChunks -Where previously you'd have code like this: +If you used the `CommonsChunkPlugin` you'll need to upgrade to using the new `splitChunks`. + +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. + +In webpack v4, `CommonsChunkPlugin` was removed in favor of `optimization.splitChunks`. + +For the full configuration options of `splitChunks`, see the [Webpack documentation](https://webpack.js.org/plugins/split-chunks-plugin/). ```js -environment.plugins.append( - 'CommonsChunk', - new CommonsChunkPlugin({ - name: 'something-vendor', - chunks: ['something'], - minChunks(module) { - return module.context && module.context.includes('node_modules'); - }, - }), -); +// config/webpack/environment.js +const WebpackAssetsManifest = require('webpack-assets-manifest'); + +// Enable the default config +environment.splitChunks() + +// or using custom config +environment.splitChunks((config) => Object.assign({}, config, { optimization: { splitChunks: false }})) ``` -It would now be more like: +Then use, `javascript_packs_with_chunks_tag` helper to include all the transpiled +packs with the chunks in your view, which creates html tags for all the chunks. -```js -environment.config.optimization.splitChunks = { - cacheGroups: { - vendor: { - name: 'something-vendor', - chunks: chunk => chunk.name === 'something', - reuseExistingChunk: true, - priority: 1, - test: /[\\/]node_modules[\\/]/, - minChunks: 1, - minSize: 0, - }, - }, -}; +```erb +<%= javascript_packs_with_chunks_tag 'calendar', 'map', 'data-turbolinks-track': 'reload' %> + + + + + + + ``` -When using the new Webpack 4 [`splitChunks` API](https://webpack.js.org/plugins/split-chunks-plugin/), also consider using the `javascript_packs_with_chunks_tag` and `stylesheet_packs_with_chunks_tag` helpers, which create HTML tags for the packs and all its dependent chunks. +**Important:** Pass all your pack names when using this helper otherwise you will +get duplicated chunks on the page. + +```erb +<%# DO %> +<%= javascript_packs_with_chunks_tag 'calendar', 'map' %> -Package-specific notes: +<%# DON'T %> +<%= javascript_packs_with_chunks_tag 'calendar' %> +<%= javascript_packs_with_chunks_tag 'map' %> +``` + +### Package-specific notes: - If you're using React, you need to add `"@babel/preset-react"`, to the list of `presets` in your babel config. - If you're using Vue Loader, you'll need to upgrade to [v15](https://vue-loader.vuejs.org/migrating.html) for webpack 4. - To see what webpacker generates for a given framework with v4, you may want to re-run `bundle exec rake webpacker:install:FRAMEWORK` and let it override the files for your given JavaScript framework, and then compare them to see what changes you'll need to make. +### Example upgrades + This is what an upgrade to Webpacker 4 looked like for existing Rails apps (please contribute yours!): - https://github.com/connorshea/ContinueFromCheckpoint/pull/77