Neutrino 9 beta/release candidate feedback

[edmorley]

Hi!

We've just published a beta release of Neutrino 9 and are keen to have people trying it out/giving feedback. Notable changes:

• now using webpack 4, Babel 7, ESLint 6, and latest versions of test runners.
• significant performance improvements (see here).
• switched from using webpack/ESLint/test runner's APIs to using their native CLIs - which fixes a number of bugs, and means that the full set of CLI features are available for each, not just what we've emulated via the API.
• the neutrino --inspect feature now produces a fully-working webpack config, for easier debugging.

Full changelogs:

• v8.3.0 -> v9.0.0-beta.0
• v9.0.0-beta.0 -> v9.0.0-beta.1
• v9.0.0-beta.1 -> v9.0.0-rc.0
• v9.0.0-rc.0 -> v9.0.0-rc.1
• v9.0.0-rc.1 -> v9.0.0-rc.2
• v9.0.0-rc.2 -> v9.0.0-rc.3
• v9.0.0-rc.3 -> v9.0.0-rc.4
• v9.0.0-rc.4 -> v9.0.0-rc.5
• v9.0.0-rc.5 -> v9.0.0

The docs for the new version can be found here:
https://master.neutrinojs.org https://neutrinojs.org/

Note that during the beta phase, you'll need to explicitly install the @next version of any Neutrino monorepo packages when following the docs, otherwise you will install the latest stable (v8.3.0) packages instead.

For example, to use v9's create-project, run:

# NPM
npx @neutrinojs/create-project@next <directory-name>

# Yarn
# (There's a bug with `yarn create` and using a version number, so we run the commands
#  manually. Make sure the directory returned by `yarn global bin` is on `PATH` first.)
yarn global add @neutrinojs/create-project@next
create-project <directory-name>

