Documentation for customization, more placeholders

docs/README.md

@@ -5,7 +5,12 @@
 
 ---
 
-Neutrino is a companion tool which lets you build web and Node.js applications with shared presets or configurations. It intends to make the process of initializing and building projects much simpler by providing minimal development dependencies. 
+Neutrino is a companion tool which lets you build web and Node.js applications with shared presets or configurations. 
+It intends to make the process of initializing and building projects much simpler by providing minimal development
+dependencies. 
 
-Neutrino uses Webpack to build both web and Node.js projects by providing complete build presets which can be shared across targets and projects. You can use Neutrino base presets to get started building a variety of projects, create your
-own presets by extending the Neutrino core ones to be shared across your own projects or even by the community. Presets can even be manipulated on a project-by-project basis to handle almost any build situation your preset doesn't cover.
+Neutrino uses Webpack to build both web and Node.js projects by providing complete build presets which can be shared
+across targets and projects. You can use Neutrino base presets to get started building a variety of projects, create
+your own presets by extending the Neutrino core ones to be shared across your own projects or even by the community.
+Presets can even be manipulated on a project-by-project basis to handle almost any build situation your preset doesn't
+cover.

docs/SUMMARY.md

@@ -8,6 +8,13 @@
   * [Web Preset](/presets/neutrino-preset-web/README.md)
   * [React Preset](/presets/neutrino-preset-react/README.md)
   * [Node.js Preset](/presets/neutrino-preset-node/README.md)
+  * [Karma Preset](/presets/neutrino-preset-karma/README.md)
+  * [Mocha Preset](/presets/neutrino-preset-mocha/README.md)
+  * [Jest Preset](/presets/neutrino-preset-jest/README.md)
   * [Base Preset](/presets/neutrino-preset-base/README.md)
-  * [Overriding a preset](/presets/overriding-a-preset.md)
-  * [Creating a preset](/presets/creating-a-preset.md)
+* [Customization](/customization/README.md)
+  * [Simple](/customization/simple.md)
+  * [Advanced](/customization/advanced.md)
+* [Creating presets](/presets/creating-presets.md)
+* [API](/api/README.md)
+* [CLI](/cli/README.md)

docs/api/README.md

@@ -0,0 +1 @@
+# Neutrino API

docs/cli/README.md

@@ -0,0 +1 @@
+# Neutrino CLI

docs/creating-presets.md

@@ -0,0 +1,3 @@
+# Creating Neutrino Presets
+
+## Publishing (npm, GitHub)

docs/customization/README.md

@@ -0,0 +1,18 @@
+# Neutrino Customization
+
+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. Neutrino provides two ways you can augment a preset in the
+context of a project without resorting to creating and publishing an entirely independent preset.
+
+### Simple Customization
+
+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 custom data.
+
+### Advanced Customization
+
+You can also create a configuration override directly in your project which can extend the presets you are using.
+
+---
+
+Continue for details on each technique.

docs/customization/advanced.md

