Using Neutrino to jump-start modern JavaScript development

Neutrino is a tool which brings together the best parts of the modern JavaScript toolchain with the ease of zero upfront configuration. Embarking on the adventure that is JavaScript development can be daunting.

Working with the latest tools and cutting edge libraries is fun, but oftentimes results in a significant amount of setup overhead before sitting down to write an app. Facing analysis paralysis is a common threat, and the time necessary to complete a comprehensive tooling pipeline has given rise to stigmas like “JavaScript fatigue”. Neutrino was built to let you hit the ground running.

Neutrino combines the power of Webpack with the simplicity of presets to build web and Node.js projects. By encapsulating the common use cases of Webpack configuration into shareable presets, it is possible to create an application without ever needing to touch a configuration file. At present, there are presets available for creating applications for the web, React, and even Node.js. Adding testing or linting is also only a preset away. Let’s take a look at how quickly we can start a React application.

React quickstart

Throughout this guide I’ll be using the Yarn client for working with dependencies and running commands. This is merely a personal preference; you can also use the npm client if you desire.

First up, we need a space to create our React application. In your terminal, create a new directory and change it into:

❯ mkdir hacks-react
❯ cd hacks-react

Next, let’s add Neutrino and the React preset for building the app, and some other dependencies for actually developing with React:

❯ yarn add --dev neutrino neutrino-preset-react
❯ yarn add react react-dom

The React preset has a few conventions:

  • Source code lives in src
  • The entry point to the app is src/index.js
  • You can mount your application to an element with an ID of “root”

Let’s create the entry file at src/index.js, edit it with some simple content, and render it:

import React from 'react';
import { render } from 'react-dom';

render(<h1>Hacks: React!</h1>, document.getElementById('root'));