Or to upgrade an existing project, modify the neutrino and @neutrinojs/* entries in your package.json to use version ^9.0.0-rc.5 ^9.0.0 and then see:
https://master.neutrinojs.org/migration-guide/ https://neutrinojs.org/migration-guide/

If you find any bugs (including things in the migration guide/docs that aren't clear enough) please comment here or file issues, so we can sort out any rough edges :-)

Many thanks!

[edmorley]

To give an example for the performance improvements - I created a project using Neutrino's create-project with both Neutrino 8 and Neutrino 9, that used @neutrinojs/airbnb + @neutrino/react + @neutrino/jest and timed various workflows:

Command	Neutrino 8	Neutrino 9 beta
yarn build	Cold: 12.8s Warm: 12.4s	Cold: 7.0s Warm: 4.2s
yarn start	Cold: 8.0s Warm: 7.4s	Cold: 6.2s Warm: 5.4s
yarn test	Cold: 4.8s Warm: 4.4s	Cold: 3.8s Warm: 3.0s
yarn lint	Cold: 5.3s Warm: 5.3s	Cold: 2.5s Warm: 2.0s

(yarn start was timed by forcing a process.exit() after the "compilation complete" message)

The speedup is even greater on projects that are larger than the create-project "hello world" (for some projects I've seen 5-10x warm build time improvements!).

Please do let us know how much of a difference upgrading makes! :-)

[Shyiy]

After upgrading to 9 beta from 8 and doing various minor adjustments following the migration guide, everything seems to work nicely by me except one thing.

I was using the webpack-pwa-manifest plugin to generate and inject a PWA manifest in the html. I verified that the plugin is supposed to be updated for Webpack v4.

I add the plugin to the end of the use config option in .neutrinorc.js on production with the following entry:

neutrino =>
    neutrino.config.plugin("webpack-pwa-manifest").use(require.resolve("webpack-pwa-manifest"), [
      {
        name: "appTitle",
        short_name: "appShortName",
        description: "appDescription",
        [... rest of the plugin config]
      }
    ])

The plugin is correctly picked up and executed, generating all its files and manifest in the build folder, it however fails to inject its contents in the index.html file. I've investigated a bit and by running neutrino --inspect --mode production it looks like the PWA manifest plugin is correctly loaded after the needed html-webpack-plugin plugin. When adding some debugging statements to the PWA manifest plugin it seems however that the necessary webpack compilation hook that is supposed to be provided by html-webpack-plugin, htmlWebpackPluginBeforeHtmlProcessing, is not present. Actually none of the hooks advertised in the HtmlWebpackPlugin docs seem to be present.

Is this a possible bug introduced by the current neutrino v9 beta? Note that the same config/code worked correctly before.

[edmorley]

Hi! Thank you for trying out the beta.

For Neutrino 9, we've updated html-webpack-plugin to 4.x since 3.x has issues with webpack 4 (particularly when using multiple entrypoints):

neutrino/packages/html-template/package.json

Line 26 in 7e5e3ab

"html-webpack-plugin": "4.0.0-alpha.2"

The 4.x release of html-webpack-plugin adjusted the hook names, so plugins that use them will need to be updated. The reason those new hook names don't appear in the html-webpack-plugin readme, is that the new changes haven't yet been merged to master, and are currently only on the webpack-4 branch / PR:
https://github.com/jantimon/html-webpack-plugin/tree/webpack-4
jantimon/html-webpack-plugin#953

Perhaps it might be worth filing an issue over at https://github.com/arthurbergmz/webpack-pwa-manifest to see if they can add support even before the final html-webpack-plugin@4.0.0 release? :-)

[Shyiy]

You're absolutely right, thanks for the in depth answer, I got confused by the master/beta README of the newly used plugin.

Nothing left for me to nag about then, it all works nicely :)

Only a small typo that I noticed in the migration guide:

The minimum supported Node.js version is 8.10. Node.js 9 is no longer supported #792. (should be 6)

[mattmcdonald-uk]

I'm struggling to get styles working in a development build.

In production everything works as expected after following the migration guide, but for development builds I'm getting errors for standard CSS (even the simplest CSS file generates this error):

ModuleParseError: Module parse failed: Unexpected character
You may need an appropriate loader to handle this file type.

I believe this may be due to css-extract-text-plugin being used for development?

I've not added any extra config options for style-loader, it's just included at 9.0.0-beta.0.

[edmorley]

@mattmcdonald-uk hi! Does the output from yarn neutrino --inspect --mode development shed any light? (If upgrading from Neutrino 8.3.0, I'd also compare it with the output from running yarn neutrino start --inspect-new before the upgrade).

@Shyiy - great! Thank you for trying it out and the feedback. Re the docs Node.js version, that part is definitely unclear, it should probably say "Node.js 6 and 9 are no longer supported".

[mattmcdonald-uk]

@edmorley If I turn extract off it works fine, with extract on it doesn't.

The different this makes to the development config output is removing this:

 /* neutrino.config.module.rule('style').use('extract') */
{
    loader: '/app/node_modules/mini-css-extract-plugin/dist/loader.js'
},

[edmorley]

Ah so extract isn't supposed to be enabled in development builds. What is the mode set to in the inspect output? Is --mode development being passed to webpack-dev-server? (or to webpack, if not using the dev server)

[mattmcdonald-uk]

It's being started with webpack-dev-server --mode development

[edmorley]

Ah - are you setting custom extract options?

Currently the web preset disables extract when not in production, here:

neutrino/packages/web/index.js

Line 32 in 7e5e3ab

extract: isProduction

However by passing custom options, that will be overwritten, and extract always enabled:

neutrino/packages/style-loader/index.js

Lines 21 to 27 in 7e5e3ab

	extract: {
	loader: {},
	plugin: {
	filename: process.env.NODE_ENV === 'production'
	? '[name].[contenthash:8].css'
	: '[name].css'
	}

neutrino/packages/style-loader/index.js

Line 53 in 7e5e3ab

loader: options.extract ? require.resolve('mini-css-extract-plugin/dist/loader') : require.resolve('style-loader'),

I believe the current implementation is so that users can force extraction to be enabled always (and not only in production) if desired. However that results in counter-intuitive behaviour in this case (since it means users have to remember to only pass the custom extract options when mode is production).

Edit 2: Actually I missed that we handle this here:

neutrino/packages/web/index.js

Lines 95 to 97 in 7e5e3ab

	style: options.style && merge(options.style, {
	extract: options.style.extract === true ? {} : options.style.extract
	}),

I think we should either:

1. Move the production conditional from the web preset into @neutrinojs/style-loader instead, so consumers of the web preset don't have to remember to conditionally pass any extract options. (But now they can't force it to be enabled in development)
2. Separate out the extraction on/off from the options. eg add an enabled key under extract or similar.

