From dca9d9a18ea821f27108a592b1775936076205d1 Mon Sep 17 00:00:00 2001 From: Eli Perelman Date: Thu, 13 Sep 2018 14:56:28 -0500 Subject: [PATCH 1/4] Initial migration guide for v8 to v9 --- docs/migration-guide.md | 185 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 0a70355e8..771168e3e 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -2,11 +2,196 @@ ## Contents +- [Neutrino v8 to v9](#neutrino-v8-to-v9) - [Neutrino v7 to v8](#neutrino-v7-to-v8) - [Neutrino v6 to v7](#neutrino-v6-to-v7) - [Neutrino v5 to v6](#neutrino-v5-to-v6) - [Neutrino v4 to v5](#neutrino-v4-to-v5) +## Neutrino v8 to v9 + +Neutrino v9 is our largest release ever, bringing the preset and middleware ecosystem back to the +native tools and utilities for which they were originally created. The biggest breaking change +is the necessity to use external tools *alongside* Neutrino now, i.e. webpack, ESLint, Jest, Karma, +and others' native CLIs will be used in tandem with Neutrino. A list of changes is detailed below for +migrating: + +- **BREAKING CHANGE** The minimum supported Node.js version is v8.3. Node.js v9 is no longer supported +[#792](https://github.com/neutrinojs/neutrino/pull/792). +- **BREAKING CHANGE** Consumption of middleware and presets are now dependent on the external CLIs and +configuration files for which they are intended [#852](https://github.com/neutrinojs/neutrino/pull/852). +This does not negate the need for a `.neutrinorc.js` file +in your projects, but rather is the configuration format for declaring all the middleware for a project. As +an example, using the `@neutrinojs/react` preset also requires an installation of `webpack`, +`webpack-dev-server`, and `webpack-cli`. You can then add a `webpack.config.js` file to the project which +will tell webpack to use the Neutrino middleware to load its configuration: + +```js +// webpack.config.js +const neutrino = require('neutrino'); + +module.exports = neutrino().webpack(); +``` + +Or for ESLint: + +```js +// .eslintrc.js +const neutrino = require('neutrino'); + +module.exports = neutrino().eslintrc(); +``` + +- **BREAKING CHANGE** With the necessity of external CLIs means the removal of most of the Neutrino CLI's +commands [#852](https://github.com/neutrinojs/neutrino/pull/852): + - `neutrino build` can typically be replaced with `webpack --mode production`. + - `neutrino start` can typically be replaced with `webpack-dev-server --mode development`. + - `neutrino test` can typically be replaced with the CLI of your test runner, e.g. `jest` or `karma`. + - `neutrino lint` can typically be replaced with `eslint --cache --ext mjs,vue,jsx,js src`. + - `neutrino --inspect` command still exists to get information about the configuration that Neutrino will use. +- **BREAKING CHANGE** The `@neutrinojs/fork` middleware has been removed +[#852](https://github.com/neutrinojs/neutrino/pull/852). Either call webpack with separate configuration files +calling out to Neutrino, or export multiple configurations from your `webpack.config.js` file: + +```js +// webpack.config.js +const neutrino = require('neutrino'); + +module.exports = [ + // first build configuration + neutrino().webpack(), + + // second build configuration + neutrino().webpack(config => ({ + ...config, + devtool: 'source-map', + })) +]; +``` + +- **BREAKING CHANGE** You can no longer define an `env` section in `.neutrinorc.js` configuration. +In order to make environment-specific changes, conditionally define middleware or configuration +overrides using environment variable values [#852](https://github.com/neutrinojs/neutrino/pull/852): + +```js +// .neutrinorc.js +module.exports = { + use: [ + '@neutrinojs/react', + (neutrino) => { + if (process.env.NODE_ENV === 'test') { + neutrino.use('neutrino-preset-example'); + } + } + ] +} +``` + +- **BREAKING CHANGE** Using a test middleware with no `NODE_ENV` set will set `process.env.NODE_ENV` +to `test` by default [#972](https://github.com/neutrinojs/neutrino/pull/972). +- **BREAKING CHANGE** Upgraded to latest major versions of webpack, webpack-dev-server, and related +packages [#809](https://github.com/neutrinojs/neutrino/pull/809). +- **BREAKING CHANGE** The `@neutrinojs/chunk` middleware has been removed in favor of webpack's +improved functionality around `splitChunks` [#809](https://github.com/neutrinojs/neutrino/pull/809). +- **BREAKING CHANGE** The `@neutrinojs/babel-minify` preset has been removed in favor of the much faster +uglify-es built into webpack 4 [#809](https://github.com/neutrinojs/neutrino/pull/809). +- **BREAKING CHANGE** The `@neutrinojs/web` and dependent presets have renamed the `minify.babel` option +to `minify.source` [#809](https://github.com/neutrinojs/neutrino/pull/809). +- **BREAKING CHANGE** The `@neutrinojs/web` and dependent presets no longer include the +`@neutrinojs/image-minify` or `@neutrinojs/style-minify` middleware. This means there are no preset +options for `minify.image` and `minify.style` [#809](https://github.com/neutrinojs/neutrino/pull/809). +- **BREAKING CHANGE** The `@neutrinojs/minify` package has been removed. The individual minification +middleware packages can be used instead [#809](https://github.com/neutrinojs/neutrino/pull/809). +- **BREAKING CHANGE** The `@neutrinojs/react` and `@neutrinojs/preact` packages no longer use +`babel-plugin-jsx-pragmatic` [#827](https://github.com/neutrinojs/neutrino/pull/827). This means if you +did not import React or preact into your files using JSX, you will now need to import these packages +explicitly when using JSX. + +```diff +- import { Component } from 'react'; ++ import React, { Component } from 'react'; +``` + +- **BREAKING CHANGE** `@neutrinojs/react` will now use the react-hot-loader v4 peerDependency when installed +in your app [#902](https://github.com/neutrinojs/neutrino/pull/902). See +https://github.com/gaearon/react-hot-loader#migrating-from-v3 for instructions on upgrading +to RHL v4 while installing it into your project also. +- **BREAKING CHANGE** `@neutrinojs/web`, `@neutrinojs/node`, and their dependent presets no longer configure +defaults for copying static files at build time [#814](https://github.com/neutrinojs/neutrino/pull/814). +Use the `@neutrinojs/copy` middleware to configure this for v9. +- **BREAKING CHANGE** Babel has been upgraded from v6 to v7 [#845](https://github.com/neutrinojs/neutrino/pull/809). +Any additional Babel plugins and presets you use in your projects should be compatible with Babel v7 if +they are still necessary. +- **BREAKING CHANGE** The fast-async Babel plugin is no longer used, so async functions will not be de-sugared +to Promises by default any more [#790](https://github.com/neutrinojs/neutrino/pull/790). This means the preset option +of `polyfills.async` has been removed. +- **BREAKING CHANGE** The output format from `neutrino --inspect` has changed and is equivalent to the +`neutrino --inspect-new` in Neutrino v8 [#928](https://github.com/neutrinojs/neutrino/pull/928). +- **BREAKING CHANGE** The length of hashes in built filenames has been shortened to 8 characters +[#930](https://github.com/neutrinojs/neutrino/pull/930). This will +cause unchanged files to invalidate caches and if you use regex rules to manage web server caches, those must be +updated. +- **BREAKING CHANGE** Module resolution now uses the webpack 4 defaults +[#926](https://github.com/neutrinojs/neutrino/pull/926). This means that the option `neutrino.options.node_modules` +has been removed. +- **BREAKING CHANGE** The font and image loader rules have now been consolidated into a single rule for +`@neutrinojs/font-loader` and another for `@neutrinojs/image-loader` [#858](https://github.com/neutrinojs/neutrino/pull/858). +- **BREAKING CHANGE** `@neutrinojs/font-loader` now uses `file-loader` instead of `url-loader` +[#858](https://github.com/neutrinojs/neutrino/pull/858). This prevents asset inlining and will always generate +separate files. +- **BREAKING CHANGE** `@neutrinojs/style-loader` now uses `mini-css-extract-plugin` instead of +`extract-text-webpack-plugin` [#809](https://github.com/neutrinojs/neutrino/pull/809). This means any options you +may have passed for `options.extract.plugin` must be updated for the new plugin. +- **BREAKING CHANGE** `@neutrinojs/compile-loader` now sets the `babelrc` option to `false` +[#826](https://github.com/neutrinojs/neutrino/pull/858). If you wish to force specifying additional Babel +configuration via a configuration file, you can set it to `true` via `babel: { babelrc: true }`. +- **BREAKING CHANGE** `@neutrinojs/eslint` and dependent middleware now throw if they are used by Neutrino after +a compile preset [#839](https://github.com/neutrinojs/neutrino/pull/939). This is to prevent using an unknowingly +broken configuration. +- **BREAKING CHANGE** The `@neutrinojs/mocha` preset no longer accepts middleware options as Mocha's CLI does not +allow providing an options file which can call out to Neutrino to load middleware +[#852](https://github.com/neutrinojs/neutrino/pull/852). Manually pass any Mocha options to a `mocha.opts` file or +via the command line flags. +- **BREAKING CHANGE** As Neutrino no longer supplies a CLI for executing project commands, the `--debug` flag no +longer exists [#852](https://github.com/neutrinojs/neutrino/pull/852). You can still output debug information for +middleware in your `.neutrinorc.js` with: + +```js +module.exports = { + options: { + debug: true + } +}; +``` + +- **BREAKING CHANGE** `@neutrinojs/html-loader` used by the web-related presets now parse URLs defined in link tags +in the HTML template [#943](https://github.com/neutrinojs/neutrino/pull/943). +- **BREAKING CHANGE** The `@neutrinojs/hot` [#981](https://github.com/neutrinojs/neutrino/pull/981) and `@neutrinojs/env` +[#983](https://github.com/neutrinojs/neutrino/pull/983) middleware have been removed and their relevant +functionality is now configured directly by its previously-consuming presets. +- **BREAKING CHANGE** `@neutrinojs/node` now compiles to the supported version of Node.js being used to run the build +[#991](https://github.com/neutrinojs/neutrino/pull/991). Previously this was always defaulted to a particular Node.js v6 +version. For example, if you use Node.js v8 to run webpack, Neutrino will tell Babel to compile your project to support +back to Node.js v8. +- **BREAKING CHANGE** Various build outputs and settings used by Neutrino were driven by the `NODE_ENV` environment +variable [#972](https://github.com/neutrinojs/neutrino/pull/972). How the environment variable drives some of these +options has changed and may cause output that is different than in v8. For example, sometimes output was controlled +when the value *was set to `development`*, but now may be done when the value *is not `production`*. +- **BREAKING CHANGE** The merging of Babel options has been updated to *not merge array options*, but instead +overwrite them [#1022](https://github.com/neutrinojs/neutrino/pull/1022). +- **BREAKING CHANGE** `@neutrinojs/eslint` and its dependent middleware now require ESLint v5, which may mean breaking +changes to rule configuration and any `parserOptions` modifications [#1025](https://github.com/neutrinojs/neutrino/pull/1025). +- **BREAKING CHANGE** The `options.mains` Neutrino option can now also accept an object per entry point for setting +individual options for html-webpack-plugin [#1029](https://github.com/neutrinojs/neutrino/pull/1029). The previous API +for setting these properties as strings is still supported. This also introduces a breaking API change as accessing an +entry point property on `neutrino.options.mains` now returns a normalized object, even when using string options. +- **BREAKING CHANGE** When configuring webpack with a target of `node` the `@neutrinojs/jest` preset will default its +`testEnvironment` to also be `node` instead of `jsdom` [#1030](https://github.com/neutrinojs/neutrino/pull/1030). +- **BREAKING CHANGE** Various dependencies have been updated which may bring their own breaking changes. Please +check and test your project to ensure proper functionality. +- ESLint caching is now enabled by default, so it is recommended to specify `.eslintcache` as being ignored from +your source control commits. + ## Neutrino v7 to v8 Neutrino v8 introduces a number of changes, with some of them being breaking changes. To upgrade from Neutrino v7 From ff206029a7ced2cc935a97f001c0d35cd43a4855 Mon Sep 17 00:00:00 2001 From: Eli Perelman Date: Mon, 17 Sep 2018 13:48:45 -0700 Subject: [PATCH 2/4] Update migration guide from review --- docs/migration-guide.md | 129 ++++++++++++++++++++++++++++++---------- 1 file changed, 98 insertions(+), 31 deletions(-) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 771168e3e..f873a9646 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -13,17 +13,46 @@ Neutrino v9 is our largest release ever, bringing the preset and middleware ecosystem back to the native tools and utilities for which they were originally created. The biggest breaking change is the necessity to use external tools *alongside* Neutrino now, i.e. webpack, ESLint, Jest, Karma, -and others' native CLIs will be used in tandem with Neutrino. A list of changes is detailed below for -migrating: +and others' native CLIs will be used in tandem with Neutrino. -- **BREAKING CHANGE** The minimum supported Node.js version is v8.3. Node.js v9 is no longer supported +To debug any difficulties in the upgrade process, you can run your respective Neutrino v8 command +with `--inspect-new` and compare it with the output of Neutrino v9's `--inspect` flag. For example, +to compare the difference between a v8 and v9 build, you can run respectively: + +```sh +# Output v8 configuration +neutrino build --inspect-new + +# Output v9 configuration +neutrino --inspect --mode production +``` + +You can also output these to files and `diff` them: + +```sh +# Output v8 configuration +neutrino build --inspect-new > v8.config + +# Output v9 configuration +neutrino --inspect --mode production > v9.config + +git diff --no-index v8.config v9.config +``` + +Please [file an issue](https://github.com/neutrinojs/neutrino/issues) if any issue arises from upgrade +that may not be outlined here. + +A list of changes is detailed below for migrating: + +- **BREAKING CHANGE** The minimum supported Node.js version is 8.10. Node.js 9 is no longer supported [#792](https://github.com/neutrinojs/neutrino/pull/792). - **BREAKING CHANGE** Consumption of middleware and presets are now dependent on the external CLIs and configuration files for which they are intended [#852](https://github.com/neutrinojs/neutrino/pull/852). This does not negate the need for a `.neutrinorc.js` file in your projects, but rather is the configuration format for declaring all the middleware for a project. As an example, using the `@neutrinojs/react` preset also requires an installation of `webpack`, -`webpack-dev-server`, and `webpack-cli`. You can then add a `webpack.config.js` file to the project which +`webpack-dev-server`, and `webpack-cli`. Refer to the updated package installation instructions on your +preset's documentation page. You must then also add a `webpack.config.js` file to the project which will tell webpack to use the Neutrino middleware to load its configuration: ```js @@ -37,6 +66,8 @@ Or for ESLint: ```js // .eslintrc.js +// NOTE: This format of .eslintrc.js is different than +// it was in Neutrino v8. const neutrino = require('neutrino'); module.exports = neutrino().eslintrc(); @@ -44,11 +75,17 @@ module.exports = neutrino().eslintrc(); - **BREAKING CHANGE** With the necessity of external CLIs means the removal of most of the Neutrino CLI's commands [#852](https://github.com/neutrinojs/neutrino/pull/852): - - `neutrino build` can typically be replaced with `webpack --mode production`. - - `neutrino start` can typically be replaced with `webpack-dev-server --mode development`. - - `neutrino test` can typically be replaced with the CLI of your test runner, e.g. `jest` or `karma`. - - `neutrino lint` can typically be replaced with `eslint --cache --ext mjs,vue,jsx,js src`. - - `neutrino --inspect` command still exists to get information about the configuration that Neutrino will use. + - `neutrino build` can typically be replaced with `webpack --mode production`. + - `neutrino start` can typically be replaced with `webpack-dev-server --mode development`. + - `neutrino test` can typically be replaced with the CLI of your test runner, + e.g. `jest`, `karma start --single-run`, or `mocha --require mocha.config.js --recursive`. + - `neutrino lint` can typically be replaced with `eslint --cache --ext mjs,vue,jsx,js src`. + - `neutrino --inspect` command still exists to get information about the configuration that Neutrino will use. +- **BREAKING CHANGE** With the removal of the Neutrino CLI and its `--use` flag, the `.neutrinorc.js` file for +setting middleware is now mandatory within a project. +- **BREAKING CHANGE** With the removal of the Neutrino CLI, many of the Neutrino API methods and functionality +were no longer needed. This includes removal of `neutrino.options.command.` See the updated Neutrino API docs +for updated information. - **BREAKING CHANGE** The `@neutrinojs/fork` middleware has been removed [#852](https://github.com/neutrinojs/neutrino/pull/852). Either call webpack with separate configuration files calling out to Neutrino, or export multiple configurations from your `webpack.config.js` file: @@ -60,15 +97,28 @@ const neutrino = require('neutrino'); module.exports = [ // first build configuration neutrino().webpack(), - + // second build configuration - neutrino().webpack(config => ({ - ...config, - devtool: 'source-map', - })) + { + ...neutrino().webpack(), + devtool: 'source-map' + }, ]; ``` +- **BREAKING CHANGE** The recommended method for setting Neutrino's `root` directory option has changed. +You should set this from your `.neutrinorc.js` file to have it apply to all external configuration files +[#1041](https://github.com/neutrinojs/neutrino/pull/1041). + +```js +// .neutrinorc.js +module.exports = { + options: { + root: __dirname + } +}; +``` + - **BREAKING CHANGE** You can no longer define an `env` section in `.neutrinorc.js` configuration. In order to make environment-specific changes, conditionally define middleware or configuration overrides using environment variable values [#852](https://github.com/neutrinojs/neutrino/pull/852): @@ -87,12 +137,12 @@ module.exports = { } ``` -- **BREAKING CHANGE** Using a test middleware with no `NODE_ENV` set will set `process.env.NODE_ENV` -to `test` by default [#972](https://github.com/neutrinojs/neutrino/pull/972). -- **BREAKING CHANGE** Upgraded to latest major versions of webpack, webpack-dev-server, and related -packages [#809](https://github.com/neutrinojs/neutrino/pull/809). +- **BREAKING CHANGE** Upgraded to latest major versions of webpack, webpack-dev-server, Babel 7, +ESLint 5, and related packages [#809](https://github.com/neutrinojs/neutrino/pull/809). - **BREAKING CHANGE** The `@neutrinojs/chunk` middleware has been removed in favor of webpack's -improved functionality around `splitChunks` [#809](https://github.com/neutrinojs/neutrino/pull/809). +improved functionality around `splitChunks` [#809](https://github.com/neutrinojs/neutrino/pull/809). See +https://webpack.js.org/plugins/split-chunks-plugin/ for more information. Usage of the `vendor` entry point +will now throw an error when used with v9. - **BREAKING CHANGE** The `@neutrinojs/babel-minify` preset has been removed in favor of the much faster uglify-es built into webpack 4 [#809](https://github.com/neutrinojs/neutrino/pull/809). - **BREAKING CHANGE** The `@neutrinojs/web` and dependent presets have renamed the `minify.babel` option @@ -114,7 +164,7 @@ explicitly when using JSX. - **BREAKING CHANGE** `@neutrinojs/react` will now use the react-hot-loader v4 peerDependency when installed in your app [#902](https://github.com/neutrinojs/neutrino/pull/902). See -https://github.com/gaearon/react-hot-loader#migrating-from-v3 for instructions on upgrading +[React Hot Loader migration](https://github.com/gaearon/react-hot-loader#migrating-from-v3) for instructions on upgrading to RHL v4 while installing it into your project also. - **BREAKING CHANGE** `@neutrinojs/web`, `@neutrinojs/node`, and their dependent presets no longer configure defaults for copying static files at build time [#814](https://github.com/neutrinojs/neutrino/pull/814). @@ -122,16 +172,16 @@ Use the `@neutrinojs/copy` middleware to configure this for v9. - **BREAKING CHANGE** Babel has been upgraded from v6 to v7 [#845](https://github.com/neutrinojs/neutrino/pull/809). Any additional Babel plugins and presets you use in your projects should be compatible with Babel v7 if they are still necessary. -- **BREAKING CHANGE** The fast-async Babel plugin is no longer used, so async functions will not be de-sugared -to Promises by default any more [#790](https://github.com/neutrinojs/neutrino/pull/790). This means the preset option -of `polyfills.async` has been removed. +- **BREAKING CHANGE** The [fast-async](https://github.com/MatAtBread/fast-async) Babel plugin is no longer used, +so async functions will not be de-sugared to Promises by default any more [#790](https://github.com/neutrinojs/neutrino/pull/790). +This means the preset option of `polyfills.async` has been removed. - **BREAKING CHANGE** The output format from `neutrino --inspect` has changed and is equivalent to the `neutrino --inspect-new` in Neutrino v8 [#928](https://github.com/neutrinojs/neutrino/pull/928). - **BREAKING CHANGE** The length of hashes in built filenames has been shortened to 8 characters [#930](https://github.com/neutrinojs/neutrino/pull/930). This will -cause unchanged files to invalidate caches and if you use regex rules to manage web server caches, those must be +cause potential hash changes for changed files and if you use regex rules to manage web server caches, those must be updated. -- **BREAKING CHANGE** Module resolution now uses the webpack 4 defaults +- **BREAKING CHANGE** Module resolution now uses the [webpack 4 defaults](https://webpack.js.org/configuration/resolve/#resolve-modules) [#926](https://github.com/neutrinojs/neutrino/pull/926). This means that the option `neutrino.options.node_modules` has been removed. - **BREAKING CHANGE** The font and image loader rules have now been consolidated into a single rule for @@ -139,9 +189,10 @@ has been removed. - **BREAKING CHANGE** `@neutrinojs/font-loader` now uses `file-loader` instead of `url-loader` [#858](https://github.com/neutrinojs/neutrino/pull/858). This prevents asset inlining and will always generate separate files. -- **BREAKING CHANGE** `@neutrinojs/style-loader` now uses `mini-css-extract-plugin` instead of -`extract-text-webpack-plugin` [#809](https://github.com/neutrinojs/neutrino/pull/809). This means any options you -may have passed for `options.extract.plugin` must be updated for the new plugin. +- **BREAKING CHANGE** `@neutrinojs/style-loader` now uses [`mini-css-extract-plugin`](https://webpack.js.org/plugins/mini-css-extract-plugin/) +instead of [`extract-text-webpack-plugin`](https://webpack.js.org/plugins/extract-text-webpack-plugin/) +[#809](https://github.com/neutrinojs/neutrino/pull/809). This means any options you may have passed for `options.extract.plugin` +must be updated for the new plugin. - **BREAKING CHANGE** `@neutrinojs/compile-loader` now sets the `babelrc` option to `false` [#826](https://github.com/neutrinojs/neutrino/pull/858). If you wish to force specifying additional Babel configuration via a configuration file, you can set it to `true` via `babel: { babelrc: true }`. @@ -150,8 +201,8 @@ a compile preset [#839](https://github.com/neutrinojs/neutrino/pull/939). This i broken configuration. - **BREAKING CHANGE** The `@neutrinojs/mocha` preset no longer accepts middleware options as Mocha's CLI does not allow providing an options file which can call out to Neutrino to load middleware -[#852](https://github.com/neutrinojs/neutrino/pull/852). Manually pass any Mocha options to a `mocha.opts` file or -via the command line flags. +[#852](https://github.com/neutrinojs/neutrino/pull/852). Manually pass any Mocha options to a [`mocha.opts`](https://mochajs.org/#mochaopts) +file or via the command line flags. - **BREAKING CHANGE** As Neutrino no longer supplies a CLI for executing project commands, the `--debug` flag no longer exists [#852](https://github.com/neutrinojs/neutrino/pull/852). You can still output debug information for middleware in your `.neutrinorc.js` with: @@ -166,6 +217,10 @@ module.exports = { - **BREAKING CHANGE** `@neutrinojs/html-loader` used by the web-related presets now parse URLs defined in link tags in the HTML template [#943](https://github.com/neutrinojs/neutrino/pull/943). +- **BREAKING CHANGE** `@neutrinojs/html-template` now uses a custom template instead of one provided by +[html-webpack-template](https://github.com/jaketrent/html-webpack-template), which supports a smaller set of options +but better html-webpack-plugin integration. You can override with your own template for more in-depth customization of +this template and its content [#1049](https://github.com/neutrinojs/neutrino/pull/1049). - **BREAKING CHANGE** The `@neutrinojs/hot` [#981](https://github.com/neutrinojs/neutrino/pull/981) and `@neutrinojs/env` [#983](https://github.com/neutrinojs/neutrino/pull/983) middleware have been removed and their relevant functionality is now configured directly by its previously-consuming presets. @@ -181,17 +236,28 @@ when the value *was set to `development`*, but now may be done when the value *i overwrite them [#1022](https://github.com/neutrinojs/neutrino/pull/1022). - **BREAKING CHANGE** `@neutrinojs/eslint` and its dependent middleware now require ESLint v5, which may mean breaking changes to rule configuration and any `parserOptions` modifications [#1025](https://github.com/neutrinojs/neutrino/pull/1025). +See the [ESLint migration docs](https://eslint.org/docs/user-guide/migrating-to-5.0.0) for more information. - **BREAKING CHANGE** The `options.mains` Neutrino option can now also accept an object per entry point for setting individual options for html-webpack-plugin [#1029](https://github.com/neutrinojs/neutrino/pull/1029). The previous API for setting these properties as strings is still supported. This also introduces a breaking API change as accessing an entry point property on `neutrino.options.mains` now returns a normalized object, even when using string options. - **BREAKING CHANGE** When configuring webpack with a target of `node` the `@neutrinojs/jest` preset will default its `testEnvironment` to also be `node` instead of `jsdom` [#1030](https://github.com/neutrinojs/neutrino/pull/1030). +- **BREAKING CHANGE** `@neutrinojs/web` and its dependent middleware no longer have the `options.hotEntries` option +[#902](https://github.com/neutrinojs/neutrino/pull/902). +- **BREAKING CHANGE** `@neutrinojs/web` and its dependent middleware no longer include `worker-loader` for automatically +loading `*.worker.js` files [#1069](https://github.com/neutrinojs/neutrino/pull/1069). +- **BREAKING CHANGE** The loading order for `config.resolve.extensions` has been rearranged to be closer in parity to +what webpack has configured by default [#1080](https://github.com/neutrinojs/neutrino/pull/1080). +- **BREAKING CHANGE** The tests directory is now additionally linted by default with `@neutrinojs/eslint` and its +dependent middleware [#951](https://github.com/neutrinojs/neutrino/pull/951). - **BREAKING CHANGE** Various dependencies have been updated which may bring their own breaking changes. Please check and test your project to ensure proper functionality. - ESLint caching is now enabled by default, so it is recommended to specify `.eslintcache` as being ignored from your source control commits. +[] + ## Neutrino v7 to v8 Neutrino v8 introduces a number of changes, with some of them being breaking changes. To upgrade from Neutrino v7 @@ -230,7 +296,8 @@ module.exports = Neutrino({ root: __dirname }) .call('eslintrc'); ``` -- **BREAKING CHANGE** When building, `file-loader` and `url-loader` will generate file names with pattern +- **BREAKING CHANGE** When building, [`file-loader`](https://webpack.js.org/loaders/file-loader/) and +[`url-loader`](https://webpack.js.org/loaders/url-loader/) will generate file names with pattern `[name].[hash].[ext]` instead of `[hash].[ext]`. ([#435](https://github.com/neutrinojs/neutrino/pull/435)) - **BREAKING CHANGE** The web preset no longer uses the `script-ext` plugin. It was never functional and did not serve a purpose at this time. ([#500](https://github.com/neutrinojs/neutrino/pull/500)) From 192d6c9da53b560dcab758c2b731e614cbfce5a5 Mon Sep 17 00:00:00 2001 From: Eli Perelman Date: Mon, 17 Sep 2018 14:57:51 -0700 Subject: [PATCH 3/4] Address review concerns for migration docs --- docs/migration-guide.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index f873a9646..c5da6b4c8 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -141,8 +141,8 @@ module.exports = { ESLint 5, and related packages [#809](https://github.com/neutrinojs/neutrino/pull/809). - **BREAKING CHANGE** The `@neutrinojs/chunk` middleware has been removed in favor of webpack's improved functionality around `splitChunks` [#809](https://github.com/neutrinojs/neutrino/pull/809). See -https://webpack.js.org/plugins/split-chunks-plugin/ for more information. Usage of the `vendor` entry point -will now throw an error when used with v9. +[the split chunks documentation](https://webpack.js.org/plugins/split-chunks-plugin/) for more information. +Usage of the `vendor` entry point will now throw an error when used with v9 and should not be used. - **BREAKING CHANGE** The `@neutrinojs/babel-minify` preset has been removed in favor of the much faster uglify-es built into webpack 4 [#809](https://github.com/neutrinojs/neutrino/pull/809). - **BREAKING CHANGE** The `@neutrinojs/web` and dependent presets have renamed the `minify.babel` option @@ -186,7 +186,8 @@ updated. has been removed. - **BREAKING CHANGE** The font and image loader rules have now been consolidated into a single rule for `@neutrinojs/font-loader` and another for `@neutrinojs/image-loader` [#858](https://github.com/neutrinojs/neutrino/pull/858). -- **BREAKING CHANGE** `@neutrinojs/font-loader` now uses `file-loader` instead of `url-loader` +- **BREAKING CHANGE** `@neutrinojs/font-loader` now uses [`file-loader`](https://webpack.js.org/loaders/file-loader/) instead of +[`url-loader`](https://webpack.js.org/loaders/url-loader/) [#858](https://github.com/neutrinojs/neutrino/pull/858). This prevents asset inlining and will always generate separate files. - **BREAKING CHANGE** `@neutrinojs/style-loader` now uses [`mini-css-extract-plugin`](https://webpack.js.org/plugins/mini-css-extract-plugin/) @@ -253,10 +254,10 @@ what webpack has configured by default [#1080](https://github.com/neutrinojs/neu dependent middleware [#951](https://github.com/neutrinojs/neutrino/pull/951). - **BREAKING CHANGE** Various dependencies have been updated which may bring their own breaking changes. Please check and test your project to ensure proper functionality. -- ESLint caching is now enabled by default, so it is recommended to specify `.eslintcache` as being ignored from -your source control commits. +- ESLint caching is now enabled by default for new projects, so it is recommended to specify `.eslintcache` as being +ignored from your source control commits. -[] +[Compare all v9 changes](https://github.com/neutrinojs/neutrino/compare/v8.3.0...master) ## Neutrino v7 to v8 @@ -296,8 +297,7 @@ module.exports = Neutrino({ root: __dirname }) .call('eslintrc'); ``` -- **BREAKING CHANGE** When building, [`file-loader`](https://webpack.js.org/loaders/file-loader/) and -[`url-loader`](https://webpack.js.org/loaders/url-loader/) will generate file names with pattern +- **BREAKING CHANGE** When building, file-loader and url-loader will generate file names with pattern `[name].[hash].[ext]` instead of `[hash].[ext]`. ([#435](https://github.com/neutrinojs/neutrino/pull/435)) - **BREAKING CHANGE** The web preset no longer uses the `script-ext` plugin. It was never functional and did not serve a purpose at this time. ([#500](https://github.com/neutrinojs/neutrino/pull/500)) From 4a9670962ea1c9258664d569ef2191129f299ff4 Mon Sep 17 00:00:00 2001 From: Eli Perelman Date: Mon, 17 Sep 2018 15:09:32 -0700 Subject: [PATCH 4/4] Reset incorrect docs change --- docs/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index c5da6b4c8..93fa0d383 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -297,7 +297,7 @@ module.exports = Neutrino({ root: __dirname }) .call('eslintrc'); ``` -- **BREAKING CHANGE** When building, file-loader and url-loader will generate file names with pattern +- **BREAKING CHANGE** When building, `file-loader` and `url-loader` will generate file names with pattern `[name].[hash].[ext]` instead of `[hash].[ext]`. ([#435](https://github.com/neutrinojs/neutrino/pull/435)) - **BREAKING CHANGE** The web preset no longer uses the `script-ext` plugin. It was never functional and did not serve a purpose at this time. ([#500](https://github.com/neutrinojs/neutrino/pull/500))