Docs: API

docs/api/README.md

@@ -1 +1,176 @@
 # Neutrino API
+
+When using Neutrino via the [CLI](/cli), 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.
+
+## 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:
+
+Using `require`:
+
+```js
+const Neutrino = require('neutrino');
+const api = new Neutrino(['neutrino-preset-react']);
+```
+
+Using ES imports:
+
+```js
+import Neutrino from 'neutrino';
+
+const api = new Neutrino(['neutrino-preset-react']);
+```
+
+## 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.
+
+```js
+process.env.NODE_ENV = 'production';
+
+const api = new Neutrino();
+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.
+
+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.
+
+### `.config`
+
+When constructing a Neutrino instance, a property of `.config` is set to be a new instance of
+[webpack-chain](https://github.com/mozilla-rpweb/webpack-chain). 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.
+
+### `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.
+
+Currently any `args` passed to `start()` have no effect and will be passed through to any event handlers.
+
+The `start` method will return a Promise which resolves after the build is done or development watcher has stopped,
+and all `start` events have finished.
+
+```js
+api
+  .start()
+  .then(() => console.log('Exiting!'));
+```
+
+### `build(args)`
+
+The `build()` method is responsible for creating a bundle typically used for production. Prior to starting this process,
+Neutrino will trigger and wait for `prebuild` events to finish. After it is complete, Neutrino will trigger and wait for
+`build` events to finish.
+
+Currently any `args` passed to `build()` have no effect and will be passed through to any event handlers.
+
+The `build` method will return a Promise which resolves after the build is done and all `build` events have finished, or
+will reject if there was a failure during building.
+
+```js
+api
+  .build()
+  .then(() => console.log('Saved to build/'))
+  .catch(err => console.error(err));
+```
+
+### `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` 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
+`files` to test, as well as a property for `watch`ing and rerunning tests.
+
+The `test` method will return a Promise which resolves after all `test` events have finished, or
+will reject if there was a failure during testing.
+
+```js
+api
+  .test()
+  .then(() => console.log('all passed'))
+  .catch(err => console.error(err));
+
+api
+  .test({
+    files: [/* ... */],
+    watch: true
+  })
+  .then(() => console.log('all passed'));
+```
+
+### `getWebpackOptions()`
+
+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.
+
+```js
+api.getWebpackOptions(); // -> { ... }
+```
+
+### `emitForAll(eventName, payload)`
+
+Trigger a Promise-dependent event. For example, calling `emitForAll('build')` will trigger an event named build, and
+each event handler can return a Promise denoting when it is finished. When all events have finished, this call will
+resolve.
+
+This method returns a Promise which resolves when all event handlers have also resolved.
+
+```js
+api
+  .emitForAll('custom-event')
+  .then(() => console.log('All custom-events have resolved!'));
+```
+
+### `handleErrors(err, stats)`
+
+This method is used primarily internally to create a consistent console output when errors occur in the build. It will
+log the `err` property and any errors from `stats` if applicable, and return `true` or `false` depending on if there
+_were_ errors.
+
+This method returns a Boolean.
+
+```js
+const failed = api.handleErrors(err, stats);
+
+if (failed) {
+  console.log('The build failed!');
+}
+```
+
+### `_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 received a `SIGINT` event to stop.
+
+```js
+api
+  ._devServer()
+  .then(() => console.log('Exiting process...'));
+```