@mattmcdonald-uk @eliperelman, thoughts?

Edit: I personally think (1) might be fine, since mini-css-extract-plugin doesn't yet support HMR, so isn't really suitable for development anyway.

[mattmcdonald-uk]

@edmorley With my original issue I hadn't set the extract option, I just discovered it as a workaround for my problem.

From what I can see, currently extract is being used in development mode if left unset in your config.

[edmorley]

I've verified locally that this doesn't happen when using the web preset - are you using @neutrinojs/style-loader directly? Could you paste your .neutrinorc.js? (I really should have asked for this at the start hehe)

[mattmcdonald-uk]

Sure, this is what I'm using:

const Dotenv = require('dotenv-webpack')

module.exports = {
    use: [
        [
            '@neutrinojs/react', {
                html: {
                    title: 'Project',
                },
                devServer: {
                    port: 8080,
                },
                publicPath: '/',
            },
        ],
        '@neutrinojs/style-loader',
        (neutrino, envs = []) => {
            neutrino.config.plugin('dotenv').use(Dotenv, envs)
        },
    ],
}

[edmorley]

Ah right that explains it :-) The @neutrinojs/react preset includes @neutrinojs/style-loader already, so @neutrinojs/style-loader should not be added alongside it. Perhaps we need to make that clearer in the docs, or add a check inside @neutrinojs/style-loader to make sure it's not being included twice?

[mattmcdonald-uk]

Ah. That would explain it!

So how would I configure style-loader? I'd gone back to a basic config to try and get it working, but want to be able to use sass-loader too. This was is what I would want to achieve:

'@neutrinojs/style-loader', {
                test: /\.(css|sass|scss)$/,
                loaders: [{
                    loader: 'sass-loader',
                    useId: 'sass',
                }],
            },

[edmorley]

The @neutrinojs/react preset has a style option, that controls what's passed to @neutrinojs/style-loader:
https://master.neutrinojs.org/packages/web/#preset-options

neutrino/packages/web/index.js

Lines 30 to 33 in 7e5e3ab

	style: {
	hot: opts.hot !== false,
	extract: isProduction
	},

neutrino/packages/web/index.js

Line 176 in 7e5e3ab

.when(options.style, () => neutrino.use(styleLoader, options.style))

This isn't the first time that those options have been hard for people to find -- so we should probably come up with a way to adjust the existing docs mention to make it clearer. Any ideas? :-)

[mattmcdonald-uk]

Great, everything's working now. Thanks for helping me sort that (and for releasing v9 - hot loading is working properly for me again! 🎉)

I initially took a guess that the key might be styleLoader or 'style-loader', I don't know if there's any benefit to making the key more directly related to the name of the thing you're configuring?

Other than that I think a mention that the style-loader middleware is already included with the react (and any other) preset in the docs, along with a note on the key to use would be handy. Probably a note on the key to use in the react section would be helpful too.

An additional CLI warning that you shouldn't include style-loader directly when you're using the react preset would probably be useful too if you had missed the warnings within the docs.

[ratson]

@edmorley I see "re-license at MIT" was removed from #693 title, and the beta release is still MPL-2.0.
Is that not going to happen for v9 release? If webpack-chain would follow the same?

[edmorley]

@mattmcdonald-uk, glad it's working now! I'll have a think about what changes I can make.

@ratson, yeah I discussed with Eli on IRC and said that (a) the two changes were unrelated (and both significant) so shouldn't be bundled into the same PR, (b) we needed to figure out what permissions we did/didn't need from previous contributors before we relicence. Is lack of MIT licence blocking your usage of Neutrino?

[ratson]

Not currently, just wondering if releasing with a more permissive license is still on the plan.

[edmorley]

Here are two PRs for projects upgrading from Neutrino 8 to 9:

• Upgrade to Neutrino 9 beta mozilla-frontend-infra/firefox-health-dashboard#158
• Upgrade to Neutrino 9 beta mozilla-frontend-infra/firefox-performance-dashboards#86

Some of the issues encountered for which we could improve the UX:

