Write migration guide for Neutrino 9

[edmorley]

We need to add a new section to:
https://github.com/mozilla-neutrino/neutrino-dev/blob/master/docs/migration-guide.md

[edmorley]

Things that need covering so far:

• Adapting for the changes in Morph Neutrino API and CLI into middleware injectors for external CLI tools #852:
  • Adjusting the package.json script entries to reference webpack/webpack-dev-server/eslint/... instead of neutrino {build, start, lint, test} (and mention that neutrino --inspect still exists).
  • Running yarn add --dev webpack webpack-dev-server eslint ... (possibly with specific major versions listed).
  • Creating new webpack.config.js and related files, plus updating any existing .eslintrc.js.
  • @neutrinojs/fork has been removed - need example of how to implement using webpack.config.js.
  • Accounting for the removed Neutrino APIs.
  • Possibly adjust environment specific configs (depending on outcome of Environment-specific configs silently not working after #852 #906).
  • Possibly adjust test preset related configs (depending on outcome of Properly set mode and NODE_ENV for test middleware #900).
• The @neutrinojs/chunk preset has been removed in favour of the splitChunks feature.
• The @neutrinojs/babel-minify preset has been removed in favour of the faster uglify-es which is built into webpack 4 (the fake vendor entrypoint should now be removed from people's .neutrinorc.js to avoid a bigger build then necessary).
• The @neutrinojs/web preset's minify.babel option has been replaced by minify.source.
• The @neutrinojs/web preset no longer includes @neutrinojs/image-minify (which was off by default anyway) or @neutrinojs/style-minify. As such the minify.image and minify.style web preset options have been removed.
• The @neutrinojs/minify preset no longer exists, the individual @neutrinojs/*-minify presets should be used instead.
• @neutrinorc/react and @neutrinorc/preact no longer use babel-plugin-jsx-pragmatic, so explicit React/Preact imports need to be added (Stop using babel-plugin-jsx-pragmatic #827).
• @neutrinojs/react now uses react-hot-loader 4, which changes the recommended way to confgure hot loading in the app (https://github.com/gaearon/react-hot-loader#migrating-from-v3).
• The web and node presets (and any others that inherit from them) no longer configure a default CopyPlugin for src/static/ (Remove default CopyPlugin from src/static/ to build/static/ #814).
• Babel has been upgraded from v6 to v7, so any manually specified official plugins need to be switched to the Babel 7 namespace equivalents (@babel/*). (Though the v7 preset-env now included more built in, so some of the custom plugins might be able to be dropped.)
• The fast-async babel plugin is no longer used (Stop using the fast-async babel plugin #790).
• The output produced by --inspect has changed (and is equivalent to the backported --inspect-new added to Neutrino 8).
• The length of hashes used in filenames has been shortened to 8 characters, so any web server caching rule regexes must be updated (Adjust hashes used in production asset filenames #930).
• Module resolution now uses the webpack 4 defaults, and the Neutrino node_modules option has also been removed (Use default webpack module resolution #926).
• The font/image loader rules have now been consolidated into a single rule for @neutrinojs/font-loader and another for @neutrinojs/image-loader.
• @neutrinojs/font-loader now uses file-loader rather than url-loader which prevents inlining.
• @neutrinojs/style-loader replaced extract-test-webpack-plugin with mini-css-extract-plugin.
• @neutrinojs/compile-loader now sets babelrc to false. If the previous behaviour of reading .babelrc files is desired, it can be switched back using babel: { babelrc: true } (compile-loader: Set 'babelrc' to false #826).
• @neutrinojs/eslint (and any presets that inherit from it) now throws if defined after a compile preset, to prevent unknowingly using a broken configuration (eslint: Throw if preset used after compile rule already defined #939).
• The minimum node.js version has been raised from 6 to 8.3.
• Various dependencies have been updated, some of which have their own breaking changes.

Edit, also:

• @neutrinojs/karma (depending on the outcome of Unable to pass options to @neutrinojs/karma after #852 #907), @neutrinojs/jest and @neutrinojs/mocha no longer accept being passed any options.
• Third party presets will need to adapt to the new approach after Morph Neutrino API and CLI into middleware injectors for external CLI tools #852 - we should right a short explanation and then link to the updated presets developer guide.
• The --debug option no longer exists, instead options: { debug: true } can be used in .neutrinorc.js.

[edmorley]

• html-loader now parses URLs in too (html-loader: Add 'link:href' to attrs so favicons are parsed #943).
• The tests directory is linted now too by eslint-loader (eslint: Lint the tests directory by default too #951).
• ESLint caching is now enabled, so .eslintcache needs to be added to project's .gitignore.

[edmorley]

• Removed @neutrinojs/hot (Remove @neutrinojs/hot #981)
• Removed @neutrinojs/env - now built into the web preset directly (Move @neutrinojs/env into the web preset & support default values #983)
• @neutrinojs/node now targets the version of Node used to run webpack/... by default (node: Target the version of Node.js used to run webpack #991)
• mode/NODE_ENV defaults and interaction adjusted in Improve mode/NODE_ENV defaults and interaction #972

[edmorley]

• babel-merge upgraded and different merge behaviour (Update dependency babel-merge to v2 #1022)
• upgraded to ESLint 5 and parserOptions changes (Update to ESLint 5 #1025)
• mains now supports specifying html template options per-entrypoint. Whilst mains is backwards compatible when setting the options, the returned value is now an object rather than a string (Support per-page HTML template customisation via 'mains' #1029)
• for a webpack target of 'node', @neutrinojs/jest now sets a testEnvironment of 'node' (Jest: Set testEnvironment to 'node' when targeting node #1030)
• Node 9 is no longer supported (Drop support for Node 9 #1035)

[edmorley]

• No longer using html-webpack-template (html-template: Replace html-webpack-template with our own template #1049)
• The way root should be specified has changed (see Specify root option for monorepo scripts and project creation #1041 for how to set it via options instead)
• worker-loader has been removed from @neutrinojs/web (web/library: Remove worker-loader #1069)
• The config.resolve.extensions order has now changed to be closer to that of webpack (Converge extension priority parity with that of webpack #1080)