@@ -0,0 +1,85 @@
+# Advanced Neutrino Customization
+
+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. If you need more customization than can be afforded by
+augmenting your project's package.json, consider using this advanced configuration guide to modify your build as
+needed.
+
+## Creating a project-specific preset
+
+Neutrino configurations are backed by [webpack-chain](https://github.com/mozilla-rpweb/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
+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
+instance for modifying the build. Let's create a file called `neutrino-custom.js` in the root of our example project:
+
+```js
+// neutrino-custom.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
+to use it for additional configuration. Modify your package.json and add `neutrino-custom.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._
+
+```json
+{
+  "config": {
+    "presets": [
+      "neutrino-preset-react",
+      "neutrino-preset-karma",
+      "neutrino-custom.js"
+    ]  
+  },
+  "scripts": {
+    "build": "neutrino build"
+  }
+}
+```
+
+Other than actually changing the config, that is all the setup necessary for Neutrino to pick up your custom changes.
+
+## Configuring
+
+The Neutrino instance provided to your custom configurator has a `config` property that is an instance of
+[webpack-chain](https://github.com/mozilla-rpweb/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.
+
+This `neutrino.config` is an accumulation of all configuration set up to this moment. Every Neutrino preset interacts
+with and makes changes through this config, which is all available to you. For example, if you are using the presets
+`neutrino-preset-react` and `neutrino-preset-karma`, any options set can be extended, manipulated, or removed.
+
+_Example: Neutrino's React preset adds `.jsx` as a module extension. Let's remove it._
+
+```js
+module.exports = neutrino => {
+  neutrino.config.resolve.extensions.delete('.jsx');
+};
+```
+
+_Example: Neutrino's Node.js preset uses `babel-preset-env` to support Node.js v6.9. Let's change it to support back to
+v4.2. This preset has a rule named "compile" and a loader named "babel"._
+
+```js
+module.exports = neutrino => {
+  neutrino.config.module
+    .rule('compile')
+      .loader('babel', ({ options }) => {
+        options.presets[0][1].targets.node = 4.2;
+
+        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-rpweb/webpack-chain) here,
+please refer to its documentation for all ways you can modify a config instance to solve your use cases.

docs/customization/simple.md

@@ -0,0 +1,238 @@
+# Simple Neutrino Customization
+
+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
+custom data.
+
+## Prepare package.json
+
+First, you will need to define a `config` section within your package.json. 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`:
+
+```json
+{
+  "config": {
+    "presets": [
+      "neutrino-preset-react",
+      "neutrino-preset-karma"
+    ]
+  },
+  "scripts": {
+    "start": "neutrino start",
+    "build": "neutrino build"
+  }
+}
+```
+
+Add a new property to `config` named `neutrino`. This will be an object where we can provide configuration data:
+
+```json
+{
+  "config": {
+    "presets": [],
+    "neutrino": {
+
+    }
+  }
+}
+```
+
+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-rpweb/webpack-chain).
+
+## Usage
+
+### Entries
+
+Add files to named entry points, or define new entry points. This is a key named `entry`, with a value being an object.
+This maps to points to enter the application. At this point the application starts executing.
+
+_Example: Define an entry point named `vendor` that bundles React packages separately from the application code._
+
+```json
+{
+  "config": {
+    "neutrino": {
+      "entry": {
+        "vendor": [
+          "react",
+          "react-dom",
+          "react-hot-loader",
+          "react-router-dom"
+        ]
+      }
+    }
+  }
+}
+```
+
+### Module
+
+The `module` object defines how the different types of modules within a project will be treated. Any additional
+properties attached to `module` not defined below will be set on the final module configuration.
+
+#### Module Rules
+
+Using `module.rule` creates rules that are matched to requests when modules are created. These rules can modify how the
+module is created. They can apply loaders to the module, or modify the parser. 
+
+Using `module.rule.loader` allows to you define the Webpack loader and its options for processing a particular rule.
+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._
+
+```json
+{
+  "dependencies": {
+    "less": "^2.7.2",
+    "less-loader": "^2.2.3"
+  },
+  "config": {
+    "neutrino": {
+      "module": {
+        "rule": {
+          "styles": {
+            "test": "/\\.less$/",
+            "loader": {
+              "less": {
+                "loader": "less-loader",
+                "options": {
+                  "noIeCompat": true
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Output
+
+The `output` object contains a set of options instructing Webpack on how and where it should output your bundles,
+assets, and anything else you bundle or load with Webpack. This option can be any property/value combination that
+[Webpack accepts](https://webpack.js.org/configuration/output/).
+
+_Example: Change the public path of the application._
+
+```json
+{
+  "config": {
+    "neutrino": {
+      "output": {
+        "publicPath": "https://cdn.example.com/assets/"
+      }
+    }
+  }
+}
+```
+
+### Node
+
+Use `node` to customize the Node.js environment using polyfills or mocks:
+
+_Example: mock the `__filename` and `__dirname` Node.js globals._
+
+```json
+{
+  "config": {
+    "neutrino": {
+      "node": {
+        "__filename": "mock",
+        "__dirname": "mock"
+      }
+    }
+  }
+}
+```
+
+### DevServer
+
+Use `devServer` to customize webpack-dev-server and change its behavior in various ways.
+
+_Example: gzip the application when serving and listen on port 9000._
+
+```json
+{
+  "config": {
+    "neutrino": {
+      "devServer": {
+        "compress": true,
+        "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
+properties attached to `resolve` not defined below will be set on the final module configuration.
+
+_Example: Add `.mjs` as a resolving extension and specify modules are located in a `custom_modules` directory._
+
+```json
+{
+  "config": {
+    "neutrino": {
+      "resolve": {
+        "extensions": [".mjs"],
+        "modules": ["custom_modules"]
+      }
+    }
+  }
+}
+```
+
+### ResolveLoader
+
+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
+module configuration.
+
+_Example: Add `.loader.js` as a loader extension and specify modules are located in a `web_loaders` directory._
+
+```json
+{
+  "config": {
+    "neutrino": {
+      "resolve": {
+        "extensions": [".loader.js"],
+        "modules": ["web_loaders"]
+      }
+    }
+  }
+}
+```
+
+### Additional configuration
+
+Any top-level properties you set on `config.neutrino` will be added to the configuration.
+
+_Example: Change the Webpack performance options to error when exceeding performance budgets._
+
+```json
+{
+  "config": {
+    "neutrino": {
+      "performance": {
+        "hints": "error"
+      }
+    }
+  }
+}
+```
+
+## Advanced Configuration
+
+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).