Eli Perelman
8 years ago
1 changed files with 175 additions and 0 deletions
@ -1 +1,176 @@ |
|||||
# Neutrino API |
# 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...')); |
||||
|
``` |
||||
|
Loading…
Reference in new issue