Using the command-line interface is the preferred and simplest way of interacting with Neutrino.
When using the Neutrino CLI, you can provide a list of middleware for the API to attempt to load and merge
configurations. Each middleware 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
middleware, Neutrino will attempt to load a .neutrinorc.js
file as middleware from the current working directory if
it exists.
Let's take a look at the CLI usage.
Using neutrino --help
will bring up the following help guide:
❯ neutrino --help
Commands:
start Build a project in development mode
build Compile the source directory to a bundled build
test [files..] Run all suites from the test directory or provided files
Options:
--inspect Output a string representation of the configuration used by webpack and exit [boolean] [default: false]
--use A list of Neutrino middleware used to configure the build [array] [default: []]
--options Set Neutrino options, config, and environment variables, e.g. --options.env.NODE_ENV production [default: {}]
--quiet Disable console output of CLI commands [boolean] [default: false]
--debug Run in debug mode [boolean] [default: false]
--require Preload a module prior to loading Neutrino; can be used multiple times [array] [default: []]
--version Show version number [boolean]
--help Show help [boolean]
Using --version
will output the current version of the Neutrino CLI to the console and exit.
❯ neutrino --version
8.0.0
The --use
flag can be used in conjunction with any of the top-level commands to specify a collection of
middleware and presets to load. These can be an npm package or a relative path to a module to load as middleware.
❯ neutrino start --use @neutrinojs/react @neutrinojs/karma
The Neutrino CLI will not attempt to load any presets and middleware defined in the project's .neutrinorc.js
file
when passing middleware via --use
.
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 have been supplied, but will then exit after logging the configuration to stdout. No builds, servers, or
watchers will be started.
❯ neutrino start --inspect --use @neutrinojs/react @neutrinojs/jest
This could also be used to help create diffs between configuration changes. Take the following command:
❯ neutrino start --inspect --use @neutrinojs/react @neutrinojs/jest
We can capture this inspection to a file, and capture the change by adding a preset override:
❯ neutrino start --inspect --use @neutrinojs/react @neutrinojs/jest > a.config
❯ neutrino start --inspect --use @neutrinojs/react @neutrinojs/jest override.js > b.config
Using git diff --no-index a.config b.config
, we get a pretty diff of the configuration change:
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'
]
},
Require one or more modules prior to invoking any Neutrino commands. These can be an npm package or a relative path to
a module to require. If you export a function, Neutrino will execute this function for you. If you export a Promise, or
if you export a function that returns a Promise, Neutrino will wait for it to resolve before invoking any commands.
Using --require
with multiple Promise-using modules will make Neutrino await all the Promises in parallel prior to
running a command.
The --require
flag can be especially useful if you need to perform work before running Neutrino each time.
❯ neutrino start --require load-env.js
❯ neutrino build --require scripts/load-env scripts/fetch-remote-data
❯ neutrino build --require scripts/load-env --require scripts/fetch-remote-data
Informs interested middleware that they should be in a state of debugging. This does not currently make Neutrino itself behave any differently; rather it can be used to inform middleware to behave differently, by outputting console information, inspecting processes, or changing configuration helpful for debugging.
Prevents the CLI from outputting any console output. Neutrino middleware should also respect this flag when possible, but is not a guarantee.
Used to override Neutrino options, configuration, and environments from the command line. This would typically be used
for specifying one-off changes that may not be appropriate to encapsulate in .neutrinorc.js
. The --options
flag is
formatted as "dotted-object" syntax, meaning it should be used as --options.<option> [value]
. This can also be used
to toggle Boolean options to true
by providing no value. Some examples:
❯ neutrino start --options.host 192.168.1.10 --options.port 3000
❯ neutrino build --options.env.NODE_ENV development --options.env.CUSTOM_ENV_VAR customValue
# Sets options.https to true
❯ neutrino start --options.https
❯ neutrino start --options.config.devtool eval
# Sets config.node.Buffer to true
❯ neutrino start --options.config.node.Buffer
Using the command neutrino start
builds a project in development mode, also starting a development server or source
watcher depending on the middleware or configuration used. This command sets the NODE_ENV
environment variable to
development
by default.
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
by default.
Using the command neutrino test
passes execution onto a test runner preset. It is up to the preset or middleware being
used to determine how source files are built or provided to tests. See your particular test middleware for details. This
command sets the NODE_ENV
environment variable to test
by default.
Looking at the --help
for neutrino test
:
❯ neutrino test --help
neutrino test [files..]
Options:
--inspect Output a string representation of the configuration used by Neutrino and exit [boolean] [default: false]
--use A list of Neutrino middleware used to configure the build [array] [default: []]
--options Set Neutrino options, config, and environment variables, e.g. --options.env.NODE_ENV production [default: {}]
--quiet Disable console output of CLI commands [boolean] [default: false]
--debug Run in debug mode [boolean] [default: false]
--version Show version number [boolean]
--help Show help [boolean]
--coverage Collect test coverage information and generate report [boolean] [default: false]
--watch Watch source files for changes and re-run tests [boolean] [default: false]
Using the command neutrino test
will execute every test file located in your
testing directory. 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 --use
parameter, you should use two
dashes after the last preset to denote the end of the presets and the beginning of the test files.
❯ neutrino test a_test.js b_test.js
❯ neutrino test --use @neutrinojs/react @neutrinojs/karma -- a_test.js b_test.js
You can also pass a flag --watch
to watch source files for changes and re-run tests, if your middleware supports it.
❯ neutrino test --watch
As well, you can pass a flag --coverage
to collect test coverage information and generate a report, if your middleware
supports it.
❯ neutrino test --coverage
Middleware has the ability to register named commands with Neutrino. These registered commands are also available to invoke from the CLI provided the middleware registering the command has been loaded when it is time for the CLI to invoke the command.
// custom.js
module.exports = (neutrino) => {
neutrino.register('hello', () => 'HELLO WORLD!');
};
❯ neutrino hello --use custom.js
HELLO WORLD!
When the CLI creates an instance of Neutrino, it waits for all commands to either resolve or reject their registered
command. If the command succeeded, the CLI will exit with code 0
. If there were errors, the CLI will log the errors
to the console and exit with code 1
. This makes it easier to use Neutrino commands for status reasons, such
as failing a pull request on continuous integration if any tests fail or if there are linter errors.