Merge pull request #98 from eliperelman/v5-docs

v5 Docs

docs/SUMMARY.md

@@ -1,27 +1,30 @@
 # Summary
 
-* [Introduction](/README.md)
+* [Introduction](./README.md)
-* [Installation](/installation.md)
+* [Installation](./installation.md)
-* [Usage](/usage.md)
+* [Usage](./usage.md)
-* [Project Layout](/project-layout.md)
+* [Project Layout](./project-layout.md)
-* [FAQ](/FAQ.md)
+* [FAQ](./FAQ.md)
-* [Presets](/presets/README.md)
+* [Middleware](./middleware/README.md)
-  * [Web](/presets/neutrino-preset-web/README.md)
+* [Presets](./presets/README.md)
-  * [React](/presets/neutrino-preset-react/README.md)
+  * [Web](./presets/neutrino-preset-web/README.md)
-  * [Node.js](/presets/neutrino-preset-node/README.md)
+  * [React](./presets/neutrino-preset-react/README.md)
-  * [Airbnb](/presets/neutrino-preset-airbnb-base/README.md)
+  * [Node.js](./presets/neutrino-preset-node/README.md)
-  * [Karma](/presets/neutrino-preset-karma/README.md)
+  * [Airbnb](./presets/neutrino-preset-airbnb-base/README.md)
-  * [Mocha](/presets/neutrino-preset-mocha/README.md)
+  * [Karma](./presets/neutrino-preset-karma/README.md)
-  * [Jest](/presets/neutrino-preset-jest/README.md)
+  * [Mocha](./presets/neutrino-preset-mocha/README.md)
-  * [Community presets](/presets/community-presets.md)
+  * [Jest](./presets/neutrino-preset-jest/README.md)
-* [Customization](/customization/README.md)
+  * [Community presets](./presets/community-presets.md)
-  * [Simple](/customization/simple.md)
+* [Customization](./customization/README.md)
-  * [Advanced](/customization/advanced.md)
+  * [Simple](./customization/simple.md)
-* [Creating presets](/creating-presets.md)
+  * [Advanced](./customization/advanced.md)
-  * [Creating linting presets](/presets/neutrino-lint-base/README.md)
+* [Creating presets](./creating-presets.md)
-* [Learning Resources](/learning-resources.md)
+  * [Creating linting presets](./presets/neutrino-lint-base/README.md)
-* [API](/api/README.md)
+* [Learning Resources](./learning-resources.md)
-* [CLI](/cli/README.md)
+* [API](./api/README.md)
-* [Contributing](/contributing/README.md)
+* [CLI](./cli/README.md)
-  * [Development Process](/contributing/development.md)
+* [Upgrading from v4 to v5](./upgrading-neutrino.md)
-  * [Code of Conduct](/contributing/code-of-conduct.md)
+* [v4 Documentation](https://github.com/mozilla-neutrino/neutrino-dev/tree/docs-v4/docs)
+* [Contributing](./contributing/README.md)
+  * [Development Process](./contributing/development.md)
+  * [Code of Conduct](./contributing/code-of-conduct.md)

docs/api/README.md

@@ -1,19 +1,20 @@
 # Neutrino API
 
-When using Neutrino via the [CLI](/cli/README.md), it creates an instance of the Neutrino API which picks up
+When using Neutrino via the [CLI](../cli/README.md), it creates an instance of the Neutrino API which picks up
-any presets and arguments passed on the command line. If you desire, you can also create your own
+any presets and arguments passed on the command line or located in package.json. If you desire, you can also create your
-instance of the Neutrino API and interact with it programmatically.
+own instance of the Neutrino API and interact with it programmatically.
 
 ## Instantiation
 
 In order to access the Neutrino API, you must require or import it and instantiate it, passing in any
-preset names or paths you wish to load:
+options:
 
 Using `require`:
 
 ```js
 const Neutrino = require('neutrino');
-const api = new Neutrino(['neutrino-preset-react']);
+
+const api = new Neutrino(options);
 ```
 
 Using ES imports:
@@ -21,19 +22,159 @@ Using ES imports:
 ```js
 import Neutrino from 'neutrino';
 
-const api = new Neutrino(['neutrino-preset-react']);
+const api = new Neutrino(options);
+```
+
+## API options
+
+The Neutrino constructor can accept an object for setting a number of useful options:
+
+### `options.root`
+
+Set the base directory which Neutrino middleware and presets operate on. Typically this is the project directory where
+the package.json would be located. If the option is not set, Neutrino defaults it to `process.cwd()`. If a relative
+path is specified, it will be resolved relative to `process.cwd()`; absolute paths will be used as-is.
+
+```js
+new Neutrino({
+  // if not specified, defaults to process.cwd()
+  
+  // relative, resolves to process.cwd() + ./website
+  root: './website',
+  
+  // absolute
+  root: '/code/website'
+})
+```
+
+### `options.source`
+
+Set the directory which contains the application source code. If the option is not set, Neutrino defaults it to `src`.
+If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be used as-is.
+
+```js
+new Neutrino({
+  // if not specified, defaults to options.root + src
+  
+  // relative, resolves to options.root + ./lib
+  source: './lib',
+  
+  // absolute
+  source: '/code/website/lib'
+})
+```
+
+### `options.output`
+
+Set the directory which will be the output of built assets. If the option is not set, Neutrino defaults it to `build`.
+If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be used as-is.
+
+```js
+new Neutrino({
+  // if not specified, defaults to options.root + build
+  
+  // relative, resolves to options.root + ./dist
+  output: './dist',
+  
+  // absolute
+  output: '/code/website/dist'
+})
+```
+
+### `options.tests`
+
+Set the directory that contains test files. If the option is not set, Neutrino defaults it to `test`.
+If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be used as-is.
+
+```js
+new Neutrino({
+  // if not specified, defaults to options.root + test
+  
+  // relative, resolves to options.root + ./testing
+  tests: './testing',
+  
+  // absolute
+  tests: '/code/website/testing'
+})
+```
+
+### `options.entry`
+
+Set the main entry point for the application. If the option is not set, Neutrino defaults it to `index.js`.
+If a relative path is specified, it will be resolved relative to `options.source`; absolute paths will be used as-is.
+
+```js
+new Neutrino({
+  // if not specified, defaults to options.source + index.js
+  
+  // relative, resolves to options.source + ./entry.js
+  entry: './entry.js',
+  
+  // absolute
+  entry: '/code/website/lib/entry.js'
+})
+```
+
+### `options.node_modules`
+
+Set the directory which contains the Node.js modules of the project. If the option is not set, Neutrino defaults it to
+`node_modules`. If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be
+used as-is.
+
+```js
+new Neutrino({
+  // if not specified, defaults to options.root + node_modules
+  
+  // relative, resolves to options.root + ./modules
+  node_modules: './modules',
+  
+  // absolute
+  node_modules: '/code/website/modules'
+})
+```
+
+## Loading middleware
+
+Using the Neutrino API you can load [middleware](../middleware/README.md) and presets (which are also just middleware)
+using the `use` method. The `use` method takes in a middleware function, and optionally any options that should be
+passed to the middleware function.
+
+```js
+api.use(middleware, middlewareOptions)
+```
+
+Typically presets do not require any additional options, and middleware may, but check with your particular package
+for specifics. As an example, if you wanted to require the list of presets and Neutrino options from a package.json:
+
+```js
+const Neutrino = require('neutrino');
+const pkg = require('./package.json');
+
+const api = new Neutrino(pkg.neutrino.options);
+
+api.use(require(pkg.neutrino.presets[0]));
+```
+
+You can call `.use` iteratively for multiple presets:
+
+```js
+pkg.neutrino.presets
+  .forEach(preset => neutrino.use(require(preset)));
 ```
 
 ## Environment
 
 When using the CLI, environment variables are automatically set based on the command you are using.
 When using the API this is not the case, and you **must** set it prior to calling any build commands or
-loading any presets.
+loading any presets if you expect them to build correctly based on their target.
 
 ```js
 process.env.NODE_ENV = 'production';
 
 const api = new Neutrino();
+
+// load presets...
+
 api.build();
 ```
 
@@ -41,21 +182,46 @@ api.build();
 
 ### Constructor
 
-When creating a Neutrino instance, you have the option of providing an array of presets for the API to attempt
+When creating a Neutrino instance, you have the option of providing an object which can be passed as options to
-to load and merge configurations for. Each preset will attempt to be loaded from the current working directory's
+middleware as `neutrino.options`.
-`node_modules`, nested within, by name, or relative file path. If it cannot be found, an exception will be thrown.
+
+```js
+const Neutrino = require('neutrino');
+
+const api = new Neutrino();
 
-In addition to any provided presets, Neutrino will also attempt to load configuration data from the package.json
+// or with optional options
-residing in the current working directory. If this package.json contains an object at `config.neutrino`, this data
+const api = new Neutrino({ jest: { bail: true } });
-will be merged.
+```
 
 ### `.config`
 
 When constructing a Neutrino instance, a property of `.config` is set to be a new instance of
-[webpack-chain](https://github.com/mozilla-neutrino/webpack-chain/tree/v1.4.3). This property is then available to all presets, which
+[webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). This property is then available to all presets
-subsequently augment it with their specific options. Every preset added uses this single `.config` to store their data,
+which subsequently augment it with their specific configuration. All middleware and presets added use this single
-meaning that preset load order has an effect on which config values take precedence. Presets loaded later will override
+`.config` to store their data, meaning that middleware load order has an effect on which config values take precedence.
-values set by earlier presets.
+Middleware loaded first will have any configuration overridden by later middleware with matching properties.
+
+### `.use(middleware, middlewareOptions)`
+
+Invoke a Neutrino middleware function, optionally providing options which will be passed to the middleware function.
+Middleware will be invoked with two arguments:
+
+1. The Neutrino instance
+2. The optional `middlewareOptions`
+
+For example, given the following middleware function:
+
+```js
+function middleware(neutrino, options) {
+  neutrino.config
+    .entry('index')
+    .prepend(options.entryPoint);
+}
+
+// Passing this middleware function to Neutrino, along with some options:
+neutrino.use(middleware, { entryPoint: 'babel-polyfill' });
+```
 
 ### `start(args)`
 
@@ -63,8 +229,8 @@ The `start()` method is responsible for creating a development bundle, and when
 server or source watcher. Prior to starting this process, Neutrino will trigger and wait for `prestart` events to
 finish. After it is complete, Neutrino will trigger and wait for `start` events to finish.
 
-If the Neutrino config contains options for `devServer`, then a webpack-dev-server will be started. If it is
+If the Neutrino config contains options for `devServer`, then a webpack-dev-server will be started, otherwise a Webpack
-configured for Node.js, then a build will be created, otherwise a Webpack source watcher will be started.
+source watcher will be started.
 
 Currently any `args` passed to `start()` have no effect and will be passed through to any event handlers.
 
@@ -98,9 +264,9 @@ api
 ### `test(args)`
 
 The `test()` method is responsible for gathering args needed for testing and triggering relevant events as a signal to
-test presets that they may run. Using the `test` method does nothing other than triggering these events; without a
+test presets that they may run. Using the `test` method does nothing other than triggering these events; without
-preset listening for these events, nothing will happen. Prior to starting this process, Neutrino will trigger and wait
+middleware listening for these events, nothing will happen. Prior to starting this process, Neutrino will trigger and
-for `pretest` events to finish. After it is complete, Neutrino will trigger and wait for
+wait for `pretest` events to finish. After it is complete, Neutrino will trigger and wait for
 `test` events to finish, in which test runners will do their work.
 
 Any `args` passed to `test()` are passed on to the event handles and typically have properties for an array of
@@ -127,8 +293,7 @@ api
 
 While tools like webpack-chain provide a convenient API for creating Webpack configurations, this is not a format that
 is understandable by Webpack. With `getWebpackOptions()`, the webpack-chain instance at `.config` will be converted to
-an options object readable directly by Webpack. This call is cached, so subsequent calls to `getWebpackOptions` will
+an configuration object readable directly by Webpack.
-result in the config being rendered only once, but the cached value returned afterwards.
 
 ```js
 api.getWebpackOptions(); // -> { ... }
@@ -177,13 +342,36 @@ if (failed) {
 }
 ```
 
-### `_devServer`
+### `devServer()`
 
-This method is used internally to generate an instance of webpack-dev-server during `start()`. It returns a promise that
+This method is used internally to generate an instance of webpack-dev-server when using `start()`. It returns a promise
-resolves when the process receives a `SIGINT` event to stop.
+that resolves when the process receives a `SIGINT` event to stop.
 
 ```js
 api
-  ._devServer()
+  .devServer()
   .then(() => console.log('Exiting process...'));
 ```
+
+### `builder()`
+
+This method is used internally to generate an instance of a Webpack compiler when using `build()`. It returns a promise
+that resolves when the Webpack build has completed, or rejects if the build fails.
+
+```js
+api
+  .builder()
+  .then(() => console.log('Exiting process...'))
+  .catch(() => console.error('Build failed!'));
+```
+
+### `watcher()`
+
+This method is used internally to generate an instance of a Webpack source watcher when using `start()`. It returns a promise
+that resolves when the process receives a `SIGINT` event to stop and the watcher has closed.
+
+```js
+api
+  .watcher()
+  .then(() => console.log('Exiting process, done watching...'));
+```

docs/cli/README.md

@@ -1,6 +1,16 @@
 # Neutrino CLI
 
-Using the command-line interface is the preferred way of interacting with Neutrino. Let's take a look at its usage.
+Using the command-line interface is the preferred and simplest way of interacting with Neutrino.
+
+When using the Neutrino CLI, you provide a list of presets for the API to attempt to load and merge configurations for.
+Each preset will attempt to be loaded from the current working directory's `node_modules`, nested within, by name, or
+relative file path. If it cannot be found, an exception will be thrown.
+
+In addition to any provided presets, Neutrino will also attempt to load configuration data from the package.json
+residing in the current working directory. If this package.json contains an object at `neutrino.config`, this data
+will be merged with the Neutrino configuration after all presets and middleware have been loaded.
+
+Let's take a look at the CLI usage.
 
 ## `--help`
 
@@ -14,6 +24,7 @@ Commands:
   test [files..]  Run all suites from the test directory or provided files
 
 Options:
+  --inspect  Output a string representation of the configuration used by Neutrino and exit   [boolean]
   --presets  A list of Neutrino presets used to configure the build                          [array] [default: []]
   --version  Show version number                                                             [boolean]
   --help     Show help                                                                       [boolean]
@@ -42,18 +53,59 @@ The Neutrino CLI will still attempt to load any presets defined in the project's
 `config.presets`, meaning that options set by package.json presets can have their values overridden by
 `--presets` presets.
 
-## neutrino start
+## `--inspect`
+
+The `--inspect` flag can be used to write out a stringified version of the Webpack configuration which has been
+accumulated by all middleware. When using the `--inspect` flag, the Neutrino CLI will still import all presets and
+middleware that has been supplied, but will then exit after logging the configuration to stdout. No builds, servers, or
+watchers will be started.
+
+```bash
+❯ neutrino start --inspect --presets neutrino-preset-react neutrino-preset-jest
+```
+
+This could also be used to help create diffs between configuration changes. Take the following command:
+
+```bash
+❯ neutrino start --inspect --presets neutrino-preset-react neutrino-preset-jest
+```
+
+We can capture this inspection to a file, and capture the change by adding a preset override:
+
+```bash
+❯ neutrino start --inspect --presets neutrino-preset-react neutrino-preset-jest > a.config
+❯ neutrino start --inspect --presets neutrino-preset-react neutrino-preset-jest override.js > b.config
+```
+
+Using `git diff a.config b.config`, we get a pretty diff of the configuration change:
+
+```diff
+diff --git a/a.config b/b.config
+index 3356802..d4d82ef 100644
+--- a/a.config
++++ b/b.config
+@@ -3,6 +3,7 @@
+   devtool: 'source-map',
+   entry: {
+     index: [
++      'babel-polyfill',
+       '/node/src/index.js'
+     ]
+   },
+```
+
+## `neutrino start`
 
 Using the command `neutrino start` builds a project in development mode, also starting a development server or source
 watcher depending on the preset or config options used. This command sets the `NODE_ENV` environment variable to
 `development`.
 
-## neutrino build
+## `neutrino build`
 
 Using the command `neutrino build` builds a project in production mode, rendering static assets to the configured build
 output destination. This command sets the `NODE_ENV` environment variable to `production`.
 
-## neutrino test
+## `neutrino test`
 
 Using the command `neutrino test` passes execution onto a test runner preset. It is up to the preset being used to
 determine how source files are built or provided to tests. See your particular test preset for details. This
@@ -74,7 +126,7 @@ Options:
 ```
 
 Using the command `neutrino test` will execute every test file located in your
-[testing directory](/project-layout#Testing). You may also provide to this command the specific test files you wish
+[testing directory](../project-layout#Testing). You may also provide to this command the specific test files you wish
 to run individually. It is important to note that when combined with the `--presets` parameter, you should use two
 dashes after the last preset to denote the end of the presets and the beginning of the test files.
 
@@ -99,7 +151,6 @@ supports it.
 ❯ neutrino test --coverage
 ```
 
-
 ## Exit codes
 
 When the CLI creates an instance of Neutrino, it waits for all commands to either resolve or reject their Promise.

docs/contributing/README.md

@@ -9,7 +9,7 @@ community.
 ### Participation Conduct
 
 In order to ensure everyone has a fair, pleasant, and inclusive experience contributing to Neutrino, we ask that you
-abide by our [community participation guidelines](/contributing/code-of-conduct.md), based on the
+abide by our [community participation guidelines](./code-of-conduct.md), based on the
 [Contributor Covenant](http://contributor-covenant.org/). Please read and understand it for everyone's benefit.
 
 Following these guidelines helps to communicate that you respect the time of the developers managing
@@ -63,7 +63,7 @@ possible.
 ## Getting started
 
 Most contributions will involve working with the neutrino-dev codebase. Please refer to the [development
-documentation](/contributing/development.md) for technical details on getting started.
+documentation](./development.md) for technical details on getting started.
 
 ## Filing bugs and issues
 

docs/contributing/development.md

@@ -1,6 +1,6 @@
 # Developing Neutrino
 
-Developing and contributing to Neutrino and its core presets is done through our monorepo located at
+Developing and contributing to Neutrino, its core presets, and middleware is done through our monorepo located at
 https://github.com/mozilla-neutrino/neutrino-dev. The code is broken up into a couple different sections:
 packages and documentation.
 
@@ -17,7 +17,8 @@ Developing for neutrino-dev requires:
 
 ## Getting started
 
-The first step to start developing neutrino-dev is forking the repository to your own GitHub account.
+The first step to start developing neutrino-dev is
+[forking the repository to your own GitHub account](https://help.github.com/articles/fork-a-repo/).
 
 <a href="https://github.com/mozilla-neutrino/neutrino-dev/fork" target="_blank">Fork mozilla-neutrino/neutrino-dev on GitHub</a>
 
@@ -170,7 +171,7 @@ in order to add files that should be committed. Give your changes a descriptive
 
 Now if you open the GitHub page for your repository, GitHub should display a button to open a pull request for
 the branch and commit you just pushed. When filling out the details of the pull request, try to be as descriptive
-as possible, following our detailed [contribution guidelines](/contributing/README.md).
+as possible, following our detailed [contribution guidelines](./README.md).
 
 ### Congrats!
 

docs/creating-presets.md

@@ -10,11 +10,14 @@ and dependencies necessary to accomplish those use cases:
 
 ## Getting Started
 
-Neutrino presets are Node.js modules or packages that export a function which accepts a Neutrino instance. You can use
+Neutrino presets are Node.js modules or packages that export a function which accepts a Neutrino instance. We call these
-this instance to modify the configuration, provide your own, expose custom options for your preset, listen for build
+functions "Neutrino middleware", as they sit between the middle of Neutrino and Webpack, modifying a configuration with
+each subsequent middleware call. You can use the Neutrino instance provided to the middleware function to modify
+the configuration, provide your own configuration, expose custom options for your preset, listen for build
 events, and execute functionality.
 
-At a bare minimum, let's start with our package boilerplate for an empty Neutrino preset:
+Neutrino presets are just Neutrino middleware that encapsulate a specific project need. At a bare minimum, let's start
+by exporting a middleware function for an empty Neutrino preset:
 
 ```js
 module.exports = neutrino => {
@@ -22,7 +25,7 @@ module.exports = neutrino => {
 };
 ```
 
-If you are using Babel or Neutrino to build your preset (so meta) with ES modules:
+If you are using Babel or Neutrino to build your preset (very meta) with ES modules:
 
 ```js
 export default neutrino => {
@@ -32,13 +35,13 @@ export default neutrino => {
 
 ## Configuring
 
-The Neutrino instance provided to your custom configurator has a `config` property that is an instance of
+The Neutrino instance provided to your middleware function has a `config` property that is an instance of
-[webpack-chain](https://github.com/mozilla-neutrino/webpack-chain/tree/v1.4.3). We won't go in-depth of all the configuration
+[webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). We won't go in-depth of all the configuration
-possibilities here, but encourage you to check out the documentation for webpack-chain for instruction on your
+possibilities here, but encourage you to check out the documentation for webpack-chain for instructions on your
-particular use case.
+particular use cases.
 
-This `neutrino.config` is an accumulation of all configuration set up to this moment. Every Neutrino preset interacts
+This `neutrino.config` is an accumulation of all configuration set up to this moment. All Neutrino presets and
-with and makes changes through this config, which is all available to your preset.
+middleware interacts with and makes changes through this config, which is all available to your preset.
 
 ## Events
 
@@ -61,10 +64,10 @@ module.exports = neutrino => {
 
 ## Including and merging other presets
 
-If your preset depends on other Neutrino presets, or you are creating a preset that is a combination of multiple
+If your preset depends on other Neutrino presets and/or middleware, or you are creating a preset that is a combination
-presets, you can install them as dependencies and simply call them from your preset, providing them with your Neutrino
+of multiple presets and/or middleware, you can install them as dependencies and simply have Neutrino use them as
-instance. When users install your preset, they will bring along your dependencies defined with your package without
+middleware. When users install your preset, they will bring along these dependencies defined with your package without
-needing also to include your extended presets in their own commands.
+needing to to include your extended presets in their own commands.
 
 _Example: Define a Neutrino preset which combines Node.js and Mocha presets._
 
@@ -73,8 +76,8 @@ const node = require('neutrino-preset-node');
 const mocha = require('neutrino-preset-mocha');
 
 module.exports = neutrino => {
-  node(neutrino);
+  neutrino.use(node);
-  mocha(neutrino);
+  neutrino.use(mocha);
   
   // neutrino.config now contains the accumulation of configuration from
   // the Node.js and Mocha presets
@@ -87,6 +90,9 @@ Let's create a preset from scratch which allows users to augment their project w
 [JavaScript Standard Style](http://standardjs.com/). For this sample preset we are using
 [Yarn](https://yarnpkg.com) for managing dependencies, but you may use the npm client if you desire.
 
+**Important: this preset is not meant to be functional; rather it is used to demonstrate the concepts of creating
+presets.**
+
 ```bash
 # Create a new directory for your project and change into it:
 mkdir neutrino-preset-standard-style && cd neutrino-preset-standard-style
@@ -111,27 +117,31 @@ module.exports = neutrino => {
     .rule('lint')
       .pre()
       .test(/\.jsx?$/)
-      .include(path.join(process.cwd(), 'src'))
+      .include
-      .loader('standard', require.resolve('standard-loader'), {
+        .add(neutrino.options.source)
-        snazzy: false
+        .end()
-      });
+      .use('standard')
+        .loader(require.resolve('standard-loader'))
+        .options({ snazzy: false });
 };
 ```
 
 ## Custom Data
 
 If you want to expose custom options for your preset that are not appropriate to be stored in the Neutrino config,
-there is a `neutrino.custom` object namespace you can attach to. This way you can document to others how they can
+there is a `neutrino.options` object namespace you can attach to. This way you can document to others how they can
-go about affecting how your preset works.
+go about affecting how your preset works. In addition, you may also instruct users of your preset to override these
+options in either their package.json at `neutrino.options` or using `neutrino.options` in their advanced overrides.
+You can then merge these options back with your defaults at `neutrino.options` when needed.
 
 _Example:_
 
 ```js
 module.exports = neutrino => { 
-  neutrino.custom.standardStyle = {
+  neutrino.options.standardStyle = Object.assign({
     quiet: false,
     logLevel: 'warn'
-  };
+  }, neutrino.options.standardStyle);
   
   // ...
 };
@@ -141,7 +151,120 @@ module.exports = neutrino => {
 
 When working with paths, remember that your preset will be running in the context of a project. You should take care
 to define application paths by referencing the current working directory with `process.cwd()`. For example, if you
-wanted to work with the project's "src" directory, you would merge the path via `path.join(process.cwd(), 'src')`
+wanted to work with the project's "src" directory, you would merge the path via `path.join(process.cwd(), 'src')`.
+
+Neutrino provides a number of paths that have been defaulted through `neutrino.options` or configured by the user.
+Please consider using these paths for your preset so they play nice with others.
+
+### `options.root`
+
+Set the base directory which Neutrino middleware and presets operate on. Typically this is the project directory where
+the package.json would be located. If the option is not set, Neutrino defaults it to `process.cwd()`. If a relative
+path is specified, it will be resolved relative to `process.cwd()`; absolute paths will be used as-is.
+
+```js
+module.exports = neutrino => {
+  // if not specified, defaults to process.cwd()
+  neutrino.options.root;
+  
+  // relative, resolves to process.cwd() + ./website
+  neutrino.options.root = './website';
+  
+  // absolute
+  neutrino.options.root = '/code/website';
+};
+```
+
+### `options.source`
+
+Set the directory which contains the application source code. If the option is not set, Neutrino defaults it to `src`.
+If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be used as-is.
+
+```js
+module.exports = neutrino => {
+  // if not specified, defaults to options.root + src
+  neutrino.options.source;
+  
+  // relative, resolves to options.root + ./lib
+  neutrino.options.source = './lib';
+  
+  // absolute
+  neutrino.options.source = '/code/website/lib';
+};
+```
+
+### `options.output`
+
+Set the directory which will be the output of built assets. If the option is not set, Neutrino defaults it to `build`.
+If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be used as-is.
+
+```js
+module.exports = neutrino => {
+  // if not specified, defaults to options.root + build
+  neutrino.options.output;
+  
+  // relative, resolves to options.root + ./dist
+  neutrino.options.output = './dist';
+  
+  // absolute
+  neutrino.options.output = '/code/website/dist';
+};
+```
+
+### `options.tests`
+
+Set the directory that contains test files. If the option is not set, Neutrino defaults it to `test`.
+If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be used as-is.
+
+```js
+module.exports = neutrino => {
+  // if not specified, defaults to options.root + test
+  neutrino.options.tests;
+  
+  // relative, resolves to options.root + ./testing
+  neutrino.options.tests = './testing';
+  
+  // absolute
+  neutrino.options.tests = '/code/website/testing';
+};
+```
+
+### `options.entry`
+
+Set the main entry point for the application. If the option is not set, Neutrino defaults it to `index.js`.
+If a relative path is specified, it will be resolved relative to `options.source`; absolute paths will be used as-is.
+
+```js
+module.exports = neutrino => {
+  // if not specified, defaults to options.source + index.js
+  neutrino.options.entry;
+  
+  // relative, resolves to options.source + ./entry.js
+  neutrino.options.entry = './entry.js';
+  
+  // absolute
+  neutrino.options.entry = '/code/website/lib/entry.js';
+};
+```
+
+### `options.node_modules`
+
+Set the directory which contains the Node.js modules of the project. If the option is not set, Neutrino defaults it to
+`node_modules`. If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be
+used as-is.
+
+```js
+module.exports = neutrino => {
+  // if not specified, defaults to options.root + node_modules
+  neutrino.options.node_modules;
+  
+  // relative, resolves to options.root + ./modules
+  neutrino.options.node_modules = './modules';
+  
+  // absolute
+  neutrino.options.node_modules = '/code/website/modules';
+};
+```
 
 ## Loader and Babel modules
 
@@ -158,5 +281,5 @@ name of the module off to be required by Webpack or Babel, instead pass the path
 
 When your preset is ready to be used by others, feel free to publish and distribute! By putting your preset on npm,
 GitHub, or another location, you can share the hard work put into abstracting away configuration and save everyone
-in the community time and effort. As long as Neutrino can require your preset, it puts no restrictions on where
+in the community time and effort. As long as the Neutrino CLI or another preset can require your preset, it puts no
-you want to host it.
+restrictions on where you want to host it.

docs/customization/README.md

@@ -6,12 +6,13 @@ context of a project without resorting to creating and publishing an entirely in
 
 ### Simple Customization
 
-By defining a configuration object within your package.json, Neutrino will merge this information with that provided by
+By defining an object within your package.json at `neutrino`, Neutrino will merge this information with that provided by
-your preset, effectively overriding those options with your custom data.
+your presets or middleware, overriding the configuration and options with your own preferences.
 
 ### Advanced Customization
 
-You can also create a configuration override directly in your project which can extend the presets you are using.
+You can also create a configuration override directly in your project which can extend the presets and middleware you
+are using.
 
 ---
 

docs/customization/advanced.md

@@ -5,26 +5,36 @@ to the way your Neutrino preset is building your project. If you need more custo
 augmenting your project's package.json, consider using this advanced configuration guide to modify your build as
 needed.
 
-## Creating a project-specific preset
+## Creating a project-specific override
 
-Neutrino configurations are backed by [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain/tree/v1.4.3), a library for
+Neutrino configurations are backed by [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain), a library for
 making modifications to a Webpack configuration using a fluent or chained API. When your project needs more advanced
 build overrides, you will be interacting with this API in order to perform modifications.
 
-First, we need to create a project-specific preset to make these changes. This can either be a JS file or a directory
+First, we need to create a project-specific override to make these changes. This can either be a JS file or a directory
 with an `index.js` file. Since Neutrino uses Node.js and Webpack for interacting with presets, it is helpful to
-understand that this is a Node.js module. By exporting a function from your module, you will be provided with a Neutrino
+understand that this is a Node.js module. By exporting a middleware function from your module, you will be provided with
-instance for modifying the build. Let's create a file called `neutrino-custom.js` in the root of our example project:
+a Neutrino instance for modifying the build. Let's create a file called `override.js` in the root of our example
+project:
 
 ```js
-// neutrino-custom.js
+// override.js
 module.exports = neutrino => {
   // ...
 };
 ```
 
-At the moment our custom configurator isn't doing anything, but it does get us far enough to be able to tell Neutrino
+The signature of this function is what we call "Neutrino middleware". If you're familiar with middleware from the
-to use it for additional configuration. Modify your package.json and add `neutrino-custom.js` as an additional preset.
+Express/connect world, this works similarly. When using Express middleware, you provide a function to Express which
+receives arguments to modify a request or response along its lifecycle. There can be a number of middleware functions
+that Express can load, each one potentially modifying a request or response in succession.
+
+When you customize Neutrino with an override, you export a Neutrino middleware function, except this is typically used
+to override Neutrino's configuration. Every preset or middleware that Neutrino has loaded follows this same middleware
+pipeline.
+
+At the moment our custom override isn't doing anything, but it does get us far enough to be able to tell Neutrino
+to use it for additional configuration. Modify your package.json and add `override.js` as an additional preset.
 
 _Note: Neutrino will attempt to load this module relative to the current working directory, which should be the root of
 your project._
@@ -35,7 +45,7 @@ your project._
     "presets": [
       "neutrino-preset-react",
       "neutrino-preset-karma",
-      "neutrino-custom.js"
+      "override.js"
     ]  
   },
   "scripts": {
@@ -44,18 +54,145 @@ your project._
 }
 ```
 
-Other than actually changing the config, that is all the setup necessary for Neutrino to pick up your custom changes.
+Other than actually changing the build configuration or Neutrino options, that is all the setup necessary for Neutrino
+to pick up your custom changes.
+
+## Overriding Neutrino options
+
+Neutrino has a number of useful options for customizing its behavior, as well as the behavior of presets and middleware.
+You can override these options using an object at `neutrino.options`.
+
+**Important! Some of these options are used by presets and middleware to determine their path locations for building.
+Making changes to these in advanced configuration will usually mean needing to set Neutrino options before other presets
+are loaded, and overriding build configuration after the presets have loaded. Consider using
+[simple customization](./simple.md) for setting Neutrino options and preset/middleware-specific options.**
+
+### `options.root`
+
+Set the base directory which Neutrino middleware and presets operate on. Typically this is the project directory where
+the package.json would be located. If the option is not set, Neutrino defaults it to `process.cwd()`. If a relative
+path is specified, it will be resolved relative to `process.cwd()`; absolute paths will be used as-is.
+
+```js
+module.exports = neutrino => {
+  // if not specified, defaults to process.cwd()
+  neutrino.options.root;
+  
+  // relative, resolves to process.cwd() + ./website
+  neutrino.options.root = './website';
+  
+  // absolute
+  neutrino.options.root = '/code/website';
+};
+```
+
+### `options.source`
+
+Set the directory which contains the application source code. If the option is not set, Neutrino defaults it to `src`.
+If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be used as-is.
+
+```js
+module.exports = neutrino => {
+  // if not specified, defaults to options.root + src
+  neutrino.options.source;
+  
+  // relative, resolves to options.root + ./lib
+  neutrino.options.source = './lib';
+  
+  // absolute
+  neutrino.options.source = '/code/website/lib';
+};
+```
+
+### `options.output`
+
+Set the directory which will be the output of built assets. If the option is not set, Neutrino defaults it to `build`.
+If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be used as-is.
+
+```js
+module.exports = neutrino => {
+  // if not specified, defaults to options.root + build
+  neutrino.options.output;
+  
+  // relative, resolves to options.root + ./dist
+  neutrino.options.output = './dist';
+  
+  // absolute
+  neutrino.options.output = '/code/website/dist';
+};
+```
+
+### `options.tests`
+
+Set the directory that contains test files. If the option is not set, Neutrino defaults it to `test`.
+If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be used as-is.
+
+```js
+module.exports = neutrino => {
+  // if not specified, defaults to options.root + test
+  neutrino.options.tests;
+  
+  // relative, resolves to options.root + ./testing
+  neutrino.options.tests = './testing';
+  
+  // absolute
+  neutrino.options.tests = '/code/website/testing';
+};
+```
+
+### `options.entry`
+
+Set the main entry point for the application. If the option is not set, Neutrino defaults it to `index.js`.
+If a relative path is specified, it will be resolved relative to `options.source`; absolute paths will be used as-is.
+
+```js
+module.exports = neutrino => {
+  // if not specified, defaults to options.source + index.js
+  neutrino.options.entry;
+  
+  // relative, resolves to options.source + ./entry.js
+  neutrino.options.entry = './entry.js';
+  
+  // absolute
+  neutrino.options.entry = '/code/website/lib/entry.js';
+};
+```
+
+### `options.node_modules`
+
+Set the directory which contains the Node.js modules of the project. If the option is not set, Neutrino defaults it to
+`node_modules`. If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be
+used as-is.
+
+```js
+module.exports = neutrino => {
+  // if not specified, defaults to options.root + node_modules
+  neutrino.options.node_modules;
+  
+  // relative, resolves to options.root + ./modules
+  neutrino.options.node_modules = './modules';
+  
+  // absolute
+  neutrino.options.node_modules = '/code/website/modules';
+};
+```
+
+### Middleware or preset options
+
+Some middleware and presets also have their own custom options. Consult the documentation for the package for specific
+details on its customization.
 
-## Configuring
+## Overriding build configuration
 
 The Neutrino instance provided to your custom configurator has a `config` property that is an instance of
-[webpack-chain](https://github.com/mozilla-neutrino/webpack-chain/tree/v1.4.3). We won't go in-depth of all the configuration
+[webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). We won't go in-depth of all the configuration
 possibilities here, but encourage you to check out the documentation for webpack-chain for instruction on your
-particular use case.
+particular use case. Just know that you can use webpack-chain to modify any part of the underlying Webpack configuration
+using its API.
 
-This `neutrino.config` is an accumulation of all configuration set up to this moment. Every Neutrino preset interacts
+This `neutrino.config` is an accumulation of all configuration up to this moment. All Neutrino middleware and presets
-with and makes changes through this config, which is all available to you. For example, if you are using the presets
+interact with and make changes through this config, which is all available to you. For example, if you are using the
-`neutrino-preset-react` and `neutrino-preset-karma`, any options set can be extended, manipulated, or removed.
+presets `neutrino-preset-react` and `neutrino-preset-karma`, any config set can be extended, manipulated, or removed.
 
 _Example: Neutrino's React preset adds `.jsx` as a module extension. Let's remove it._
 
@@ -72,14 +209,14 @@ v4.2. This preset has a rule named "compile" and a loader named "babel"._
 module.exports = neutrino => {
   neutrino.config.module
     .rule('compile')
-      .loader('babel', ({ options }) => {
+    .loader('babel', options => {
       options.presets[0][1].targets.node = 4.2;
       
-        return { options };
+      return options;
     });
 };
 ```
 
 Presets can also have their own custom data in addition to the Neutrino config. See your respective preset for details.
-Again, rather than reiterate the documentation for [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain/tree/v1.4.3) here,
+Again, rather than reiterate the documentation for [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain)
-please refer to its documentation for all ways you can modify a config instance to solve your use cases.
+here, please refer to its documentation for all ways you can modify a config instance to solve your use cases.

docs/customization/simple.md

@@ -2,18 +2,22 @@
 
 No two JavaScript projects are ever the same, and as such there may be times when you will need to make modifications
 to the way your Neutrino preset is building your project. By defining a configuration object within your package.json,
-Neutrino will merge this information with that provided by your preset, effectively overriding those options with your
+Neutrino will merge this information with those provided by your presets, overriding those options with your custom
-custom data.
+configuration.
+
+_Note: Using package.json for customization tends to be quite verbose for anything more than simple overrides. If this
+is not to your liking, consider moving your overrides to their own file using
+[Advanced Customization](./advanced.md)._
 
 ## Prepare package.json
 
-First, you will need to define a `config` section within your package.json. You
+First, you will need to define a `neutrino` section within your package.json. You
-[may have already done this](/usage.md#using-multiple-presets) if you
+[may have already done this](../usage.md#using-multiple-presets) if you
-specified your presets through the `config` as opposed to flags through `scripts`:
+specified your presets through `neutrino` as opposed to flags through `scripts`:
 
 ```json
 {
-  "config": {
+  "neutrino": {
     "presets": [
       "neutrino-preset-react",
       "neutrino-preset-karma"
@@ -26,13 +30,153 @@ specified your presets through the `config` as opposed to flags through `scripts
 }
 ```
 
-Add a new property to `config` named `neutrino`. This will be an object where we can provide configuration data:
+## Overriding Neutrino options
+
+Neutrino has a number of useful options for customizing its behavior, as well as the behavior of presets and middleware.
+You can override these options using an object at `neutrino.options`:
+
+### `options.root`
+
+Set the base directory which Neutrino middleware and presets operate on. Typically this is the project directory where
+the package.json would be located. If the option is not set, Neutrino defaults it to `process.cwd()`. If a relative
+path is specified, it will be resolved relative to `process.cwd()`; absolute paths will be used as-is.
+
+```js
+{
+  "neutrino": {
+    "options": {
+      // if not specified, defaults to process.cwd()
+      
+      // relative, resolves to process.cwd() + ./website
+      "root": "./website",
+
+      // absolute
+      "root": "/code/website"
+    }
+  }
+}
+```
+
+### `options.source`
+
+Set the directory which contains the application source code. If the option is not set, Neutrino defaults it to `src`.
+If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be used as-is.
+
+```js
+{
+  "neutrino": {
+    "options": {
+      // if not specified, defaults to options.root + src
+        
+      // relative, resolves to options.root + ./lib
+      "source": "./lib",
+      
+      // absolute
+      "source": "/code/website/lib"
+    }
+  }
+}
+```
+
+### `options.output`
+
+Set the directory which will be the output of built assets. If the option is not set, Neutrino defaults it to `build`.
+If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be used as-is.
+
+```js
+{
+  "neutrino": {
+    "options": {
+      // if not specified, defaults to options.root + build
+        
+      // relative, resolves to options.root + ./dist
+      "output": "./dist",
+      
+      // absolute
+      "output": "/code/website/dist"
+    }
+  }
+}
+```
+
+### `options.tests`
+
+Set the directory that contains test files. If the option is not set, Neutrino defaults it to `test`.
+If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be used as-is.
+
+```js
+{
+  "neutrino": {
+    "options": {
+      // if not specified, defaults to options.root + test
+        
+      // relative, resolves to options.root + ./testing
+      "tests": "./testing",
+      
+      // absolute
+      "tests": "/code/website/testing"
+    }
+  }
+}
+```
+
+### `options.entry`
+
+Set the main entry point for the application. If the option is not set, Neutrino defaults it to `index.js`.
+If a relative path is specified, it will be resolved relative to `options.source`; absolute paths will be used as-is.
+
+```js
+{
+  "neutrino": {
+    "options": {
+      // if not specified, defaults to options.source + index.js
+        
+      // relative, resolves to options.source + ./entry.js
+      "entry": "./entry.js",
+      
+      // absolute
+      "entry": "/code/website/lib/entry.js"
+    }
+  }
+}
+```
+
+### `options.node_modules`
+
+Set the directory which contains the Node.js modules of the project. If the option is not set, Neutrino defaults it to
+`node_modules`. If a relative path is specified, it will be resolved relative to `options.root`; absolute paths will be
+used as-is.
+
+```js
+{
+  "neutrino": {
+    "options": {
+      // if not specified, defaults to options.root + node_modules
+        
+      // relative, resolves to options.root + ./modules
+      "node_modules": "./modules"
+      
+      // absolute
+      "node_modules": "/code/website/modules"
+    }
+  }
+}
+```
+
+### Middleware or preset options
+
+Some middleware and presets also have their own custom options. Consult the documentation for the package for specific
+details on its customization.
+
+## Overriding build configuration
+
+Add a new property to `neutrino` named `config`. This will be an object where we can provide configuration data:
 
 ```json
 {
-  "config": {
-    "presets": [],
   "neutrino": {
+    "presets": [],
+    "config": {
 
     }
   }
@@ -40,7 +184,8 @@ Add a new property to `config` named `neutrino`. This will be an object where we
 ```
 
 Populate this object with configuration overrides. This is not a Webpack configuration, but rather a Neutrino-compatible
-object based on [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain/tree/v1.4.3).
+object based on [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). A schematic of what this structure
+looks like is located on the [webpack-chain docs](https://github.com/mozilla-neutrino/webpack-chain#merging-config).
 
 ## Usage
 
@@ -53,8 +198,8 @@ _Example: Define an entry point named `vendor` that bundles React packages separ
 
 ```json
 {
-  "config": {
   "neutrino": {
+    "config": {
       "entry": {
         "vendor": [
           "react",
@@ -82,7 +227,7 @@ Using `module.rule.loader` allows to you define the Webpack loader and its optio
 This loader is usually a `dependency` or `devDependency` of your project. Each `loader` object can specify a property
 for the string `loader` and an `options` object.
 
-_Example: Add LESS loading to the project, by extending the `css` rule._
+_Example: Add LESS loading to the project, by overriding the `style` rule._
 
 ```json
 {
@@ -90,11 +235,11 @@ _Example: Add LESS loading to the project, by extending the `css` rule._
     "less": "^2.7.2",
     "less-loader": "^2.2.3"
   },
-  "config": {
   "neutrino": {
+    "config": {
       "module": {
         "rule": {
-          "css": {
+          "style": {
             "test": "\\.less$",
             "loader": {
               "less": {
@@ -122,8 +267,8 @@ _Example: Change the public path of the application._
 
 ```json
 {
-  "config": {
   "neutrino": {
+    "config": {
       "output": {
         "publicPath": "https://cdn.example.com/assets/"
       }
@@ -140,8 +285,8 @@ _Example: mock the `__filename` and `__dirname` Node.js globals._
 
 ```json
 {
-  "config": {
   "neutrino": {
+    "config": {
       "node": {
         "__filename": "mock",
         "__dirname": "mock"
@@ -159,8 +304,8 @@ _Example: gzip the application when serving and listen on port 9000._
 
 ```json
 {
-  "config": {
   "neutrino": {
+    "config": {
       "devServer": {
         "compress": true,
         "port": 9000
@@ -173,15 +318,15 @@ _Example: gzip the application when serving and listen on port 9000._
 ### Resolve
 
 Use `resolve` to change how modules are resolved. When using `resolve.extensions` and `resolve.modules`, these should be
-specified as arrays, and will be merged with their respective definitions used in inherited presets. Any additional
+specified as arrays, and will be merged with their respective definitions used in inherited presets. See the
-properties attached to `resolve` not defined below will be set on the final module configuration.
+webpack-chain docs for more details on this structure.
 
 _Example: Add `.mjs` as a resolving extension and specify modules are located in a `custom_modules` directory._
 
 ```json
 {
-  "config": {
   "neutrino": {
+    "config": {
       "resolve": {
         "extensions": [".mjs"],
         "modules": ["custom_modules"]
@@ -195,15 +340,14 @@ _Example: Add `.mjs` as a resolving extension and specify modules are located in
 
 Use `resolveLoader` to change how loader packages are resolved. When using `resolveLoader.extensions` and
 `resolveLoader.modules`, these should be specified as arrays, and will be merged with their respective definitions used
-in inherited presets. Any additional properties attached to `resolveLoader` not defined below will be set on the final
+in inherited presets. See the webpack-chain docs for more details on this structure.
-module configuration.
 
 _Example: Add `.loader.js` as a loader extension and specify modules are located in a `web_loaders` directory._
 
 ```json
 {
-  "config": {
   "neutrino": {
+    "config": {
       "resolve": {
         "extensions": [".loader.js"],
         "modules": ["web_loaders"]
@@ -215,14 +359,14 @@ _Example: Add `.loader.js` as a loader extension and specify modules are located
 
 ### Additional configuration
 
-Any top-level properties you set on `config.neutrino` will be added to the configuration.
+Any top-level properties you set on `neutrino.config` will be added to the configuration.
 
 _Example: Change the Webpack performance options to error when exceeding performance budgets._
 
 ```json
 {
-  "config": {
   "neutrino": {
+    "config": {
       "performance": {
         "hints": "error"
       }
@@ -235,4 +379,4 @@ _Example: Change the Webpack performance options to error when exceeding perform
 
 With the options defined above in your package.json, you can perform a variety of build customizations on a per-project
 basis. In the event that you need more customization than what is afforded through JSON, consider either switching to
-[advanced configuration](/customization/advanced.md), or [creating your own preset](/creating-presets.md).
+[advanced configuration](./advanced.md), or [creating your own preset](../creating-presets.md).

docs/learning-resources.md

@@ -6,18 +6,16 @@ community, file an issue or submit a pull request.
 
 ## Blog Posts & Tutorials
 
-[Modern JavaScript Apps with Neutrino](https://davidwalsh.name/neutrino) by [@eliperelman](https://twitter.com/eliperelman)
+* [Modern JavaScript Apps with Neutrino](https://davidwalsh.name/neutrino) by [@eliperelman](https://twitter.com/eliperelman)
+* [Using Neutrino to jump-start modern JavaScript development](https://hacks.mozilla.org/2017/02/using-neutrino-for-modern-javascript-development/) by [@eliperelman](https://twitter.com/eliperelman)
+* [Custom Neutrino Linting](https://davidwalsh.name/neutrino-linting) by [@davidwalshblog](https://twitter.com/davidwalshblog)
 
 ## Screencasts & Videos
 
-## Starter Repositories
+## Starter Kit Repositories
 
-[Node.js Quickstart Kit](https://github.com/mozilla-neutrino/node-starter)
+* [mozilla-neutrino/node-starter](https://github.com/mozilla-neutrino/node-starter)
-
+* [mozilla-neutrino/express-starter](https://github.com/mozilla-neutrino/express-starter)
-[Express Quickstart Kit](https://github.com/mozilla-neutrino/express-starter)
+* [mozilla-neutrino/react-starter](https://github.com/mozilla-neutrino/react-starter)
-
+* [mozilla-neutrino/web-starter](https://github.com/mozilla-neutrino/web-starter)
-[React Quickstart Kit](https://github.com/mozilla-neutrino/react-starter)
+* [jerolimov/feathers-starter](https://github.com/jerolimov/feathers-starter)
-
-[Web Quickstart Kit](https://github.com/mozilla-neutrino/web-starter)
-
-[jerolimov/feathers-starter](https://github.com/jerolimov/feathers-starter)

docs/middleware/README.md

@@ -0,0 +1,124 @@
+# Middleware
+
+The basic unit of interacting with Neutrino is middleware. In Neutrino, middleware are functions
+that are provided a Neutrino instance for the intent of modifying configuration, listening for
+events, getting build metadata, or augmenting with custom functionality. At its simplest, a middleware
+function accepts a Neutrino instance argument and does nothing:
+
+```js
+function middleware(neutrino) {}
+```
+
+A middleware function can also optionally accept an `options` argument which will be fed back into
+the middleware function when used.
+
+```js
+function middleware(neutrino, options) {}
+```
+
+The signature of this function is what we call "Neutrino middleware". If you're familiar with middleware from the
+Express/connect world, this works similarly. When using Express middleware, you provide a function to Express which
+receives arguments to modify a request or response along its lifecycle. There can be a number of middleware functions
+that Express can load, each one potentially modifying a request or response in succession.
+
+Neutrino will execute middleware similarly, where each middleware function successively interacts with Neutrino along
+the lifecycle. This is done by plugging in the middleware to Neutrino via the `use()` method.
+
+```js
+const api = new Neutrino();
+
+api.use(middleware);
+api.use(middleware, options);
+```
+
+To use a concrete example, let's create middleware that adds an environment plugin:
+
+```js
+const Neutrino = require('neutrino');
+const { EnvironmentPlugin } = require('webpack');
+
+const api = new Neutrino();
+
+function env(neutrino, additionalVars = []) {
+  neutrino.config
+    .plugin('env')
+    .use(EnvironmentPlugin, ['NODE_ENV', ...additionalVars]);
+}
+
+api.use(env); // or:
+api.use(env, ['SECRET_KEY']);
+```
+
+## Loading middleware
+
+Additional middleware can also be loaded from a middleware function. This makes their composition simpler for
+consumers.
+
+```js
+// neutrino-middleware-env
+const { EnvironmentPlugin } = require('webpack');
+
+module.exports = (neutrino, additionalVars = []) => neutrino.config
+  .plugin('env')
+  .use(EnvironmentPlugin, ['NODE_ENV', ...additionalVars]);
+```
+
+```js
+// react preset (which is also middleware)
+const env = require('./neutrino-middleware-env');
+
+module.exports = neutrino => {
+  neutrino.use(env, ['SECRET_KEY']);
+  neutrino.use(/* next middleware */);
+  neutrino.use(/* next middleware */)
+};
+```
+
+## Configuring
+
+If your middleware requires configuration _outside_ of the options necessary for _running_ the middleware,
+use a closure technique for simplifying this for your middleware consumers. In short, your module will provide a
+function to consumers which, when executed, will return a Neutrino middleware function. Describing this in code:
+
+```js
+module.exports = function wrapper(...args) {
+  return function middleware(neutrino, options) {
+    // do something with neutrino, options, and args
+  };
+};
+```
+
+Let's create a contrived example using our `env` middleware. Let's use a closure to let the consumer provide an
+alternate plugin name when creating the middleware:
+
+```js
+// neutrino-middleware-env
+const { EnvironmentPlugin } = require('webpack');
+
+module.exports = (pluginName = 'env') => (neutrino, additionalVars = []) => {
+    neutrino.config
+      .plugin(pluginName)
+      .use(EnvironmentPlugin, ['NODE_ENV', ...additionalVars]);
+};
+```
+
+```js
+// react preset (which is also middleware)
+const env = require('./neutrino-middleware-env');
+
+module.exports = neutrino => {
+  neutrino.use(env('ENV-PLUGIN'), ['SECRET_KEY']);
+};
+```
+
+## Distributing
+
+If you would like your middleware to be used by others, feel free to publish and distribute! By putting your middleware
+on npm, GitHub, or another location, you can share the hard work put into abstracting away Neutrino and Webpack
+interactions and save everyone in the community time and effort. As long as the Neutrino CLI, other middleware, or
+presets can require your middleware, it puts no restrictions on where you want to host it.
+
+## Core middleware
+
+Neutrino maintains a number of core middleware packages which aid in creating the various preset packages we also
+distribute. Continue onward for documentation on these various middleware packages.

docs/middleware/neutrino-middleware-banner/README.md

@@ -0,0 +1,71 @@
+# Neutrino Banner Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-banner` is Neutrino middleware for injecting string content into source code files.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-banner` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-banner
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-banner
+```
+
+## Usage
+
+`neutrino-middleware-banner` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const banner = require('neutrino-middleware-banner');
+
+// Use with default options
+neutrino.use(banner);
+
+// Also accepts options for Webpack's BannerPlugin
+// https://webpack.js.org/plugins/banner-plugin/
+
+// Usage shows the default values of this middleware:
+neutrino.use(banner, {
+  banner: `require('source-map-support').install();`,
+  raw: true,
+  entryOnly: true
+});
+```
+
+## Customization
+
+`neutrino-middleware-banner` creates some conventions to make overriding the configuration easier once you are ready to
+make changes.
+
+### Plugins
+
+The following is a list of plugins and their identifiers which can be overridden:
+
+- `banner`: Injects string content into application source code.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-banner.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-banner.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-banner
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-chunk/README.md

@@ -0,0 +1,71 @@
+# Neutrino Chunk Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-chunk` is Neutrino middleware for optimizing Webpack bundles via `CommonsChunkPlugin`.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-chunk` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-chunk
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-chunk
+```
+
+## Usage
+
+`neutrino-middleware-chunk` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const chunk = require('neutrino-middleware-chunk');
+
+// Use with default options
+neutrino.use(chunk);
+
+// Also accepts options for Webpack's CommonsChunkPlugin
+// https://webpack.js.org/plugins/commons-chunk-plugin/
+
+// Usage shows the default values of this middleware:
+neutrino.use(chunk, {
+  minChunks: Infinity,
+  names: ['vendor', 'manifest']
+});
+```
+
+## Customization
+
+`neutrino-middleware-chunk` creates some conventions to make overriding the configuration easier once you are ready to
+make changes.
+
+### Plugins
+
+The following is a list of plugins and their identifiers which can be overridden:
+
+- `chunk`: Creates a separate file (known as a chunk), consisting of common modules shared between multiple entry
+points.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-chunk.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-chunk.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-chunk
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-clean/README.md

@@ -0,0 +1,67 @@
+# Neutrino Clean Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-clean` is Neutrino middleware for removing directories before building.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-clean` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-clean
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-clean
+```
+
+## Usage
+
+`neutrino-middleware-clean` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const clean = require('neutrino-middleware-clean');
+
+// Use with default options
+neutrino.use(clean);
+
+// Usage shows the default values of this middleware:
+neutrino.use(clean, {
+  paths: [],
+  root: neutrino.options.root
+});
+```
+
+## Customization
+
+`neutrino-middleware-clean` creates some conventions to make overriding the configuration easier once you are ready to
+make changes.
+
+### Plugins
+
+The following is a list of plugins and their identifiers which can be overridden:
+
+- `clean`: Removes directories before building.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-clean.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-clean.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-clean
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-compile-loader/README.md

@@ -0,0 +1,69 @@
+# Neutrino Compile Loader Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-compile-loader` is Neutrino middleware for compiling source code with Babel.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-compile-loader` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-compile-loader
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-compile-loader
+```
+
+## Usage
+
+`neutrino-middleware-compile-loader` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const compile = require('neutrino-middleware-compile-loader');
+
+neutrino.use(compile, {
+  include: [],
+  exclude: [],
+  babel: {}
+});
+```
+
+- `include` should be an array of paths to include in the compilation. Maps to Webpack's
+[`Rule.include`](https://webpack.js.org/configuration/module/#rule-include)
+- `babel` is a [Babel configuration object](https://babeljs.io/docs/usage/api/#options), consumed by babel-loader. Use
+this to set properties such as `presets`, `plugins`, and `env`.
+
+## Customization
+
+`neutrino-middleware-compile-loader` creates some conventions to make overriding the configuration easier once you are
+ready to make changes.
+
+### Rules
+
+The following is a list of rules and their identifiers which can be overridden:
+
+- `compile`: Compiles JS and JSX files from the `src` directory using Babel. Contains a single loader named `babel`.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-compile-loader.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-compile-loader.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-compile-loader
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-copy/README.md

@@ -0,0 +1,73 @@
+# Neutrino Copy Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-copy` is Neutrino middleware for copying files during building.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-copy` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-copy
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-copy
+```
+
+## Usage
+
+`neutrino-middleware-copy` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const copy = require('neutrino-middleware-copy');
+
+// Use with default options
+neutrino.use(copy);
+
+// Usage shows the default values of this middleware:
+neutrino.use(copy, {
+  patterns: [],
+  options: {}
+});
+```
+
+The `patterns` and `options` are defined from the [CopyWebpackPlugin](https://github.com/kevlened/copy-webpack-plugin).
+See their docs for details on valid values to specify.
+
+- `patterns`: An array of patterns specifying copy operations.
+- `options`: An object specifying copy options.
+
+## Customization
+
+`neutrino-middleware-copy` creates some conventions to make overriding the configuration easier once you are ready to
+make changes.
+
+### Plugins
+
+The following is a list of plugins and their identifiers which can be overridden:
+
+- `copy`: Copy files during building.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-copy.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-copy.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-copy
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-env/README.md

@@ -0,0 +1,67 @@
+# Neutrino Environment Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-copy` is Neutrino middleware for injecting environment variable definitions into
+source code at `process.env`. Always injects `process.env.NODE_ENV`, unless overridden.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-env` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-env
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-env
+```
+
+## Usage
+
+`neutrino-middleware-env` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const env = require('neutrino-middleware-env');
+
+// Use with default options
+neutrino.use(env);
+
+// Usage with additional environment variables
+neutrino.use(env, ['SECRET_KEY']);
+```
+
+This middleware optionally accepts an array of environment variables to additionally inject into source code.
+
+## Customization
+
+`neutrino-middleware-env` creates some conventions to make overriding the configuration easier once you are ready to
+make changes.
+
+### Plugins
+
+The following is a list of plugins and their identifiers which can be overridden:
+
+- `env`: Inject environment variables into source code at `process.env`.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-env.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-env.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-env
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-eslint/README.md

@@ -0,0 +1,138 @@
+# Neutrino ESLint Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-eslint` is Neutrino middleware for linting source code using ESLint and eslint-loader.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-eslint` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-eslint
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-eslint
+```
+
+## Usage
+
+`neutrino-middleware-eslint` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const eslint = require('neutrino-middleware-eslint');
+
+// Usage shows default values
+neutrino.use(eslint, {
+  test: /\.(js|jsx)$/,
+  include: [], /* Should specify either include or exclude */
+  exclude: [], /* Should specify either include or exclude */
+  eslint: {
+    failOnError: process.env.NODE_ENV !== 'development',
+     emitWarning: process.env.NODE_ENV !== 'development',
+     emitError: process.env.NODE_ENV !== 'development',
+     cwd: neutrino.options.root,
+     useEslintrc: false,
+     root: true,
+     plugins: ['babel'],
+     baseConfig: {},
+     envs: ['es6'],
+     parser: 'babel-eslint',
+     parserOptions: {
+       ecmaVersion: 2017,
+       sourceType: 'module',
+       ecmaFeatures: {
+         objectLiteralDuplicateProperties: false,
+         generators: true,
+         impliedStrict: true
+       }
+     },
+     settings: {},
+     globals: ['process'],
+    rules: {}
+  }
+});
+```
+
+- `test`: Test which files should be linted.
+- `include`: An array of paths to include in linting. Maps to Webpack's
+[`Rule.include`](https://webpack.js.org/configuration/module/#rule-include)
+- `exclude`: An array of paths to exclude from linting. Maps to Webpack's
+[`Rule.exclude`](https://webpack.js.org/configuration/module/#rule-exclude)
+- `eslint`: An ESLint CLIEngine configuration object for configuring ESLint. Use this to configure rules,
+plugins, and other [ESLint options](http://eslint.org/docs/user-guide/configuring).
+
+## Customization
+
+`neutrino-middleware-eslint` creates some conventions to make overriding the configuration easier once you are ready to
+make changes.
+
+### Rules
+
+The following is a list of rules and their identifiers which can be overridden:
+
+- `lint`: By default, lints JS and JSX files from included directories using ESLint. Contains a single loader named
+`eslint`.
+
+## Information
+
+This middleware will show errors and warnings in the console during development, and will cause a failure when
+creating a build bundle.
+
+---
+
+If you want your preset or middleware to also extend from another **ESLint configuration or preset** that you have made
+a dependency, you must use `baseConfig.extends` rather than just `extends`. This is a limitation of ESLint, not this
+middleware.
+
+---
+
+This middleware only configures a target environment for `es6`, leaving other build middleware free to add their own
+target environments. If your middleware puts restrictions on which environments it is capable of running, please
+document that clearly in your middleware.
+
+## eslintrc Config
+
+`neutrino-middleware-eslint` also provides a method for getting the ESLint configuration suitable for use in an eslintrc
+file. Typically this is used for providing hints or fix solutions to the development environment, e.g. IDEs and text
+editors. Doing this requires [creating an instance of the Neutrino API](../../api/README.md) and providing the presets uses.
+If you keep this information in `neutrino.presets` in package.json, this should be relatively straightforward. By
+providing all the presets used to Neutrino, you can ensure all the linting options used across all presets will be
+merged together for your development environment, without the need for copying, duplication, or loss of organization and
+separation.
+
+_Example: Create a .eslintrc.js file in the root of the project._
+
+```js
+// .eslintrc.js
+const Neutrino = require('neutrino');
+const pkg = require('./package.json');
+const api = new Neutrino();
+
+pkg.neutrino.presets.map(preset => neutrino.use(preset));
+
+module.exports = api.eslintrc();
+```
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-eslint.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-eslint.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-eslint
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-font-loader/README.md

@@ -0,0 +1,70 @@
+# Neutrino Font Loader Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-font-loader` is Neutrino middleware for loading and importing font files from modules.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-font-loader` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-font-loader
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-font-loader
+```
+
+## Usage
+
+`neutrino-middleware-font-loader` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const fonts = require('neutrino-middleware-font-loader');
+
+// Use with default options
+neutrino.use(fonts);
+
+// Usage showing default options
+neutrino.use(fonts, {
+  limit: '10000'
+});
+```
+
+- `limit`: Return a Data URL if the file is smaller than a byte limit.
+
+## Customization
+
+`neutrino-middleware-font-loader` creates some conventions to make overriding the configuration easier once you are
+ready to make changes.
+
+### Rules
+
+The following is a list of rules and their identifiers which can be overridden:
+
+- `woff`: Allows importing WOFF font files from modules. Contains a single loader named `url`.
+- `ttf`: Allows importing TTF font files from modules. Contains a single loader named `url`.
+- `eot`: Allows importing EOT font files from modules. Contains a single loader named `file`.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-font-loader.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-font-loader.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-font-loader
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-hml-template/README.md

@@ -0,0 +1,75 @@
+# Neutrino HTML Template Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-html-template` is Neutrino middleware for automatically creating HTML files for configured
+entry-points.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-html-template` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-html-template
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-html-template
+```
+
+## Usage
+
+`neutrino-middleware-html-template` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const template = require('neutrino-middleware-html-template');
+
+// Usage shows default values
+// Accepts options specified by HtmlWebpackTemplate
+// https://github.com/jaketrent/html-webpack-template
+neutrino.use(template, {
+  inject: false,
+  appMountId: 'root',
+  xhtml: true,
+  mobile: true,
+  minify: {
+    useShortDoctype: true,
+    keepClosingSlash: true,
+    collapseWhitespace: true,
+    preserveLineBreaks: true
+  }
+});
+```
+
+## Customization
+
+`neutrino-middleware-html-template` creates some conventions to make overriding the configuration easier once you are ready to
+make changes.
+
+### Plugins
+
+The following is a list of plugins and their identifiers which can be overridden:
+
+- `html`: Automatically generates HTML files for configured entry-points.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-html-template.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-html-template.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-html-template
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-hot/README.md

@@ -0,0 +1,61 @@
+# Neutrino Hot Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-hot` is Neutrino middleware for enabled Hot Module Replacement with Webpack's
+`HotModuleReplacementPlugin`. This middleware is usually only added during development.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-hot` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-hot
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-hot
+```
+
+## Usage
+
+`neutrino-middleware-hot` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const hot = require('neutrino-middleware-hot');
+
+neutrino.use(hot);
+```
+
+## Customization
+
+`neutrino-middleware-hot` creates some conventions to make overriding the configuration easier once you are ready to
+make changes.
+
+### Plugins
+
+The following is a list of plugins and their identifiers which can be overridden:
+
+- `hot`: Enables hot module replacement.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-hot.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-hot.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-hot
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-html-loader/README.md

@@ -0,0 +1,60 @@
+# Neutrino HTML Loader Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-html-loader` is Neutrino middleware for loading and importing HTML files from modules.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-html-loader` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-html-loader
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-html-loader
+```
+
+## Usage
+
+`neutrino-middleware-html-loader` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const html = require('neutrino-middleware-html-loader');
+
+neutrino.use(html);
+```
+
+## Customization
+
+`neutrino-middleware-html-loader` creates some conventions to make overriding the configuration easier once you are
+ready to make changes.
+
+### Rules
+
+The following is a list of rules and their identifiers which can be overridden:
+
+- `html`: Allows importing HTML files from modules. Contains a single loader named `file`.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-html-loader.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-html-loader.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-html-loader
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-image-loader/README.md

@@ -0,0 +1,70 @@
+# Neutrino Image Loader Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-image-loader` is Neutrino middleware for loading and importing image files from modules.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-image-loader` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-image-loader
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-image-loader
+```
+
+## Usage
+
+`neutrino-middleware-image-loader` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const images = require('neutrino-middleware-image-loader');
+
+// Use with default options
+neutrino.use(images);
+
+// Usage showing default options
+neutrino.use(images, {
+  limit: 8192
+});
+```
+
+- `limit`: Return a Data URL if the file is smaller than a byte limit.
+
+## Customization
+
+`neutrino-middleware-image-loader` creates some conventions to make overriding the configuration easier once you are
+ready to make changes.
+
+### Rules
+
+The following is a list of rules and their identifiers which can be overridden:
+
+- `img`: Allows importing JPEG, PNG, and GIF files from modules. Contains a single loader named `url`.
+- `svg`: Allows importing SVG files from modules. Contains a single loader named `url`.
+- `ico`: Allows importing ICO files from modules. Contains a single loader named `url`.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-image-loader.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-image-loader.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-image-loader
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-loader-merge/README.md

@@ -0,0 +1,75 @@
+# Neutrino Loader Merge Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-loader-merge` is Neutrino middleware for easily performing a deep merge of options into
+a named rule and named loader in a Neutrino configuration.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-loader-merge` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-loader-merge
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-loader-merge
+```
+
+## Usage
+
+`neutrino-middleware-loader-merge` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const loaderMerge = require('neutrino-middleware-loader-merge');
+
+neutrino.use(loaderMerge('compile', 'babel'), {
+  plugins: ['object-rest-spread']
+});
+
+// Equivalent to:
+neutrino.config.module
+  .rule('compile')
+  .use('babel')
+    .tap(options => require('deepmerge')(options, {
+      plugins: ['object-rest-spread']
+    }));
+```
+
+This middleware is a factory intended to be invoked with a rule name and a loader name for which to extend the options.
+Upon invoking, it will return a middleware function to be provided to Neutrino's `use()` method.
+
+```js
+const middleware = loaderMerge(ruleName, loaderName);
+
+neutrino.use(middleware, options);
+```
+
+
+## Customization
+
+`neutrino-middleware-loader-merge` does not create any of its own conventions; it is only middleware
+for extending the options for a rule loader which has create its own conventions.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-loader-merge.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-loader-merge.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-loader-merge
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-minify/README.md

@@ -0,0 +1,62 @@
+# Neutrino Minify Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-hot` is Neutrino middleware for minifying source code using
+[`BabiliWebpackPlugin`](https://www.npmjs.com/package/babili-webpack-plugin). This middleware is usually only
+added during production builds.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-minify` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-minify
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-minify
+```
+
+## Usage
+
+`neutrino-middleware-minify` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const minify = require('neutrino-middleware-minify');
+
+neutrino.use(minify);
+```
+
+## Customization
+
+`neutrino-middleware-minify` creates some conventions to make overriding the configuration easier once you are ready to
+make changes.
+
+### Plugins
+
+The following is a list of plugins and their identifiers which can be overridden:
+
+- `minify`: Minifies source code using `BabiliWebpackPlugin`.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-minify.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-minify.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-minify
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-named-modules/README.md

@@ -0,0 +1,60 @@
+# Neutrino Named Modules Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-named-modules` is Neutrino middleware for enabling named modules output via `NamedModulesPlugin`.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-named-modules` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-named-modules
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-named-modules
+```
+
+## Usage
+
+`neutrino-middleware-named-modules` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const namedModules = require('neutrino-middleware-named-modules');
+
+neutrino.use(namedModules);
+```
+
+## Customization
+
+`neutrino-middleware-named-modules` creates some conventions to make overriding the configuration easier once you are
+ready to make changes.
+
+### Plugins
+
+The following is a list of plugins and their identifiers which can be overridden:
+
+- `named-modules`: Enables named modules for improved debugging and console output.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-named-modules.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-named-modules.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-named-modules
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-progress/README.md

@@ -0,0 +1,60 @@
+# Neutrino Progress Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-progress` is Neutrino middleware for displaying a progress bar showing the progress of a build.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-progress` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-progress
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-progress
+```
+
+## Usage
+
+`neutrino-middleware-progress` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const progress = require('neutrino-middleware-progress');
+
+neutrino.use(progress);
+```
+
+## Customization
+
+`neutrino-middleware-progress` creates some conventions to make overriding the configuration easier once you are ready to
+make changes.
+
+### Plugins
+
+The following is a list of plugins and their identifiers which can be overridden:
+
+- `progress`: Displays a bar showing progression of build.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-progress.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-progress.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-progress
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-start-server/README.md

@@ -0,0 +1,69 @@
+# Neutrino Start Server Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-start-server` is Neutrino middleware for starting a Node.js server for a file upon
+completion of a build.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-start-server` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-start-server
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-start-server
+```
+
+## Usage
+
+`neutrino-middleware-start-server` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const server = require('neutrino-middleware-start-server');
+
+// Use with default options, starting the server
+// for the main entry point, neutrino.options.entry
+neutrino.use(server);
+
+// Usage with custom server file to start
+neutrino.use(server, { name: 'custom.js' });
+```
+
+By default this middleware will start a server with the single entry point configured in Neutrino.
+This middleware optionally accepts an object with a `name` property for a path to a module which to start the server.
+
+## Customization
+
+`neutrino-middleware-start-server` creates some conventions to make overriding the configuration easier once you are ready to
+make changes.
+
+### Plugins
+
+The following is a list of plugins and their identifiers which can be overridden:
+
+- `start-server`: Start a Node.js for a configured entry point or specified file.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-start-server.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-start-server.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-start-server
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/middleware/neutrino-middleware-style-loader/README.md

@@ -0,0 +1,61 @@
+# Neutrino Style Loader Middleware
+[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
+
+`neutrino-middleware-style-loader` is Neutrino middleware for loading and importing stylesheets from modules.
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v5
+
+## Installation
+
+`neutrino-middleware-style-loader` can be installed via the Yarn or npm clients.
+
+#### Yarn
+
+```bash
+❯ yarn add neutrino-middleware-style-loader
+```
+
+#### npm
+
+```bash
+❯ npm install --save neutrino-middleware-style-loader
+```
+
+## Usage
+
+`neutrino-middleware-style-loader` can be consumed from the Neutrino API, middleware, or presets. Require this package
+and plug it into Neutrino:
+
+```js
+const styles = require('neutrino-middleware-style-loader');
+
+neutrino.use(styles);
+```
+
+## Customization
+
+`neutrino-middleware-style-loader` creates some conventions to make overriding the configuration easier once you are
+ready to make changes.
+
+### Rules
+
+The following is a list of rules and their identifiers which can be overridden:
+
+- `css`: Allows importing CSS stylesheets from modules. Contains two loaders named `style` and `css` which use
+`style-loader` and `css-loader`, respectively.
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](../../contributing/README.md) for details.
+
+[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-style-loader.svg
+[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-style-loader.svg
+[npm-url]: https://npmjs.org/package/neutrino-middleware-style-loader
+[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
+[slack-url]: https://neutrino-slack.herokuapp.com/

docs/presets/community-presets.md

@@ -6,6 +6,19 @@ A collection of Neutrino presets published on npm. In order to have your preset
 - Contain the `neutrino-preset` keyword in package.json
 - Not be deprecated
 
+In addition, your preset should also:
+
+- Have a relevant description
+- Use `neutrino` as a `peerDependency` to mark which versions of Neutrino your preset supports:
+
+```json
+{
+  "peerDependencies": {
+    "neutrino": "^5.0.0"
+  }
+}
+```
+
 It should also have a relevant description. If you prefer, you can also add your preset to the
 [neutrino-dev wiki](https://github.com/mozilla-neutrino/neutrino-dev/wiki/Community-Presets).
 

docs/presets/neutrino-lint-base/README.md

@@ -1,200 +0,0 @@
-# Neutrino Lint Base
-[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-url]
-
-`neutrino-lint-base` is an abstract Neutrino preset base that makes creating ESLint-based presets simpler. By creating
-a linting preset that extends from `neutrino-lint-base`, the development overhead and dependencies needed can be
-significantly reduced. Use it as a baseline to create your own linting presets easier and more quickly.
-
-## Features
-
-- Quickly and easily create your own Neutrino linting presets
-- Modern Babel knowledge supporting ES modules, JSX (when used with React preset), Web and Node.js apps
-- Highly visible during development, fails compilation when building for production
-- Easily extensible to customize your project as needed
-
-## Development Requirements
-
-- Node.js v6.9+
-- Yarn or npm client
-- Neutrino v4
-
-## Installation
-
-`neutrino-lint-base` can be installed via the Yarn or npm clients.
-
-#### Yarn
-
-```bash
-❯ yarn add neutrino-lint-base
-```
-
-#### npm
-
-```bash
-❯ npm install --save neutrino-lint-base
-```
-
-Your project should also install any dependencies needed to operate based on options passed to `eslint-loader` or
-ESLint's CLIEngine.
-
-## Project Layout
-
-`neutrino-lint-base` follows the standard [project layout](/project-layout.md) specified by Neutrino. This
-means that by default all project source code should live in a directory named `src` in the root of the
-project. The `.js` or `.jsx` files in this directory are the ones that will be linted by your preset.
-
-## Creating the preset
-
-Your preset will follow the same guidelines for normally creating Neutrino presets, with your preset extending
-`neutrino-lint-base`. This starts out by having your package module export a function which accepts a Neutrino instance:
-
-```js
-module.exports = neutrino => {
-  // ...
-};
-```
-
-The next step is to `require`, or `import` if your package supports it, `neutrino-lint-base` and execute it with
-Neutrino. This will add the lint base's configuration to Neutrino for your preset to extend further:
-
-```js
-const lint = require('neutrino-lint-base');
-
-module.exports = neutrino => {
-  lint(neutrino);
-  // ...
-};
-```
-
-Now comes the core of your own preset. By extending from `neutrino-lint-base`'s "lint" rule and "eslint" loader, you
-can manipulate the options as you desire. Consider using a package such as
-[`deepmerge`](https://www.npmjs.com/package/deepmerge) to make extending these options easier:
-
-_Example: Create a preset that shuts off semicolons from being required by ESLint._
-
-```js
-const lint = require('neutrino-lint-base');
-const merge = require('deepmerge');
-
-module.exports = neutrino => {
-  lint(neutrino);
-  neutrino.config.module
-    .rule('lint')
-    .loader('eslint', props => merge(props, {
-      options: {
-        rules: {
-          semi: 'off'
-        }
-      }
-    }));
-};
-```
-
-_Example: Create a preset that lints a project using the Airbnb base ESLint rules._
-
-```js
-const lint = require('neutrino-lint-base');
-const merge = require('deepmerge');
-
-module.exports = neutrino => {
-  lint(neutrino);
-  neutrino.config.module
-    .rule('lint')
-    .loader('eslint', props => merge(props, {
-      options: {
-        baseConfig: {
-          extends: ['airbnb-base']
-        }
-      }
-    }));
-};
-```
-
-Visit the [creating presets](/creating-presets.md) documentation for more detailed information on creating your own
-custom preset.
-
-## Customization
-
-`neutrino-lint-base` creates some conventions to make overriding the configuration easier once you are ready to
-make changes.
-
-### Rules
-
-The following is a list of rules and their identifiers which can be overridden:
-
-- `lint`: Lints JS and JSX files from the `src` directory using ESLint. Contains a single loader named `eslint`.
-
-## Information
-
-The lint base will show errors and warnings in the console during development, and will cause a failure when
-creating a build bundle.
-
----
-
-If you want your preset to also extend from another ESLint configuration that you have made a dependency, you must use
-`baseConfig.extends` rather than just `extends`. This is a limitation of ESLint, not this lint base.
-
-```js
-const lint = require('neutrino-lint-base');
-const merge = require('deepmerge');
-
-module.exports = neutrino => {
-  lint(neutrino);
-  neutrino.config.module
-    .rule('lint')
-    .loader('eslint', props => merge(props, {
-      options: {
-        baseConfig: {
-          extends: [
-            'YOUR_ESLINT_CONFIGURATION_BASE_A',
-            'YOUR_ESLINT_CONFIGURATION_BASE_B'
-          ]
-        }
-      }
-    }));
-};
-```
-
----
-
-The linting base only configures a target environment for `es6`, leaving other build presets free to add their own
-target environments. If your preset puts restrictions on which environments it is capable of running, please document
-that clearly in your preset.
-
-For specifics on what options are configured when using this linting base, please
-[view the source](https://github.com/mozilla-neutrino/neutrino-dev/blob/master/packages/neutrino-lint-base/src/index.js).
-
-## eslintrc Config
-
-`neutrino-lint-base` also provides a method for getting the ESLint configuration suitable for use in an eslintrc file.
-Typically this is used for providing hints or fix solutions to the development environment, e.g. IDEs and text editors.
-Doing this requires [creating an instance of the Neutrino API](/api/README.md) and providing the presets uses. If you
-keep this information in `config.presets` in package.json, this should be relatively straightforward. By providing
-all the presets used to Neutrino, you can ensure all the linting options used across all those preset will be merged
-together for your development environment, without the need for copying, duplication, or loss of organization and
-separation.
-
-_Example: Create a .eslintrc.js file in the root of the project._
-
-```js
-// .eslintrc.js
-const Neutrino = require('neutrino');
-const pkg = require('./package.json');
-const api = new Neutrino(pkg.config.presets);
-
-module.exports = api.custom.eslintrc();
-```
-
----
-
-## Contributing
-
-This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
-containing all resources for developing Neutrino and its core presets. Follow the
-[contributing guide](/contributing/README.md) for details.
-
-[npm-image]: https://img.shields.io/npm/v/neutrino-lint-base.svg
-[npm-downloads]: https://img.shields.io/npm/dt/neutrino-lint-base.svg
-[npm-url]: https://npmjs.org/package/neutrino-lint-base
-[slack-image]: https://neutrino-slack.herokuapp.com/badge.svg
-[slack-url]: https://neutrino-slack.herokuapp.com/

docs/presets/neutrino-preset-airbnb-base/README.md

@@ -15,7 +15,7 @@ config, following the [Airbnb styleguide](https://github.com/airbnb/javascript).
 
 - Node.js v6.9+
 - Yarn or npm client
-- Neutrino v4, Neutrino build preset
+- Neutrino v5, Neutrino build preset
 
 ## Installation
 
@@ -37,7 +37,7 @@ another Neutrino preset for building your application source code.
 
 ## Project Layout
 
-`neutrino-preset-airbnb-base` follows the standard [project layout](/project-layout.md) specified by Neutrino. This
+`neutrino-preset-airbnb-base` follows the standard [project layout](../../project-layout.md) specified by Neutrino. This
 means that by default all project source code should live in a directory named `src` in the root of the
 project.
 
@@ -55,6 +55,19 @@ linting **before** your build preset. For example, if you are building your proj
 }
 ```
 
+Or if you have set up Neutrino with `neutrino.presets` in your package.json:
+
+```json
+{
+  "neutrino": {
+    "presets": [
+      "neutrino-preset-airbnb-base",
+      "neutrino-preset-web"
+    ]
+  }
+}
+```
+
 Start the app, then check your console for any linting errors. If everything is successful, you should see no errors in
 the console. ESLint errors visible during development are reported, but will still continue to build and serve your
 project.
@@ -117,19 +130,12 @@ Build completed in 1.287s
 
 ✖ 4 problems (3 errors, 1 warning)
 
- @ multi ./src/index.js
-./src/index.js
-Module build failed: Error: Module failed because of a eslint error.
-
-    at lint (/Users/eli/code/neutrino-dev/packages/neutrino-preset-airbnb-base/node_modules/eslint-loader/index.js:115:17)
-    at Object.module.exports (/Users/eli/code/neutrino-dev/packages/neutrino-preset-airbnb-base/node_modules/eslint-loader/index.js:181:3)
- @ multi ./src/index.js
 error Command failed with exit code 1.
 ```
 
 ## Customizing
 
-To override the build configuration, start with the documentation on [customization](/customization/README.md).
+To override the build configuration, start with the documentation on [customization](../../customization/README.md).
 `neutrino-preset-airbnb-base` creates some conventions to make overriding the configuration easier once you are ready to
 make changes.
 
@@ -137,24 +143,25 @@ make changes.
 
 The following is a list of rules and their identifiers which can be overridden:
 
-- `lint`: Lints JS and JSX files from the `src` directory using ESLint. Contains a single loader named `eslint`.
+- `lint`: Lints JS and JSX files from the `src` directory using ESLint. Contains a single loader named `eslint`. This is
+inherited from `neutrino-middleware-eslint`.
 
 ### Simple customization
 
-By following the [customization guide](/customization/simple.md) and knowing the rule and loader IDs above,
+By following the [customization guide](../../customization/simple.md) and knowing the rule and loader IDs above,
 you can override and augment the linting configuration directly from package.json. _Note: Using the simple customization
-approach for linting changes can be verbose._
+approach for linting changes can be quite verbose. Consider using advanced configuration below if this bothers you._
 
 _Example: Turn off semicolons from being required as defined by the Airbnb rules._
 
 ```json
 {
-  "config": {
   "neutrino": {
+    "config": {
       "module": {
         "rule": {
           "lint": {
-            "loader": {
+            "use": {
               "eslint": {
                 "options": {
                   "rules": {
@@ -176,23 +183,38 @@ project.
 
 ### Advanced configuration
 
-By following the [customization guide](/customization/advanced.md) and knowing the rule and loader IDs above,
+By following the [customization guide](../../customization/advanced.md) and knowing the rule and loader IDs above,
-you can override and augment the build by creating a JS module which overrides the config.
+you can override and augment the build by creating a JS module which overrides the config. This preset is also
+Neutrino middleware, making it easy to compose and extend the configuration.
 
 _Example: Turn off semicolons from being required as defined by the Airbnb rules._
 
 ```js
+// If using as middleware, remove from presets and .use it from your override:
+const airbnb = require('neutrino-preset-airbnb-base');
+
+module.exports = neutrino => {
+  neutrino.use(airbnb, {
+    rules: {
+      semi: 'off'
+    }
+  });
+};
+```
+
+```js
+// If using as a preset from the CLI or configured in package.json,
+// override its configuration directly:
 const merge = require('deepmerge');
 
 module.exports = neutrino => {
   neutrino.config.module
     .rule('lint')
-    .loader('eslint', props => merge(props, {
+      .use('eslint')
-      options: {
+        .tap(options => merge(options, {
           rules: {
             semi: 'off'
           }
-      }
         }));
 };
 ```
@@ -201,11 +223,11 @@ module.exports = neutrino => {
 
 `neutrino-lint-airbnb-base` also provides a method for getting the ESLint configuration suitable for use in an eslintrc
 file. Typically this is used for providing hints or fix solutions to the development environment, e.g. IDEs and text
-editors. Doing this requires [creating an instance of the Neutrino API](/api/README.md) and providing the presets uses.
+editors. Doing this requires [creating an instance of the Neutrino API](../../api/README.md) and providing the presets uses.
-If you keep this information in `config.presets` in package.json, this should be relatively straightforward. By
+If you keep this information in `neutrino.presets` in package.json, this should be relatively straightforward. By
 providing all the presets used to Neutrino, you can ensure all the linting options used across all those preset will be
 merged together for your development environment, without the need for copying, duplication, or loss of organization and
-separation.
+separation. This is inherited from `neutrino-middleware-eslint`.
 
 _Example: Create a .eslintrc.js file in the root of the project._
 
@@ -213,16 +235,23 @@ _Example: Create a .eslintrc.js file in the root of the project._
 // .eslintrc.js
 const Neutrino = require('neutrino');
 const pkg = require('./package.json');
-const api = new Neutrino(pkg.config.presets);
+const api = new Neutrino();
+
+// If the Airbnb preset is not included in pkg.neutrino.presets,
+// use it manually:
+api.use(require('neutrino-preset-airbnb-base'));
+
+// Add the rest of the presets:
+pkg.neutrino.presets.map(preset => api.use(preset));
 
-module.exports = api.custom.eslintrc();
+module.exports = api.eslintrc();
 ```
 
 ## Contributing
 
 This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
 containing all resources for developing Neutrino and its core presets. Follow the
-[contributing guide](/contributing/README.md) for details.
+[contributing guide](../../contributing/README.md) for details.
 
 [npm-image]: https://img.shields.io/npm/v/neutrino-preset-airbnb-base.svg
 [npm-downloads]: https://img.shields.io/npm/dt/neutrino-preset-airbnb-base.svg

docs/presets/neutrino-preset-jest/README.md

@@ -15,7 +15,7 @@
 
 - Node.js v6.9+
 - Yarn or npm client
-- Neutrino v4, Neutrino build preset
+- Neutrino v5, Neutrino build preset
 
 ## Installation
 
@@ -58,7 +58,7 @@ testing with this approach.
 
 ## Project Layout
 
-`neutrino-preset-jest` follows the standard [project layout](/project-layout.md) specified by Neutrino. This
+`neutrino-preset-jest` follows the standard [project layout](../../project-layout.md) specified by Neutrino. This
 means that by default all project test code should live in a directory named `test` in the root of the
 project. Test files end in either `_test.js`, `.test.js`, `_test.jsx`, or `.test.jsx`.
 
@@ -92,6 +92,19 @@ let's pretend this is a Node.js project:
 }
 ```
 
+Or if you have set up Neutrino with `neutrino.presets` in your package.json:
+
+```json
+{
+  "neutrino": {
+    "presets": [
+      "neutrino-preset-node",
+      "neutrino-preset-jest"
+    ]
+  }
+}
+```
+
 Run the tests, and view the results in your console:
 
 #### Yarn
@@ -137,8 +150,7 @@ For more details on specific Jest usage, please refer to their [documentation](h
 ## Executing single tests
 
 By default this preset will execute every test file located in your test directory ending in the appropriate file
-extension.
+extension. Use the command line [`files` parameters](../../cli/README.md#neutrino-test) to execute individual tests.
-Use the command line [`files` parameters](/cli/README.md#neutrino-test) to execute individual tests.
 
 ## Watching for changes
 
@@ -148,14 +160,14 @@ Use the command line [`files` parameters](/cli/README.md#neutrino-test) to execu
 ## Coverage reporting
 
 Jest has an integrated coverage reporter, which requires no configuration. To collect test coverage information and
-generate report run:
+generate a report:
 
 ```bash
 ❯ neutrino test --coverage
 ```
 
-You can also edit your package.json file and create a separate command for generating coverage report, which can be
+You can also edit your package.json file and create a separate command for generating a coverage report, which can be
-very helpful during continues integration of your project:
+very helpful during continuous integration of your project:
 
 ```json
 {
@@ -165,12 +177,12 @@ very helpful during continues integration of your project:
 }
 ```
 
-See the [Jest's documentation](https://facebook.github.io/jest/docs/configuration.html#collectcoveragefrom-array) for
+See the [Jests documentation](https://facebook.github.io/jest/docs/configuration.html#collectcoveragefrom-array) for
 more configuration options for generating coverage reports.
 
 ## Customizing
 
-To override the test configuration, start with the documentation on [customization](/customization/README.md).
+To override the test configuration, start with the documentation on [customization](../../customization/README.md).
 `neutrino-preset-jest` creates some conventions to make overriding the configuration easier once you are ready to make
 changes.
 
@@ -183,38 +195,42 @@ Contains a single loader named `babel`.
 
 ### Simple customization
 
-By following the [customization guide](/customization/simple.md) and knowing the rule, and loader IDs above,
+By following the [customization guide](../../customization/simple.md) and knowing the rule, and loader IDs above,
 you can override and augment the build directly from package.json.
 
 Jest configuration settings can also be modified directly from package.json, but it is not required.
-`neutrino-preset-jest` will import Jest configuration from your package.json's `jest` object; the format is
+`neutrino-preset-jest` will import Jest configuration from your package.json's `jest` object or `neutrino.options.jest`;
-defined on the [Jest documentation site](https://facebook.github.io/jest/docs/configuration.html).
+the format is defined on the [Jest documentation site](https://facebook.github.io/jest/docs/configuration.html).
 
 _Example: Turn off bailing on test failures._
 
 ```json
 {
+  "neutrino": {
+    "options": {
       "jest": {
         "bail": false
       }
     }
+  }
+}
 ```
 
 ### Advanced configuration
 
-By following the [customization guide](/customization/advanced.md) and knowing the rule, and loader IDs above,
+By following the [customization guide](../../customization/advanced.md) and knowing the rule, and loader IDs above,
 you can override and augment testing by creating a JS module which overrides the config. 
 
 You can also modify Jest settings by overriding with any options Jest accepts. In a standalone Jest project this is
 typically done in the package.json file, but `neutrino-preset-jest` allows advanced configuration through this
-mechanism as well. This is stored in the `neutrino.custom.jest` object, and takes the same configuration options as
+mechanism as well. This is stored in the `neutrino.options.jest` object, and takes the same configuration options as
 outlined in the [Jest documentation](https://facebook.github.io/jest/docs/configuration.html).
 
 _Example: Create a global `__DEV__` variable set to `true` in all test environments._
 
 ```js
 module.exports = neutrino => {
-  neutrino.custom.jest.globals = {
+  neutrino.options.jest.globals = {
     __DEV__: true
   };
 };
@@ -224,7 +240,7 @@ module.exports = neutrino => {
 
 This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
 containing all resources for developing Neutrino and its core presets. Follow the
-[contributing guide](/contributing/README.md) for details.
+[contributing guide](../../contributing/README.md) for details.
 
 [npm-image]: https://img.shields.io/npm/v/neutrino-preset-jest.svg
 [npm-downloads]: https://img.shields.io/npm/dt/neutrino-preset-jest.svg

docs/presets/neutrino-preset-karma/README.md

@@ -15,7 +15,7 @@
 
 - Node.js v6.9+
 - Yarn or npm client
-- Neutrino v4, Neutrino build preset
+- Neutrino v5, Neutrino build preset
 
 ## Installation
 
@@ -37,7 +37,7 @@ another Neutrino preset for building your application source code.
 
 ## Project Layout
 
-`neutrino-preset-karma` follows the standard [project layout](/project-layout.md) specified by Neutrino. This
+`neutrino-preset-karma` follows the standard [project layout](../../project-layout.md) specified by Neutrino. This
 means that by default all project test code should live in a directory named `test` in the root of the
 project. Test files end in `_test.js` by default.
 
@@ -73,6 +73,19 @@ let's pretend this is a React project:
 }
 ```
 
+Or if you have set up Neutrino with `neutrino.presets` in your package.json:
+
+```json
+{
+  "neutrino": {
+    "presets": [
+      "neutrino-preset-react",
+      "neutrino-preset-karma"
+    ]
+  }
+}
+```
+
 Run the tests, and view the results in your console:
 
 #### Yarn
@@ -126,8 +139,7 @@ For more details on specific Karma usage, please refer to their
 ## Executing single tests
 
 By default this preset will execute every test file located in your test directory ending in the appropriate file
-extension.
+extension. Use the command line [`files` parameters](/cli/README.md#neutrino-test) to execute individual tests.
-Use the command line [`files` parameters](/cli/README.md#neutrino-test) to execute individual tests.
 
 ## Watching for changes
 
@@ -151,23 +163,39 @@ before_install:
 
 ## Customizing
 
-To override the test configuration, start with the documentation on [customization](/customization/README.md).
+To override the test configuration, start with the documentation on [customization](../../customization/README.md).
 `neutrino-preset-karma` creates some conventions to make overriding the configuration easier once you are ready to make
 changes.
 
 ### Simple customization
 
-It is not currently possible to override `neutrino-preset-karma` settings from the package.json using simple
+By following the [customization guide](../../customization/simple.md) you can override and augment the test configuration
-customization. Please use the advanced configuration for changes.
+directly from package.json. `neutrino-preset-karma` will import Karma configuration from your package.json's
+`neutrino.options.karma` object if defined. The format is defined on the
+[Karma documentation site](http://karma-runner.github.io/1.0/config/configuration-file.html).
+
+_Example: Change the duration Karma waits for a browser to reconnect (in ms)._
+
+```js
+{
+  "neutrino": {
+    "options": {
+      "karma": {
+        "browserDisconnectTimeout": 5000
+      }
+    }
+  }
+}
+```
 
 ### Advanced configuration
 
-By following the [customization guide](/customization/advanced.md) you can override and augment testing by creating a
+By following the [customization guide](../../customization/advanced.md) you can override and augment testing by creating a
 JS module which overrides the config. 
 
 You can also modify Karma settings by overriding with any options Karma accepts. In a standalone Karma project this is
 typically done in a `karma.conf.js` file, but `neutrino-preset-karma` unifies advanced configuration through a preset
-override module. When needing to make changes to Karma-specific settings, this is stored in the `neutrino.custom.karma`
+override module. When needing to make changes to Karma-specific settings, this is stored in the `neutrino.options.karma`
 object, and takes the same configuration options as outlined in the
 [Karma documentation](https://karma-runner.github.io/1.0/config/configuration-file.html).
 
@@ -175,7 +203,7 @@ _Example: Change the duration Karma waits for a browser to reconnect (in ms)._
 
 ```js
 module.exports = neutrino => {
-  neutrino.custom.karma.browserDisconnectTimeout = 5000;
+  neutrino.options.karma.browserDisconnectTimeout = 5000;
 };
 ```
 
@@ -183,7 +211,7 @@ module.exports = neutrino => {
 
 This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
 containing all resources for developing Neutrino and its core presets. Follow the
-[contributing guide](/contributing/README.md) for details.
+[contributing guide](../../contributing/README.md) for details.
 
 [npm-image]: https://img.shields.io/npm/v/neutrino-preset-karma.svg
 [npm-downloads]: https://img.shields.io/npm/dt/neutrino-preset-karma.svg

docs/presets/neutrino-preset-mocha/README.md

@@ -13,7 +13,7 @@
 
 - Node.js v6.9+
 - Yarn or npm client
-- Neutrino v4, Neutrino build preset
+- Neutrino v5, Neutrino build preset
 
 ## Installation
 
@@ -35,7 +35,7 @@ another Neutrino preset for building your application source code.
 
 ## Project Layout
 
-`neutrino-preset-mocha` follows the standard [project layout](/project-layout.md) specified by Neutrino. This
+`neutrino-preset-mocha` follows the standard [project layout](../../project-layout.md) specified by Neutrino. This
 means that by default all project test code should live in a directory named `test` in the root of the
 project. Test files end in `_test.js` by default.
 
@@ -71,6 +71,19 @@ let's pretend this is a Node.js project:
 }
 ```
 
+Or if you have set up Neutrino with `neutrino.presets` in your package.json:
+
+```json
+{
+  "neutrino": {
+    "presets": [
+      "neutrino-preset-node",
+      "neutrino-preset-mocha"
+    ]
+  }
+}
+```
+
 Run the tests, and view the results in your console:
 
 #### Yarn
@@ -110,11 +123,11 @@ For more details on specific Mocha usage, please refer to their [documentation](
 ## Executing single tests
 
 By default this preset will execute every test file located in your test directory ending in `_test.js`.
-Use the command line [`files` parameters](/cli/README.md#neutrino-test) to execute individual tests.
+Use the command line [`files` parameters](../../cli/README.md#neutrino-test) to execute individual tests.
 
 ## Customizing
 
-To override the test configuration, start with the documentation on [customization](/customization/README.md).
+To override the test configuration, start with the documentation on [customization](../../customization/README.md).
 `neutrino-preset-mocha` creates some conventions to make overriding the configuration easier once you are ready to make
 changes.
 
@@ -122,16 +135,47 @@ changes.
 
 The following is a list of rules and their identifiers which can be overridden:
 
-- `compile`: Compiles JS files from the `test` directory using Babel. Contains a single loader named `babel`.
+- `compile`: Compiles JS files from the `test` directory using Babel. Contains a single loader named `babel`. Adopts
+Babel configuration from other presets that have been loaded.
 
 ### Simple customization
 
-By following the [customization guide](/customization/simple.md) and knowing the rule, loader, and plugin IDs above,
+By following the [customization guide](../../customization/simple.md) you can override and augment the test configuration
-you can override and augment the build directly from package.json.
+directly from package.json. `neutrino-preset-mocha` will import Mocha configuration from your package.json's
+`neutrino.options.mocha` object if defined. The format is defined on the
+[Mocha documentation site](https://mochajs.org/#usage), with command-line flags mapping to camel-cased options
+in `neutrino.options.mocha`.
+
+_Example: Switch the test reporter from the default `spec` to `nyan`:_
+
+```js
+{
+  "neutrino": {
+    "options": {
+      "mocha": {
+        "reporter": "nyan"
+      }
+    }
+  }
+}
+```
+
+```bash
+❯ yarn test
+
+ 1   -__,------,
+ 0   -__|  /\_/\
+ 0   -_~|_( ^ .^)
+     -_ ""  ""
+
+  1 passing (362ms)
+
+✨  Done in 3.28s.
+```
 
 ### Advanced configuration
 
-By following the [customization guide](/customization/advanced.md) and knowing the rule, and loader IDs above,
+By following the [customization guide](../../customization/advanced.md) and knowing the rule, and loader IDs above,
 you can override and augment testing by creating a JS module which overrides the config.
 
 You can modify Mocha settings by overriding the preset with any options Mocha accepts. This is stored in the
@@ -141,7 +185,7 @@ _Example: Switch the test reporter from the default `spec` to `nyan`:_
 
 ```js
 module.exports = neutrino => {
-  neutrino.custom.mocha.reporter = 'nyan';
+  neutrino.options.mocha.reporter = 'nyan';
 };
 ```
 
@@ -162,7 +206,7 @@ module.exports = neutrino => {
 
 This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
 containing all resources for developing Neutrino and its core presets. Follow the
-[contributing guide](/contributing/README.md) for details.
+[contributing guide](../../contributing/README.md) for details.
 
 [npm-image]: https://img.shields.io/npm/v/neutrino-preset-mocha.svg
 [npm-downloads]: https://img.shields.io/npm/dt/neutrino-preset-mocha.svg

docs/presets/neutrino-preset-node/README.md

@@ -6,9 +6,10 @@
 ## Features
 
 - Zero upfront configuration necessary to start developing and building a Node.js project
-- Modern Babel compilation supporting ES modules, Node.js 6.9+, and async functions
+- Modern Babel compilation supporting ES modules, Node.js 6.9+, async functions, and dynamic imports
-- Auto-wired sourcemaps
+- Supports automatically-wired sourcemaps
 - Tree-shaking to create smaller bundles
+- Hot Module Replacement with source-watching during development
 - Chunking of external dependencies apart from application code
 - Easily extensible to customize your project as needed
 
@@ -16,7 +17,7 @@
 
 - Node.js v6.9+
 - Yarn or npm client
-- Neutrino v4
+- Neutrino v5
 
 ## Installation
 
@@ -51,7 +52,7 @@ If you want to have automatically wired sourcemaps added to your project, add `s
 
 ## Project Layout
 
-`neutrino-preset-node` follows the standard [project layout](/project-layout.md) specified by Neutrino. This
+`neutrino-preset-node` follows the standard [project layout](../../project-layout.md) specified by Neutrino. This
 means that by default all project source code should live in a directory named `src` in the root of the
 project. This includes JavaScript files that would be available to your compiled project.
 
@@ -82,14 +83,10 @@ createServer(async (req, res) => {
 
 Now edit your project's package.json to add commands for starting and building the application.
 
-**Important Note:** At the time of writing, Neutrino's Node preset does not support `watch`
-compilation with `neutrino start`; it will instead fall back to running a build with the `NODE_ENV`
-environment variable set to `development`.
-
 ```json
 {
   "scripts": {
-    "start": "neutrino start --presets neutrino-preset-node && node build/index.js",
+    "start": "neutrino start --presets neutrino-preset-node",
     "build": "neutrino build --presets neutrino-preset-node"
   }
 }
@@ -101,13 +98,6 @@ Start the app, then either open a browser to http://localhost:3000 or use curl f
 
 ```bash
 ❯ yarn start
-Warning: This preset does not support watch compilation. Falling back to a one-time build.
-Hash: 89e4fb250fc535920ba4
-Version: webpack 2.2.1
-Time: 432ms
-       Asset     Size  Chunks             Chunk Names
-    index.js  4.29 kB       0  [emitted]  index
-index.js.map  3.73 kB       0  [emitted]  index
 Server running on port 3000
 ```
 
@@ -120,13 +110,6 @@ hi!
 
 ```bash
 ❯ npm start
-Warning: This preset does not support watch compilation. Falling back to a one-time build.
-Hash: 89e4fb250fc535920ba4
-Version: webpack 2.2.1
-Time: 432ms
-       Asset     Size  Chunks             Chunk Names
-    index.js  4.29 kB       0  [emitted]  index
-index.js.map  3.73 kB       0  [emitted]  index
 Server running on port 3000
 ```
 
@@ -168,9 +151,52 @@ or via `.npmignore` to blacklist `src`.
 }
 ```
 
+_Note: While this preset works well for many types of Node.js applications, it's important to make the distinction
+between applications and libraries. This preset will not work optimally out of the box for creating distributable
+libraries, and will take a little extra customization to make them suitable for that purpose._
+
+## Hot Module Replacement
+
+While `neutrino-preset-node` supports Hot Module Replacement for your app, it does require some application-specific
+changes in order to operate. Your application should define split points for which to accept modules to reload using
+`module.hot`:
+
+For example:
+
+```js
+import { createServer } from 'http';
+import app from './app';
+
+if (module.hot) {
+  module.hot.accept('./app');
+}
+
+createServer((req, res) => {
+  res.end(app('example'));  
+}).listen(/* */);
+```
+
+Or for all paths:
+
+```js
+import { createServer } from 'http';
+import app from './app';
+
+if (module.hot) {
+  module.hot.accept();
+}
+
+createServer((req, res) => {
+  res.end(app('example'));  
+}).listen(/* */);
+```
+
+Using dynamic imports with `import()` will automatically create split points and hot replace those modules upon
+modification during development.
+
 ## Customizing
 
-To override the build configuration, start with the documentation on [customization](/customization/README.md).
+To override the build configuration, start with the documentation on [customization](../../customization/README.md).
 `neutrino-preset-node` creates some conventions to make overriding the configuration easier once you are ready to make
 changes.
 
@@ -202,15 +228,15 @@ The following is a list of plugins and their identifiers which can be overridden
 
 ### Simple customization
 
-By following the [customization guide](/customization/simple.md) and knowing the rule, loader, and plugin IDs above,
+By following the [customization guide](../../customization/simple.md) and knowing the rule, loader, and plugin IDs above,
 you can override and augment the build directly from package.json.
 
 _Example: Allow importing modules with an `.mjs` extension._
 
 ```json
 {
-  "config": {
   "neutrino": {
+    "config": {
       "resolve": {
         "extensions": [
           ".mjs"
@@ -223,7 +249,7 @@ _Example: Allow importing modules with an `.mjs` extension._
 
 ### Advanced configuration
 
-By following the [customization guide](/customization/advanced.md) and knowing the rule, loader, and plugin IDs above,
+By following the [customization guide](../../customization/advanced.md) and knowing the rule, loader, and plugin IDs above,
 you can override and augment the build by creating a JS module which overrides the config.
 
 _Example: Allow importing modules with an `.mjs` extension._
@@ -238,7 +264,7 @@ module.exports = neutrino => {
 
 This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
 containing all resources for developing Neutrino and its core presets. Follow the
-[contributing guide](/contributing/README.md) for details.
+[contributing guide](../../contributing/README.md) for details.
 
 [npm-image]: https://img.shields.io/npm/v/neutrino-preset-node.svg
 [npm-downloads]: https://img.shields.io/npm/dt/neutrino-preset-node.svg

docs/presets/neutrino-preset-react/README.md

@@ -9,8 +9,8 @@
 - Modern Babel compilation adding JSX and object rest spread syntax.
 - Support for React Hot Loader
 - Write JSX in .js or .jsx files
-- Extends from [neutrino-preset-web](/presets/neutrino-preset-web/README.md)
+- Extends from [neutrino-preset-web](../neutrino-preset-web/README.md)
-  - Modern Babel compilation supporting ES modules, last 2 major browser versions, and async functions
+  - Modern Babel compilation supporting ES modules, last 2 major browser versions, async functions, and dynamic imports
   - Webpack loaders for importing HTML, CSS, images, icons, and fonts
   - Webpack Dev Server during development
   - Automatic creation of HTML pages, no templating necessary
@@ -22,7 +22,7 @@
 
 - Node.js v6.9+
 - Yarn or npm client
-- Neutrino v4
+- Neutrino v5
 
 ## Installation
 
@@ -46,7 +46,7 @@ React development.
 
 ## Project Layout
 
-`neutrino-preset-react` follows the standard [project layout](/project-layout.md) specified by Neutrino. This
+`neutrino-preset-react` follows the standard [project layout](../../project-layout.md) specified by Neutrino. This
 means that by default all project source code should live in a directory named `src` in the root of the
 project. This includes JavaScript files, CSS stylesheets, images, and any other assets that would be available
 to your compiled project.
@@ -123,14 +123,14 @@ You can either serve or deploy the contents of this `build` directory as a stati
 
 ## Customizing
 
-To override the build configuration, start with the documentation on [customization](/customization/README.md).
+To override the build configuration, start with the documentation on [customization](../../customization/README.md).
 `neutrino-preset-react` does not use any additional named rules, loaders, or plugins that aren't already in use by the
-Web preset. See the [Web documentation customization](/presets/neutrino-preset-web#customizing)
+Web preset. See the [Web documentation customization](../neutrino-preset-web#customizing)
 for preset-specific configuration to override.
 
 ### Simple customization
 
-By following the [customization guide](/customization/simple.md) and knowing the rule, loader, and plugin IDs above,
+By following the [customization guide](../../customization/simple.md) and knowing the rule, loader, and plugin IDs above,
 you can override and augment the build directly from package.json.
 
 #### Vendoring
@@ -143,8 +143,8 @@ _Example: Put React and React DOM into a separate "vendor" chunk:_
 
 ```json
 {
-  "config": {
   "neutrino": {
+    "config": {
       "entry": {
         "vendor": [
           "react",
@@ -181,23 +181,25 @@ manifest.29ee4d0db8f2534cc643.bundle.js    1.44 kB       2  [emitted]  manifest
 #### HTML files
 
 If you wish to override how HTML files are created for your React app, refer to the [relevant section on
-neutrino-preset-web](/presets/neutrino-preset-web/README.md#html-files).
+neutrino-preset-web](../neutrino-preset-web/README.md#html-files).
 
 _Example: Change the application mount ID from "root" to "app":_
 
 ```json
 {
-  "config": {
+  "neutrino": {
+    "options": {
       "html": {
         "appMountId": "app"
       }
     }
   }
+}
 ```
 
 ### Advanced configuration
 
-By following the [customization guide](/customization/advanced.md) and knowing the rule, loader, and plugin IDs from
+By following the [customization guide](../../customization/advanced.md) and knowing the rule, loader, and plugin IDs from
 neutrino-preset-web, you can override and augment the build by creating a JS module which overrides the config.
 
 #### Vendoring
@@ -216,9 +218,9 @@ module.exports = neutrino => {
 };
 ```
 
-## Hot Reloading
+## Hot Module Replacement
 
-While `neutrino-preset-react` supports hot reloading your app using React Hot Loader, it does require some
+While `neutrino-preset-react` supports Hot Module Replacement your app using React Hot Loader, it does require some
 application-specific changes in order to operate.
 
 First, install `react-hot-loader` as a dependency, this **must** be React Hot Loader v3+ (currently in beta):
@@ -237,7 +239,8 @@ First, install `react-hot-loader` as a dependency, this **must** be React Hot Lo
 
 ---
 
-- From your `index` entry point (`src/index.js`), import an `AppContainer` from `react-hot-loader`.
+- From your `index` entry point (defaults to `src/index.js` from `neutrino.options.entry`), import an `AppContainer`
+from `react-hot-loader`.
 - Wrap your top-level React component in the `AppContainer`.
 - Perform the application render in a reusable function for initial load and subsequent reloads.
 - Add the `hot` acceptance to call this function.
@@ -267,7 +270,7 @@ load();
 
 This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
 containing all resources for developing Neutrino and its core presets. Follow the
-[contributing guide](/contributing/README.md) for details.
+[contributing guide](../../contributing/README.md) for details.
 
 [npm-image]: https://img.shields.io/npm/v/neutrino-preset-react.svg
 [npm-downloads]: https://img.shields.io/npm/dt/neutrino-preset-react.svg

docs/presets/neutrino-preset-web/README.md

@@ -6,7 +6,7 @@
 ## Features
 
 - Zero upfront configuration necessary to start developing and building a web app
-- Modern Babel compilation supporting ES modules, last 2 major browser versions, and async functions
+- Modern Babel compilation supporting ES modules, last 2 major browser versions, async functions, and dynamic imports
 - Webpack loaders for importing HTML, CSS, images, icons, and fonts
 - Webpack Dev Server during development
 - Automatic creation of HTML pages, no templating necessary
@@ -40,7 +40,7 @@
 
 ## Project Layout
 
-`neutrino-preset-web` follows the standard [project layout](/project-layout.md) specified by Neutrino. This
+`neutrino-preset-web` follows the standard [project layout](../../project-layout.md) specified by Neutrino. This
 means that by default all project source code should live in a directory named `src` in the root of the
 project. This includes JavaScript files, CSS stylesheets, images, and any other assets that would be available
 to your compiled project.
@@ -116,15 +116,53 @@ manifest.c10c6464802bf71a2c3f.bundle.js    1.41 kB       1  [emitted]  manifest
 
 You can either serve or deploy the contents of this `build` directory as a static site.
 
+## Hot Module Replacement
+
+While `neutrino-preset-web` supports Hot Module Replacement your app, it does require some application-specific changes
+in order to operate. Your application should define split points for which to accept modules to reload using
+`module.hot`:
+
+For example:
+
+```js
+import app from './app';
+
+document
+  .getElementById('root')
+  .appendChild(app('Hello world!'));
+
+if (module.hot) {
+  module.hot.accept('./app');
+}
+```
+
+Or for all paths:
+
+```js
+import app from './app';
+
+document
+  .getElementById('root')
+  .appendChild(app('Hello world!'));
+
+if (module.hot) {
+  module.hot.accept();
+}
+```
+
+Using dynamic imports with `import()` will automatically create split points and hot replace those modules upon
+modification during development.
+
 ## Customizing
 
-To override the build configuration, start with the documentation on [customization](/customization/README.md).
+To override the build configuration, start with the documentation on [customization](../../customization/README.md).
 `neutrino-preset-web` creates some conventions to make overriding the configuration easier once you are ready to make
 changes.
 
 By default the Web preset creates a single **main** `index` entry point to your application, and this maps to the
-`index.js` file in the `src` directory. This means that the Web preset is optimized toward the use case of single-page
+`index.js` file in the `src` directory. This value is provided by `neutrino.options.entry`.
-applications over multi-page applications.
+This means that the Web preset is optimized toward the use case of single-page applications over multi-page
+applications.
 
 ### Rules
 
@@ -132,7 +170,7 @@ The following is a list of rules and their identifiers which can be overridden:
 
 - `compile`: Compiles JS files from the `src` directory using Babel. Contains a single loader named `babel`.
 - `html`: Allows importing HTML files from modules. Contains a single loader named `file`.
-- `css`: Allows importing CSS stylesheets from modules. Contains two loaders named `style` and `css`.
+- `style`: Allows importing CSS stylesheets from modules. Contains two loaders named `style` and `css`.
 - `img`, `svg`, `ico`: Allows import image files from modules. Each contains a single loader named `url`.
 - `woff`, `ttf`: Allows importing WOFF and TTF font files from modules. Each contains a single loader named `url`.
 - `eot`: Allows importing EOT font files from modules. Contains a single loader named `file`.
@@ -151,7 +189,7 @@ The following is a list of plugins and their identifiers which can be overridden
 
 ### Simple customization
 
-By following the [customization guide](/customization/simple.md) and knowing the rule, loader, and plugin IDs above,
+By following the [customization guide](../../customization/simple.md) and knowing the rule, loader, and plugin IDs above,
 you can override and augment the build directly from package.json.
 
 #### Vendoring
@@ -163,8 +201,8 @@ _Example: Put lodash into a separate "vendor" chunk:_
 
 ```json
 {
-  "config": {
   "neutrino": {
+    "config": {
       "entry": {
         "vendor": [
           "lodash"
@@ -181,24 +219,26 @@ _Example: Put lodash into a separate "vendor" chunk:_
 #### HTML files
 
 Under the hood `neutrino-preset-web` uses [html-webpack-template](https://www.npmjs.com/package/html-webpack-template)
-for generating HTML files. If you wish to override how these files are creating, define an object in your package.json
+for generating HTML files. If you wish to override how these files are created, define an object in your package.json
-at `config.html` with options matching the format expected by html-webpack-template.
+at `neutrino.options.html` with options matching the format expected by html-webpack-template.
 
 _Example: Change the application mount ID from "root" to "app":_
 
 ```json
 {
-  "config": {
+  "neutrino": {
+    "options": {
       "html": {
         "appMountId": "app"
       }
     }
   }
+}
 ```
 
 ### Advanced configuration
 
-By following the [customization guide](/customization/advanced.md) and knowing the rule, loader, and plugin IDs above,
+By following the [customization guide](../../customization/advanced.md) and knowing the rule, loader, and plugin IDs above,
 you can override and augment the build by creating a JS module which overrides the config.
 
 #### Vendoring
@@ -216,11 +256,23 @@ module.exports = neutrino => {
 };
 ```
 
+#### HTML files
+
+_Example: Change the application mount ID from "root" to "app":_
+
+```js
+const merge = require('deepmerge');
+
+module.exports = neutrino => {
+  neutrino.options.html.appMountId = 'app';
+};
+```
+
 ## Contributing
 
 This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
 containing all resources for developing Neutrino and its core presets. Follow the
-[contributing guide](/contributing/README.md) for details.
+[contributing guide](../../contributing/README.md) for details.
 
 [npm-image]: https://img.shields.io/npm/v/neutrino-preset-web.svg
 [npm-downloads]: https://img.shields.io/npm/dt/neutrino-preset-web.svg

docs/project-layout.md

@@ -9,7 +9,7 @@ development process for new projects as quick as possible. This is broken up int
 
 Each of these directories is set up via convention by a Neutrino preset, but each can be customized as
 desired by overriding the preset's configuration or using a different preset. See
-[Custom Configuration](/custom-configuration.md) for detailed instructions.
+[Custom Configuration](./customization/README.md) for detailed instructions.
 
 ## Source Code
 

docs/upgrading-neutrino.md

@@ -0,0 +1,213 @@
+# Upgrading from Neutrino v4 to v5
+
+Neutrino v5 introduces a number of changes, with some of them being breaking changes. To upgrade from Neutrino v4
+to v5, be sure to check this list for tasks you may need to perform to use this latest version:
+
+- Updates to config for creating plugins (from webpack-chain v3 upgrade):
+
+```js
+// Creating plugins in v4
+neutrino.config
+  .plugin(name)
+  .use(WebpackPlugin, ...args)
+  
+// Creating plugins in v5
+neutrino.config
+  .plugin(name)
+  .use(WebpackPlugin, args)
+```
+
+- Updates to config for modifying plugins (from webpack-chain v3 upgrade):
+
+```js
+// Modifying plugins in v4
+neutrino.config
+  .plugin(name)
+  .inject((Plugin, args) => new Plugin(...newArgs))
+  
+// Modifying plugins in v5
+neutrino.config
+  .plugin(name)
+  .tap(args => newArgs);
+```
+
+- Updates to config for creating loaders (from webpack-chain v3 upgrade):
+
+```js
+// Creating loaders in v4
+neutrino.config.module
+  .rule('compile')
+  .loader('babel', 'babel-loader', {
+    options: {
+      plugins: ['object-rest-spread']
+    }
+  });
+  
+// Creating loaders in v5
+neutrino.config
+  .rule('compile')
+  .use('babel')
+    .loader('babel-loader')
+    .options({ plugins: ['object-rest-spread'] });
+```
+
+- Updates to config for modifying loaders (from webpack-chain v3 upgrade). The function now gets its options directly
+instead of being nested in an object:
+
+```js
+// Modifying loaders in v4
+neutrino.config.module
+  .rule('compile')
+  .loader('babel', props => merge(props, {
+    options: {
+      plugins: ['object-rest-spread']
+    }
+  }));
+  
+// Modifying loaders in v5
+neutrino.config.module
+  .rule('compile')
+    .use('babel')
+      .tap(options => merge(options, { plugins: ['object-rest-spread'] }));
+```
+
+- Updates to `include` and `exclude` for rules (from webpack-chain v3). In the previous webpack-chain
+package, `include` and `exclude` were functions where you provided paths as arguments. These are now
+`ChainedMap`s, making them much more extensible should you need to manipulate these values:
+
+```js
+// Adding rule includes and excludes in v4
+neutrino.config.module
+  .rule('compile')
+    .include(x, y)
+    .exclude(x, y);
+
+// Adding rule includes and excludes in v5
+neutrino.config.module
+  .rule('compile')
+    .include
+      .add(x)
+      .add(y)
+      .end()
+    .exclude
+      .add(x)
+      .add(y);
+
+// You can also use .merge() to add multiple paths at once:
+neutrino.config.module
+  .rule('compile')
+    .include.merge([x, y]).end()
+    .exclude.merge([x, y]);
+```
+
+- Simple configuration via package.json now done from top-level `neutrino` object. Rename `config` to `neutrino`, and
+rename `config.neutrino` to `neutrino.config`. Presets also fall under this `neutrino` object. The `custom` object has
+been renamed to `options`.
+
+```json
+{
+  "neutrino": {
+    "config": {
+      "entry": {
+        "vendor": ["react"]
+      }
+    },
+    "presets": [
+      "neutrino-preset-react"
+    ],
+    "options": {
+      "mocha": {
+        "reporter": "nyan"
+      }
+    }
+  }
+}
+```
+
+- The Web preset has renamed its styling rule from `css` to `style`:
+
+```js
+// v4 API for Web preset
+neutrino.config.module.rule('css')
+
+// v5 API for Web preset
+neutrino.config.module.rule('style')
+```
+
+```json
+{
+  "neutrino": {
+    "config": {
+      "module": {
+        "rule": {
+          "style": {}
+        }
+      }
+    }
+  }
+}
+```
+
+- Jest upgraded to v19, which changes the option `testPathDirs` to `roots`. Jest options set using
+package.json can now only be done at `neutrino.options.jest` (no more package.json `jest`);
+- Linting base is deprecated in favor of `neutrino-middleware-eslint`:
+
+```js
+// v4 API
+const lint = require('neutrino-lint-base');
+
+lint(neutrino);
+neutrino.config.module
+  .rule('lint')
+  .loader('eslint', props => merge(props, { rules: { /* */ } }));
+
+// v5 API
+const eslint = require('neutrino-middleware-eslint');
+
+neutrino.use(eslint, {
+  rules: { /* */ }
+})
+```
+
+- When using a linting preset or consuming anything with `neutrino-middleware-eslint`, the `eslintrc()` method has been
+moved from `neutrino.custom.eslintrc` to `neutrino.eslintrc`:
+
+```js
+// v4 API
+neutrino.custom.eslintrc();
+
+// v5 API
+neutrino.eslintrc();
+```
+
+- The Neutrino API no longer accepts preset strings in its constructor. The constructor now accepts an options object to
+be set at `neutrino.options`:
+
+```js
+const Neutrino = require('neutrino');
+const api = new Neutrino({ mocha: { reporter: 'nyan' } });
+
+api.options.mocha.reporter // "nyan"
+```
+
+- Since the Neutrino API no longer accepts preset strings in its constructor, you must now pass presets and middleware
+as code/functions to the `.use()` method. This means the API no longer does preset module resolution. This has been
+moved to the CLI.
+
+```js
+// v4 API
+const Neutrino = require('neutrino');
+const api = new Neutrino(['neutrino-preset-node', 'neutrino-preset-mocha']);
+
+// v5 API
+const Neutrino = require('neutrino');
+const api = new Neutrino();
+
+api.use(require('neutrino-preset-node'));
+api.use(require('neutrino.preset-mocha'));
+```
+
+- `neutrino.getWebpackOptions()` no longer caches the configuration after being called.
+- Using a `node` target no longer skips the watcher for a builder, it now uses the Webpack source watcher. This means
+commands like `neutrino start && node build` is obsolete. `neutrino build && node build` would work to start a Node
+instance for production-built bundles.

docs/usage.md

@@ -6,7 +6,7 @@ scripts defined in your project's `package.json`.
 
 ## Setup
 
-After completing the [installation](/installation.md) of Neutrino and your Neutrino preset, you will
+After completing the [installation](./installation.md) of Neutrino and your Neutrino preset, you will
 want to define some scripts in your project's `package.json` in order to simply build your project.
 In a typical project:
 
@@ -14,8 +14,8 @@ In a typical project:
 - `scripts.build` would be the command you wish to run to create a production bundle
 - `scripts.test` would be the command you wish to run to execute tests
 
-Using these script targets may not be suitable for every project; know that they are just
+Using these script targets may not be suitable for every project. They are only the
-typical recommendations for script target names, you may choose a different name if desired
+typical recommendations for script target names. You may choose any different name if desired
 for your project.
 
 ## Building for development
@@ -23,7 +23,7 @@ for your project.
 Neutrino provides the command `neutrino start` for creating a bundle during development. Using
 `neutrino start` sets the Node.js environment to `development` using the `NODE_ENV` environment variable,
 which is available in your project source code. Depending on the presets you are using, `neutrino start`
-may also spin up a development server with hot module reloading capabilities.
+may also spin up a development server with Hot Module Replacement (HMR) capabilities.
 Check the documentation of your preset for details.
 
 Usage:
@@ -72,8 +72,8 @@ Putting this into your `package.json` will allow you to build your project using
 Neutrino provides the command `neutrino test` for invoking a set of tests included in your project.
 Using `neutrino test` sets the Node.js environment variable to `test` using the `NODE_ENV` environment
 variable, which is available in your project source code. How your source code is built and consumed from tests
-is determined by the preset you are using. Running suites that are built the same as source files are encouraged
+is determined by the presets you are using. Running suites that are built the same as source files is encouraged by
-to use a Neutrino-compatible preset. Neutrino currently provides three core testing presets: Karma, Jest, and Mocha.
+using a Neutrino-compatible preset. Neutrino currently provides three core testing presets: Karma, Jest, and Mocha.
 
 ```bash
 # PRESET_MODULE is the name of the preset to build with, e.g. neutrino-preset-react
@@ -93,7 +93,7 @@ Putting this into your `package.json` will allow you to test your project using
 ```
 
 Using the command `neutrino test` will execute every test file located in your
-[testing directory](/project-layout#Testing). You may also provide to this command the specific test files you wish
+[testing directory](./project-layout#Testing). You may also provide to this command the specific test files you wish
 to run individually. It is important to note that when combined with the `--presets` parameter, you should use two
 dashes after the last preset to denote the end of the presets and the beginning of the test files.
 
@@ -104,13 +104,16 @@ neutrino test --presets PRESET_A PRESET_B -- a_test.js b_test.js
 ## Using multiple presets
 
 All Neutrino commands support the `--presets` command line parameter, but having to specify this for each script target
-can be cumbersome, especially if you have many presets. Fortunately, Neutrino also supports specifying presets using the
+can be cumbersome and verbose, especially if you have many presets. Fortunately, Neutrino also supports specifying
-`config.presets` field in your project's package.json file. By omitting the `--presets` flag and specifying a
+presets using the `neutrino.presets` field in your project's package.json file. By omitting the `--presets` flag and
-`config.presets` array, every call to a Neutrino command will look up which presets are configured in your package.json.
+specifying a `neutrino.presets` array, every call to a Neutrino command will look up which presets are configured in
+your package.json.
+
+This is the recommended approach when using more than one preset.
 
 ```json
 {
-  "config": {
+  "neutrino": {
     "presets": [
       "neutrino-preset-react",
       "neutrino-preset-karma"