• usages of the html.links option had to be replaced (but was silently ignored, meaning it was missed during the first pass of the migration)
• the ./static/ directory was no longer copied since we removed that feature (we do mention this in the release notes, but perhaps we can do a directory exists check combined with seeing if they've added @neutrinojs/copy and if not, warn? Edit: I don't think we should do this, given that we can't guarantee that a ./static/ directory isn't being used eg for images imported in JS)
• at one point in the PR iterations, --optimize-minimize was being passed to webpack rather than --mode (something else wasn't working, so various permutations of settings were being tried). There's not much we can/should do about this IMO, but I've filed Deprecate --optimize-minimize in favour of --mode production webpack/webpack-cli#624 for making it show a deprecation warning.
• not specific to the migration, but both the @neutrinojs/react and @neutrinojs/web presets were being used simultaneously, causing confusion due to the web preset clobbering the settings from the react preset. Perhaps we should have the top-level presets error out in this case?
• there were lots of stale dependencies in the yarn lockfiles - we should perhaps emphasise the need to regenerate the lockfile

[timkelty]

I can’t rely on this project as 9 has been pre-release for over half a year. You’re simply not active enough to be trusted.

I find it preferable to "trust" a project that has a methodical and deliberate release process, opposed to one with frequent breaking releases.

Also worth noting is that v9 introduces some of the most significant conceptual changes to the project, and thus is a very important release to get right.

[eddyw]

@eddyw Hi! Yeah I can see how everything being of type Any must be frustrating. I personally wouldn't mind converting Neutrino to TypeScript, though I think other maintainers might have different opinions. If there was an easy way to improve types out of the box (whilst sticking to JS) that doesn't impose too much of a burden (eg something checked in CI) - like was performed for webpack-chain, a PR for that would likely be accepted. However if it's more than just a few top-level type definitions it may be worth going the whole way and converting to TS entirely (but that's not something I personally will have time to work on; plus would be worth getting buy-in from other maintainers first).

@edmorley Hey 👋
Ok, I opened a PR. It adds typings the same way that webpack-chain does, so keeping JS for now. Hopefully in the future it could be re-written in TS since the code doesn't look overly complicated and declaration files could be exported by tsc automatically.

[akhnaz]

I am currently using neutrino 8 with react preset but would like to use babel 7. The only way that I know is to upgrade the neutrino to v9 rc. Is that true or I have the ability to change the babel version without migrating to v9?

[yordis]

@akhnaz are you using the presets?

[akhnaz]

@yordis I am using presets react

[dantman]

@edmorley I would propose something: make Neutrino releases decoupled from the presets.

I don't really care about usage of neutrino without presets, IMHO presets are what make neutrino useful. But I agree that Neutrino's release process for core and presets should be decoupled from each other.

Inside the release process presets seem to slow down the release of bugfixes to core that affect everyone. While outside the main repo presets suffer from maintenance issues, in my experience frequently becoming abandoned making it impossible to fix bugs and limitations in them.

I think presets should stay inside the neutrino mono-repo and we should invite adding more presets to the mono-repo. But the release process should be decoupled so that core and individual presets can get releases without waiting for a bug in a separate preset to be fixed.

Then instead of presets becoming abandoned and hard to fix when one person no-longer finds them useful, anyone using them can fix bugs simply by submitting a PR that can be merged by someone other than only the original author. And core can get releases more frequently without waiting for any one of the presets to have all its bugs fixed.

I find it preferable to "trust" a project that has a methodical and deliberate release process, opposed to one with frequent breaking releases.

Personally I find it's usually the opposite. Most projects I see that make frequent breaking changes (Material UI, React Native) make small near-painless breaking changes that make migration easy and usually because of it have good tooling (codemods and compat shims) to make those migrations easier. While projects that avoid making breaking changes for a long time and wait to do it all at once in a long process (Babel) draw out the migration to a painful length and lead to a hell within the community where people are on different versions, stable releases become unusable bug-ridden problems, alphas become the de-facto "stable" version, and migration is painful.

[timkelty]

Personally I find it's usually the opposite…

@dantman You certainly have a point there, especially with the projects you mentioned. Somewhere in the middle is likely ideal.

I also empathize with your experience of finding dead/abandoned presets (I know I have a few), and wishing they were in core. At the same time, having more presets in core is more of a burden for maintainers. Decoupling releases would help that, but it would also seem awkward (and present difficulties for testing) if all presets were all at different versions and compatibilities.

One idea would be to create an "official" channel for community supported presets, e.g. https://github.com/webpack-contrib. That way they don't need to be in core, but can still be centralized and more easily vetted, deprecated, and managed.