In order to run our preview app and build it, add a couple scripts to your package.json:

  "scripts": {
    "start": "neutrino start --presets neutrino-preset-react",
    "build": "neutrino build --presets neutrino-preset-react"
  "devDependencies": {
    "neutrino": "^4.0.0",
    "neutrino-preset-react": "^4.0.0"
  "dependencies": {
    "react": "^15.4.2",
    "react-dom": "^15.4.2",
    "react-hot-loader": "next"

Run the command to start it in your console, and open the URL given:

❯ yarn start

✔ Development server running on: http://localhost:5000
✔ Build completed

Screen Shot 2017-02-17 at 12.55.05 AM

In less than 5 minutes, we have a working start to a React app! What’s more, our Neutrino preset comes with quite a bit out of the box:

  • Zero upfront configuration necessary to start developing and building a React web app.
  • Modern Babel compilation adding JSX, ES modules, last 2 major browser versions, async functions, and object rest spread syntax.
  • Support for React Hot Loader with hot module replacement.
  • Extends from neutrino-preset-web.
  • Webpack loaders for importing HTML, CSS, images, icons, and fonts directly from JavaScript.
  • Webpack Dev Server during development.
  • Automatic creation of static HTML pages, no templating necessary.
  • Production-optimized bundles with Babili minification and easy chunking.
  • Easily extensible to customize your project as needed, no blackboxes or ejecting required.

Code quality

It’s just as easy to add linting. Let’s use the Airbnb style guide as an example. By adding the Airbnb preset, we can lint our source code according to the Airbnb style guide:

❯ yarn add --dev neutrino-preset-airbnb-base

Now let’s add our preset to our Neutrino commands, but let’s move it to “presets” and out of “scripts” so it’s not so unwieldy and we reduce repetition. Also, the Airbnb preset needs to load before our build preset:

  "config": {
    "presets": [
  "scripts": {
    "start": "neutrino start",
    "build": "neutrino build"

If we start the app again, but this time introduce something that goes against the Airbnb style guide, we can see the problems right in the console:

❯ yarn start

✔ Development server running on: http://localhost:5000
✔ Build completed

ERROR in ./src/index.js

  5:13  error  Strings must use singlequote  quotes

✖ 1 problem (1 error, 0 warnings)

Keeping your code quality high is as simple as adding presets and following conventions. You can follow the same guidelines to add testing to the project. Just choose a testing preset and you are on your way.

With great power…

There may come a point where something in the build process needs to change to support your specific use cases. Fortunately, customizing and overriding the build process is straightforward. Neutrino does not force you to maintain the entire build configuration if you need changes, nor does it eject all its dependencies into your project. Each Neutrino preset has well-defined mechanisms for augmenting the build with a minimal but intuitive API. Creating your own presets is also a good way to unify configuration across many projects and reduce duplicating common changes. Simply publish to npm or GitHub, add as another dependency, and continue developing.

Our motivation

We created Neutrino to solve problems we faced creating front-end applications across teams within Mozilla’s Release & Productivity organization. Neutrino is currently in use by several Mozilla projects including TaskCluster, Treeherder, and Unified Logviewer. We maintain and support Neutrino because it is something we ourselves need and use, and we hope that everyone who uses it will also benefit.

Go forth and create

By bringing together great tools, Neutrino and its presets foster an environment for rapid development while eliminating some of the barriers in the way of writing applications. I encourage you to read through the comprehensive Neutrino documentation and try it out in your next project. All the source code is licensed MPL v2 and is available on GitHub. Enjoy!

About Eli Perelman

More articles by Eli Perelman…


  1. bat

    Thanks! I don’t understand what is the added value versus all the boilerplate projects out there or metapackage like create-react-app…

    February 23rd, 2017 at 14:32

    1. Eli Perelman

      The proliferation of boilerplate and metapackages is one thing we are trying to reduce. These types of projects are great, and do serve a purpose. But what if you wanted to make a configuration change across all your projects? You must make config changes in many places, including the original boilerplate, whereas presets give you the power to confine these changes to a single package. Some of these projects also make a tradeoff between ease of set up and black-boxing the configuration. Once you decide to make a configuration change, you are forced to maintain the entire configuration and its dependencies in perpetuity. We believe Neutrino represents a good balance between ease of set up and future extensibility.

      February 23rd, 2017 at 14:48

      1. bat

        Thanks for your detailed answer.
        You are answering the clear pain point of maintaining a webpack build process for large projects with specific needs.
        But not that much the problem of jump-starting an app as the title claims.

        February 23rd, 2017 at 18:02

        1. Eli Perelman

          I can understand where you’re coming from. The proposition of Neutrino isn’t to cater to large applications or small ones, but provide a gradiented experience. When I say “jump-start an app”, I’m talking about reducing the upfront fatigue and obstructions that keep many from actually writing their project. In less than a few minutes you can go from nothing to writing actual application code.

          You may not need all the fancy configuration customization up front. That’s why there are a number of presets in place; to let you hit the ground running. Do this a number of times, and maybe in the future you want to make changes; Neutrino can help with this. Make these changes enough times across many projects and Neutrino is also there to help create custom presets too.

          I feel like we’ve covered a good amount of the bases to let applications of all sizes jump-start however they need. Hope that clarifies what I meant. Thanks, and good luck!

          February 23rd, 2017 at 20:02

  2. Philip Mander

    I really like this. Seems like a natural evolution beyond web build tools and boilerplates. I hope it becomes ubiquitous in web development.

    One problem is that many will just dismiss this as another boilerplate tool and, to that end, I don’t think the title of this post does neutrino justice.

    February 24th, 2017 at 05:24

    1. Eli Perelman

      Thanks, and yes, sounds like the story isn’t very well defined around how this contrasts to boilerplates. We will update the docs soon to address this.

      February 24th, 2017 at 10:03

  3. Jorge Antunes

    This is a very exciting announcement! I was in the process of upgrading dev-toolkit[1] for webpack 2 but looking at this project and webpack-chain, from what I can see it seems that I could reduce dev-toolkit to a just preset! And best of all, it allows people to have all the flexibility they would need in addition to the preset.

    nice job guys <3


    February 24th, 2017 at 09:27

    1. Eli Perelman

      Thank you! In addition to your preset, if you find best practices that all React preset users could benefit from, we would love to see that make it into the core presets as well. We would love to have any contributions you may have!

      February 24th, 2017 at 10:04

  4. KZ

    What about accessibility? (WCAG…)

    Mozilla Manifesto:
    5. Individuals must have the ability to shape their own experiences on the Internet.

    February 26th, 2017 at 01:15

    1. Eli Perelman

      Working on accessibility falls on the side of application-specific code, and Neutrino doesn’t do anything to get in the way of this, nor prevent you from creating accessible experiences.

      February 26th, 2017 at 07:27

  5. Alexander

    class Neutrino extends EventEmitter {

    SyntaxError: Block-scoped declarations (let, const, function, class) not yet supported outside strict mode
    at exports.runInThisContext (vm.js:53:16)
    at Module._compile (module.js:374:25)
    at Object.Module._extensions..js (module.js:405:10)
    at Module.load (module.js:344:32)
    at Function.Module._load (module.js:301:12)
    at Module.require (module.js:354:17)
    at require (internal/module.js:12:17)
    at Object. (/Users/aodell/dev/hacks-react/node_modules/neutrino/bin/neutrino:3:18)
    at Module._compile (module.js:398:26)
    at Object.Module._extensions..js (module.js:405:10)

    I tried with NPM instead of YARN

    March 3rd, 2017 at 02:50

    1. Eli Perelman

      Neutrino requires Node.js v6.9+. You can check your version with `node –version`.

      March 3rd, 2017 at 05:36

  6. Dami

    So, whay this is different from tools like yeoman?

    March 10th, 2017 at 10:10

    1. Eli Perelman

      Yeoman is a scaffolding and boilerplate generation tool. While it can be used to generate all of the Webpack configuration your application needs, this means having to maintain all of this configuration from that moment forward into your application. You would then need to duplicate this process every time you started a new project. See the FAQ for more information:

      March 10th, 2017 at 10:16

Comments are closed for this article.