Usage¶
Neutrino is a command-line tool that wraps webpack in order to support building JavaScript projects
based on shared configuration presets and middleware. You can use Neutrino within your project, preferably using
scripts defined in your project's package.json
.
Setup¶
After completing the installation of Neutrino and your Neutrino preset, you will
want to define some scripts in your project's package.json
in order to more simply build your project.
In a typical project:
scripts.start
would be the command you wish to run during developmentscripts.build
would be the command you wish to run to create a production bundlescripts.test
would be the command you wish to run to execute tests
Using these script targets may not be suitable for every project. They are only the typical recommendations for script target names. You may choose any different name if desired for your project.
Building for development¶
Neutrino provides the command neutrino start
for creating a bundle during development. Using
neutrino start
by default sets the Node.js environment to development
using the NODE_ENV
environment variable,
which is available in your project source code. Depending on the presets you are using, neutrino start
may also spin up a development server with Hot Module Replacement (HMR) capabilities.
Check the documentation of your preset for details.
Usage:
# PRESET_MODULE is the name of the preset to build with, e.g. @neutrinojs/react
neutrino start --use PRESET_MODULE
Putting this into your package.json
will allow you to build your project using either
yarn start
or npm start
. Using @neutrinojs/react
as an example:
{ "scripts": { "start": "neutrino start --use @neutrinojs/react" } }
Building for production¶
Neutrino provides the command neutrino build
for creating a bundle for production deployment.
Using neutrino build
by default sets the Node.js environment to production
using the NODE_ENV
environment variable,
which is available in your project source code. See the documentation for your preset for details regarding additional
steps after your build is completed.
# PRESET_MODULE is the name of the preset to build with, e.g. @neutrinojs/react
neutrino build --use PRESET_MODULE
Putting this into your package.json
will allow you to build your project using either
yarn build
or npm run build
. Using @neutrinojs/react
as an example:
{ "scripts": { "build": "neutrino build --use @neutrinojs/react" } }
Building and running tests¶
Neutrino provides the command neutrino test
for invoking a set of tests included in your project.
Using neutrino test
by default sets the Node.js environment variable to test
using the NODE_ENV
environment
variable, which is available in your project source code. How your source code is built and consumed from tests
is determined by the middleware you are using. Running suites that are built the same as source files is encouraged by
using Neutrino-compatible middleware. Neutrino currently provides three core testing presets: Karma, Jest, and Mocha.
# PRESET_MODULE is the name of the preset to build with, e.g. @neutrinojs/react # TESTING_MODULE is the name of another middleware to build with, e.g. @neutrinojs/karma neutrino test --use PRESET_MODULE TESTING_MODULE
Putting this into your package.json
will allow you to test your project using either
yarn test
or npm test
. Using @neutrinojs/react
and @neutrinojs/karma
as an example:
{ "scripts": { "test": "neutrino test --use @neutrinojs/react @neutrinojs/karma" } }
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 middleware to denote the end of the middleware and the beginning of the test files.
neutrino test --use PRESET_A PRESET_B -- a_test.js b_test.js
Using multiple presets¶
All Neutrino commands support the --use
command line parameter, but having to specify this for each script target
can be cumbersome and verbose, especially if you have many middleware or presets. Fortunately, Neutrino also supports
specifying presets using the use
property in a .neutrinorc.js
file. By omitting the --use
flag and specifying a use
array, every call to a Neutrino command will look up which middleware
are configured in your in .neutrinorc.js
.
This is the recommended approach when using more than one preset/middleware.
// package.json { "scripts": { "start": "neutrino start", "build": "neutrino build", "test": "neutrino test" } }
// .neutrinorc.js module.exports = { use: [ '@neutrinojs/react', '@neutrinojs/karma' ] }