Neutrino CLI

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.

--help

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]

--version

Using --version will output the current version of the Neutrino CLI to the console and exit.

❯ neutrino --version
8.0.0

--use

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.

--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 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:

--require

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.

--debug

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.

--quiet

Prevents the CLI from outputting any console output. Neutrino middleware should also respect this flag when possible,
but is not a guarantee.

--options

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

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.

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 by default.

neutrino test

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.

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.

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

Custom commands

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.

Exit codes

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.