You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 

931 lines
29 KiB

<!DOCTYPE HTML>
<html lang="" >
<head>
<meta charset="UTF-8">
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<title>Usage · Neutrino</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="description" content="">
<meta name="generator" content="GitBook 3.2.2">
<link rel="stylesheet" href="gitbook/style.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-prism/prism.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-npmsearchlist/styles.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-search/search.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css">
<meta name="HandheldFriendly" content="true"/>
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png">
<link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon">
<link rel="next" href="project-layout.html" />
<link rel="prev" href="installation.html" />
</head>
<body>
<div class="book">
<div class="book-summary">
<div id="book-search-input" role="search">
<input type="text" placeholder="Type to search" />
</div>
<nav role="navigation">
<ul class="summary">
<li class="chapter " data-level="1.1" data-path="./">
<a href="./">
Introduction
</a>
</li>
<li class="chapter " data-level="1.2" data-path="installation.html">
<a href="installation.html">
Installation
</a>
</li>
<li class="chapter active" data-level="1.3" data-path="usage.html">
<a href="usage.html">
Usage
</a>
</li>
<li class="chapter " data-level="1.4" data-path="project-layout.html">
<a href="project-layout.html">
Project Layout
</a>
</li>
<li class="chapter " data-level="1.5" data-path="FAQ.html">
<a href="FAQ.html">
FAQ
</a>
</li>
<li class="chapter " data-level="1.6" data-path="presets/">
<a href="presets/">
Presets
</a>
<ul class="articles">
<li class="chapter " data-level="1.6.1" data-path="presets/neutrino-preset-web/">
<a href="presets/neutrino-preset-web/">
Web
</a>
</li>
<li class="chapter " data-level="1.6.2" data-path="presets/neutrino-preset-react/">
<a href="presets/neutrino-preset-react/">
React
</a>
</li>
<li class="chapter " data-level="1.6.3" data-path="presets/neutrino-preset-node/">
<a href="presets/neutrino-preset-node/">
Node.js
</a>
</li>
<li class="chapter " data-level="1.6.4" data-path="presets/neutrino-preset-airbnb-base/">
<a href="presets/neutrino-preset-airbnb-base/">
Airbnb
</a>
</li>
<li class="chapter " data-level="1.6.5" data-path="presets/neutrino-preset-karma/">
<a href="presets/neutrino-preset-karma/">
Karma
</a>
</li>
<li class="chapter " data-level="1.6.6" data-path="presets/neutrino-preset-mocha/">
<a href="presets/neutrino-preset-mocha/">
Mocha
</a>
</li>
<li class="chapter " data-level="1.6.7" data-path="presets/neutrino-preset-jest/">
<a href="presets/neutrino-preset-jest/">
Jest
</a>
</li>
<li class="chapter " data-level="1.6.8" data-path="presets/community-presets.html">
<a href="presets/community-presets.html">
Community presets
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="1.7" data-path="middleware/">
<a href="middleware/">
Middleware
</a>
<ul class="articles">
<li class="chapter " data-level="1.7.1" data-path="middleware/neutrino-middleware-banner/">
<a href="middleware/neutrino-middleware-banner/">
banner
</a>
</li>
<li class="chapter " data-level="1.7.2" data-path="middleware/neutrino-middleware-chunk/">
<a href="middleware/neutrino-middleware-chunk/">
chunk
</a>
</li>
<li class="chapter " data-level="1.7.3" data-path="middleware/neutrino-middleware-clean/">
<a href="middleware/neutrino-middleware-clean/">
clean
</a>
</li>
<li class="chapter " data-level="1.7.4" data-path="middleware/neutrino-middleware-compile-loader/">
<a href="middleware/neutrino-middleware-compile-loader/">
compile-loader
</a>
</li>
<li class="chapter " data-level="1.7.5" data-path="middleware/neutrino-middleware-copy/">
<a href="middleware/neutrino-middleware-copy/">
copy
</a>
</li>
<li class="chapter " data-level="1.7.6" data-path="middleware/neutrino-middleware-env/">
<a href="middleware/neutrino-middleware-env/">
env
</a>
</li>
<li class="chapter " data-level="1.7.7" data-path="middleware/neutrino-middleware-eslint/">
<a href="middleware/neutrino-middleware-eslint/">
eslint
</a>
</li>
<li class="chapter " data-level="1.7.8" data-path="middleware/neutrino-middleware-font-loader/">
<a href="middleware/neutrino-middleware-font-loader/">
font-loader
</a>
</li>
<li class="chapter " data-level="1.7.9" data-path="middleware/neutrino-middleware-hot/">
<a href="middleware/neutrino-middleware-hot/">
hot
</a>
</li>
<li class="chapter " data-level="1.7.10" data-path="middleware/neutrino-middleware-html-loader/">
<a href="middleware/neutrino-middleware-html-loader/">
html-loader
</a>
</li>
<li class="chapter " data-level="1.7.11" data-path="middleware/neutrino-middleware-html-template/">
<a href="middleware/neutrino-middleware-html-template/">
html-template
</a>
</li>
<li class="chapter " data-level="1.7.12" data-path="middleware/neutrino-middleware-image-loader/">
<a href="middleware/neutrino-middleware-image-loader/">
image-loader
</a>
</li>
<li class="chapter " data-level="1.7.13" data-path="middleware/neutrino-middleware-loader-merge/">
<a href="middleware/neutrino-middleware-loader-merge/">
loader-merge
</a>
</li>
<li class="chapter " data-level="1.7.14" data-path="middleware/neutrino-middleware-minify/">
<a href="middleware/neutrino-middleware-minify/">
minify
</a>
</li>
<li class="chapter " data-level="1.7.15" data-path="middleware/neutrino-middleware-named-modules/">
<a href="middleware/neutrino-middleware-named-modules/">
named-modules
</a>
</li>
<li class="chapter " data-level="1.7.16" data-path="middleware/neutrino-middleware-named-start-server/README.md">
<span>
start-server
</a>
</li>
<li class="chapter " data-level="1.7.17" data-path="middleware/neutrino-middleware-named-style-loader/README.md">
<span>
style-loader
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="1.8" data-path="customization/">
<a href="customization/">
Customization
</a>
<ul class="articles">
<li class="chapter " data-level="1.8.1" data-path="customization/simple.html">
<a href="customization/simple.html">
Simple
</a>
</li>
<li class="chapter " data-level="1.8.2" data-path="customization/advanced.html">
<a href="customization/advanced.html">
Advanced
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="1.9" data-path="creating-presets.html">
<a href="creating-presets.html">
Creating presets
</a>
</li>
<li class="chapter " data-level="1.10" data-path="learning-resources.html">
<a href="learning-resources.html">
Learning Resources
</a>
</li>
<li class="chapter " data-level="1.11" data-path="api/">
<a href="api/">
API
</a>
</li>
<li class="chapter " data-level="1.12" data-path="cli/">
<a href="cli/">
CLI
</a>
</li>
<li class="chapter " data-level="1.13" data-path="upgrading-neutrino.html">
<a href="upgrading-neutrino.html">
Upgrading from v4 to v5
</a>
</li>
<li class="chapter " data-level="1.14" >
<a target="_blank" href="https://github.com/mozilla-neutrino/neutrino-dev/tree/docs-v4/docs">
v4 Documentation
</a>
</li>
<li class="chapter " data-level="1.15" data-path="contributing/">
<a href="contributing/">
Contributing
</a>
<ul class="articles">
<li class="chapter " data-level="1.15.1" data-path="contributing/development.html">
<a href="contributing/development.html">
Development Process
</a>
</li>
<li class="chapter " data-level="1.15.2" data-path="contributing/code-of-conduct.html">
<a href="contributing/code-of-conduct.html">
Code of Conduct
</a>
</li>
</ul>
</li>
<li class="divider"></li>
<li>
<a href="https://www.gitbook.com" target="blank" class="gitbook-link">
Published with GitBook
</a>
</li>
</ul>
</nav>
</div>
<div class="book-body">
<div class="body-inner">
<div class="book-header" role="navigation">
<!-- Title -->
<h1>
<i class="fa fa-circle-o-notch fa-spin"></i>
<a href="." >Usage</a>
</h1>
</div>
<div class="page-wrapper" tabindex="-1" role="main">
<div class="page-inner">
<div id="book-search-results">
<div class="search-noresults">
<section class="normal markdown-section">
<h1 id="usage">Usage</h1>
<p>Neutrino is a command-line tool that wraps Webpack in order to support building JavaScript projects
based on shared configuration presets. You can use Neutrino within your project, preferably using
scripts defined in your project&apos;s <code>package.json</code>.</p>
<h2 id="setup">Setup</h2>
<p>After completing the <a href="installation.html">installation</a> of Neutrino and your Neutrino preset, you will
want to define some scripts in your project&apos;s <code>package.json</code> in order to simply build your project.
In a typical project:</p>
<ul>
<li><code>scripts.start</code> would be the command you wish to run during development</li>
<li><code>scripts.build</code> would be the command you wish to run to create a production bundle</li>
<li><code>scripts.test</code> would be the command you wish to run to execute tests</li>
</ul>
<p>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.</p>
<h2 id="building-for-development">Building for development</h2>
<p>Neutrino provides the command <code>neutrino start</code> for creating a bundle during development. Using
<code>neutrino start</code> sets the Node.js environment to <code>development</code> using the <code>NODE_ENV</code> environment variable,
which is available in your project source code. Depending on the presets you are using, <code>neutrino start</code>
may also spin up a development server with Hot Module Replacement (HMR) capabilities.
Check the documentation of your preset for details.</p>
<p>Usage:</p>
<pre class="language-"><code class="lang-bash"><span class="token comment" spellcheck="true"># PRESET_MODULE is the name of the preset to build with, e.g. neutrino-preset-react</span>
neutrino start --use PRESET_MODULE
</code></pre>
<p>Putting this into your <code>package.json</code> will allow you to build your project using either
<code>yarn start</code> or <code>npm start</code>. Using <code>neutrino-preset-react</code> as an example:</p>
<pre class="language-"><code class="lang-json"><span class="token punctuation">{</span>
<span class="token property">&quot;scripts&quot;</span><span class="token operator">:</span> <span class="token punctuation">{</span>
<span class="token property">&quot;start&quot;</span><span class="token operator">:</span> <span class="token string">&quot;neutrino start --use neutrino-preset-react&quot;</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre>
<h2 id="building-for-production">Building for production</h2>
<p>Neutrino provides the command <code>neutrino build</code> for creating a bundle for production deployment.
Using <code>neutrino build</code> sets the Node.js environment to <code>production</code> using the <code>NODE_ENV</code> 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.</p>
<pre class="language-"><code class="lang-bash"><span class="token comment" spellcheck="true"># PRESET_MODULE is the name of the preset to build with, e.g. neutrino-preset-react</span>
neutrino build --use PRESET_MODULE
</code></pre>
<p>Putting this into your <code>package.json</code> will allow you to build your project using either
<code>yarn build</code> or <code>npm run build</code>. Using <code>neutrino-preset-react</code> as an example:</p>
<pre class="language-"><code class="lang-json"><span class="token punctuation">{</span>
<span class="token property">&quot;scripts&quot;</span><span class="token operator">:</span> <span class="token punctuation">{</span>
<span class="token property">&quot;build&quot;</span><span class="token operator">:</span> <span class="token string">&quot;neutrino build --use neutrino-preset-react&quot;</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre>
<h2 id="building-and-running-tests">Building and running tests</h2>
<p>Neutrino provides the command <code>neutrino test</code> for invoking a set of tests included in your project.
Using <code>neutrino test</code> sets the Node.js environment variable to <code>test</code> using the <code>NODE_ENV</code> environment
variable, which is available in your project source code. How your source code is built and consumed from tests
is determined by the presets you are using. Running suites that are built the same as source files is encouraged by
using a Neutrino-compatible preset. Neutrino currently provides three core testing presets: Karma, Jest, and Mocha.</p>
<pre class="language-"><code class="lang-bash"><span class="token comment" spellcheck="true"># PRESET_MODULE is the name of the preset to build with, e.g. neutrino-preset-react</span>
<span class="token comment" spellcheck="true"># TESTING_MODULE is the name of another preset to build with, e.g. neutrino-preset-karma</span>
neutrino build --use PRESET_MODULE TESTING_MODULE
</code></pre>
<p>Putting this into your <code>package.json</code> will allow you to test your project using either
<code>yarn test</code> or <code>npm test</code>. Using <code>neutrino-preset-react</code> and <code>neutrino-preset-karma</code> as an example:</p>
<pre class="language-"><code class="lang-json"><span class="token punctuation">{</span>
<span class="token property">&quot;scripts&quot;</span><span class="token operator">:</span> <span class="token punctuation">{</span>
<span class="token property">&quot;test&quot;</span><span class="token operator">:</span> <span class="token string">&quot;neutrino test --use neutrino-preset-react neutrino-preset-karma&quot;</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre>
<p>Using the command <code>neutrino test</code> will execute every test file located in your
<a href="project-layout#Testing">testing directory</a>. 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 <code>--use</code> parameter, you should use two
dashes after the last middleware to denote the end of the middleware and the beginning of the test files.</p>
<pre class="language-"><code class="lang-bash">neutrino <span class="token function">test</span> --use PRESET_A PRESET_B -- a_test.js b_test.js
</code></pre>
<h2 id="using-multiple-presets">Using multiple presets</h2>
<p>All Neutrino commands support the <code>--use</code> 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 <code>neutrino.use</code> field in your project&apos;s package.json file. By omitting the <code>--use</code>
flag and specifying a <code>neutrino.use</code> array, every call to a Neutrino command will look up which presets are
configured in your package.json.</p>
<p>This is the recommended approach when using more than one preset.</p>
<pre class="language-"><code class="lang-json"><span class="token punctuation">{</span>
<span class="token property">&quot;neutrino&quot;</span><span class="token operator">:</span> <span class="token punctuation">{</span>
<span class="token property">&quot;use&quot;</span><span class="token operator">:</span> <span class="token punctuation">[</span>
<span class="token string">&quot;neutrino-preset-react&quot;</span><span class="token punctuation">,</span>
<span class="token string">&quot;neutrino-preset-karma&quot;</span>
<span class="token punctuation">]</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token property">&quot;scripts&quot;</span><span class="token operator">:</span> <span class="token punctuation">{</span>
<span class="token property">&quot;start&quot;</span><span class="token operator">:</span> <span class="token string">&quot;neutrino start&quot;</span><span class="token punctuation">,</span>
<span class="token property">&quot;build&quot;</span><span class="token operator">:</span> <span class="token string">&quot;neutrino build&quot;</span><span class="token punctuation">,</span>
<span class="token property">&quot;test&quot;</span><span class="token operator">:</span> <span class="token string">&quot;neutrino test&quot;</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre>
</section>
</div>
<div class="search-results">
<div class="has-results">
<h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
<ul class="search-results-list"></ul>
</div>
<div class="no-results">
<h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
</div>
</div>
</div>
</div>
</div>
</div>
<a href="installation.html" class="navigation navigation-prev " aria-label="Previous page: Installation">
<i class="fa fa-angle-left"></i>
</a>
<a href="project-layout.html" class="navigation navigation-next " aria-label="Next page: Project Layout">
<i class="fa fa-angle-right"></i>
</a>
</div>
<script>
var gitbook = gitbook || [];
gitbook.push(function() {
gitbook.page.hasChanged({"page":{"title":"Usage","level":"1.3","depth":1,"next":{"title":"Project Layout","level":"1.4","depth":1,"path":"project-layout.md","ref":"./project-layout.md","articles":[]},"previous":{"title":"Installation","level":"1.2","depth":1,"path":"installation.md","ref":"./installation.md","articles":[]},"dir":"ltr"},"config":{"plugins":["edit-link","prism","-highlight","github","anchorjs","npmsearchlist"],"root":"./docs","styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"prism":{},"github":{"url":"https://github.com/mozilla-neutrino/neutrino-dev/"},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"npmsearchlist":{},"fontsettings":{"theme":"white","family":"sans","size":2},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"edit-link":{"label":"Edit page","base":"https://github.com/mozilla-neutrino/neutrino-dev/tree/master/docs"},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false},"anchorjs":{}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Neutrino","gitbook":"*"},"file":{"path":"usage.md","mtime":"2017-03-24T23:27:54.000Z","type":"markdown"},"gitbook":{"version":"3.2.2","time":"2017-05-11T00:08:48.026Z"},"basePath":".","book":{"language":""}});
});
</script>
</div>
<script src="gitbook/gitbook.js"></script>
<script src="gitbook/theme.js"></script>
<script src="gitbook/gitbook-plugin-edit-link/plugin.js"></script>
<script src="gitbook/gitbook-plugin-github/plugin.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/3.1.1/anchor.min.js"></script>
<script src="gitbook/gitbook-plugin-anchorjs/anchor-style.js"></script>
<script src="gitbook/gitbook-plugin-npmsearchlist/script.js"></script>
<script src="gitbook/gitbook-plugin-search/search-engine.js"></script>
<script src="gitbook/gitbook-plugin-search/search.js"></script>
<script src="gitbook/gitbook-plugin-lunr/lunr.min.js"></script>
<script src="gitbook/gitbook-plugin-lunr/search-lunr.js"></script>
<script src="gitbook/gitbook-plugin-sharing/buttons.js"></script>
<script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>
</body>
</html>