[timkelty]

Has anyone else played around with multi-compiler output w/ v9?

I'm attempting to use a single .neutrinorc.js, but compile 2 outputs: 1 esmodules, 1 without (legacy).

Here's what I have so far…

webpack.config.js

const neutrino = require('neutrino');
const {join} = require('path');
const rc = require(join(process.cwd(), '.neutrinorc.js'));
const esmOptions = {...rc.options, ...{
  esm: true,
  mains: {
    'index.esm': rc.options.mains.index,
  },
}};

module.exports = [
  neutrino(rc).webpack(),
  neutrino({...rc, ...{options: esmOptions}}).webpack(),
];

…then in my .neutrinorc.js file (abbreviated for…brevity):

const web = require('@neutrinojs/web');

module.exports = {
  options: {
    mains: {
      index: 'index',
    },
  },
  use: [
    (neutrino) => neutrino.use(
      web({
        // Pass `false` to use .browserslistrc file
        targets: neutrino.options.esm ? {esmodules: true} : false,
      })
    ),
  ],
};

seems to be working? Curious if anyone else has done this, or if this seems like a reasonable approach?

[edmorley]

@timkelty looks good to me - it's the approach we mention here:
https://master.neutrinojs.org/usage/#generating-multiple-builds

[timkelty]

@edmorley Ah - totally missed that in the guide, thanks!

I guess the difference from my example is I'm creating 2 full neutrino instances with different options, rather than just manipulating the webpack output.

I wasn't sure if setting an arbitrary option on neutrino.options would work (I feel like maybe it used to validate those?), but it seems to allow it.

[edmorley]

I've just published v9.0.0-rc.4. Most notably it includes support for ESLint 6, and newer AirBnB + StandardJS presets.

Full changes here:
v9.0.0-rc.3...v9.0.0-rc.4

[edmorley]

I'd like to ship Neutrino 9 final in the next week or two. If anyone sees issues with RC4 please file them as soon as possible. Also if anyone has spare time to work on #1404 it would be appreciated :-)

[armenzg]

I've deployed it to a couple of projects. So far no problems. Thanks Ed!

[edmorley]

@armenzg That's great! Hope you are well and things going great for Treeherder and the rest of the team :-)

[mlnmln]

Thank you so much for the migration tool and your work on the project.

Currently exploring 9.0.0-rc.4, so far relatively smooth ride.

Since @neutrinojs/stylelint is going to be deprecated, what's the suggested upgrade path here?

I would have expected something similar as for the eslint package, e.g.

// .stylelintrc.js
const neutrino = require("neutrino");

// Load with no config overrides:
module.exports = neutrino().stylelintrc();

edit: ok found the rationale here. #1110 sorry for spamming the main issue. will open a separate one.

[Tassfighter]

Any news on the release date?

[edmorley]

I've just released v9.0.0-rc.5:
https://github.com/neutrinojs/neutrino/blob/master/CHANGELOG.md#v900-rc5

Presuming no issues reported in the next few days, I'd like to release v9 final at that point.

[ringods]

@edmorley I only see a bump of a few dependencies since 9.0.0-rc5. Together with it, the only issue reported since you released 9.0.0-rc5 is #1492, but that doesn't seem to be related to the release candidate per se.

Time to finally make that 9.0.0 release? 😉

[edmorley]

Hi! Yeah #1492 is the only potential blocker (not in the sense that it's a regression, but because it's a breaking change) - though perhaps it's best to just leave it until Neutrino 10 now.

[jeanlescure]

Just jumped on the Neutrino band-wagon. I struggled with v8 until I found these threads pointing to v9 RC.

I would also like to echo the overall sentiment, please release 9.0.0 😄

[edmorley]

I've opened #1505 to begin the v9.0.0 final release process :-)

[edmorley]

Neutrino 9.0.0 stable is now released. Thank you to everyone who tried out the betas/release-candidates and/or gave feedback.

The v9 docs are now published to https://neutrinojs.org . For migration guide see: https://neutrinojs.org/migration-guide/

For any issues/feedback found from now on, please open as new GitHub issues :-)

[timkelty]

Thanks for all the work, @edmorley!

[brabeji]

Neutrino was and still is the best webpack config abstraction. Thank you @edmorley !