v5 Docs

docs/SUMMARY.md

@@ -5,6 +5,7 @@
 * [Usage](/usage.md)
 * [Project Layout](/project-layout.md)
 * [FAQ](/FAQ.md)
+* [Middleware](/middleware/README.md)
 * [Presets](/presets/README.md)
   * [Web](/presets/neutrino-preset-web/README.md)
   * [React](/presets/neutrino-preset-react/README.md)
@@ -22,6 +23,8 @@
 * [Learning Resources](/learning-resources.md)
 * [API](/api/README.md)
 * [CLI](/cli/README.md)
+* [Upgrading from v4 to v5](/upgrading-neutrino.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,70 +1,128 @@
 # Neutrino API
 
 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
-instance of the Neutrino API and interact with it programmatically.
+any presets and arguments passed on the command line or located in package.json. If you desire, you can also create your
+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:
 
 ```js
 import Neutrino from 'neutrino';
 
-const api = new Neutrino(['neutrino-preset-react']);
+const api = new Neutrino(options);
+```
+
+## 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();
 ```
 
 ## API
 
 ### Constructor
 
-When creating a Neutrino instance, you have the option of providing an array 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.
+When creating a Neutrino instance, you have the option of providing an object which can be passed as options to
+middleware as `neutrino.options`.
 
-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 `config.neutrino`, this data
-will be merged.
+```js
+const Neutrino = require('neutrnino');
+
+const api = new Neutrino();
+
+// or with optional options
+const api = new Neutrino({ jest: { bail: true } });
+```
 
 ### `.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
-subsequently augment it with their specific options. Every preset added uses this single `.config` to store their data,
-meaning that preset load order has an effect on which config values take precedence. Presets loaded later will override
-values set by earlier presets.
+[webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). This property is then available to all presets
+which subsequently augment it with their specific configuration. All middleware and presets added use this single
+`.config` to store their data, meaning that middleware load order has an effect on which config values take precedence.
+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)`
 
 The `start()` method is responsible for creating a development bundle, and when possible, starting a development
 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
-configured for Node.js, then a build will be created, otherwise a Webpack source watcher will be started.
+If the Neutrino config contains options for `devServer`, then a webpack-dev-server will be started, otherwise a Webpack
+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 +156,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
-preset listening for these events, nothing will happen. Prior to starting this process, Neutrino will trigger and wait
-for `pretest` events to finish. After it is complete, Neutrino will trigger and wait for
+test presets that they may run. Using the `test` method does nothing other than triggering these events; without
+middleware listening for these events, nothing will happen. Prior to starting this process, Neutrino will trigger and
+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 +185,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
-result in the config being rendered only once, but the cached value returned afterwards.
+an configuration object readable directly by Webpack.
 
 ```js
 api.getWebpackOptions(); // -> { ... }
@@ -177,13 +234,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
-resolves when the process receives a `SIGINT` event to stop.
+This method is used internally to generate an instance of webpack-dev-server when using `start()`. It returns a promise
+that resolves when the process receives a `SIGINT` event to stop.
 
 ```js
 api
   ._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,9 +24,10 @@ Commands:
   test [files..]  Run all suites from the test directory or provided files
 
 Options:
-  --presets  A list of Neutrino presets used to configure the build    [array] [default: []]
-  --version  Show version number                                       [boolean]
-  --help     Show help                                                 [boolean]
+  --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]
 ```
 
 ## `--version`
@@ -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
@@ -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/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>