Neutrino React Preset¶
@neutrinojs/react
is a Neutrino preset that supports building React web applications.
Features¶
- Zero upfront configuration necessary to start developing and building a React web app
- Modern Babel compilation adding JSX, object rest spread syntax, and class properties.
- Support for React Hot Loader
- Write JSX in .js or .jsx files
- Extends from @neutrinojs/web
- Modern Babel compilation supporting ES modules, last 2 major browser versions, async functions, and dynamic imports
- webpack loaders for importing HTML, CSS, images, icons, fonts, and web workers
- webpack Dev Server during development
- Automatic creation of HTML pages, no templating necessary
- Automatic stylesheet extraction; importing stylesheets into modules creates bundled external stylesheets
- Pre-configured to support CSS Modules via
*.module.css
file extensions - Hot Module Replacement support including CSS
- Tree-shaking to create smaller bundles
- Production-optimized bundles with minification, easy chunking, and scope-hoisted modules for faster execution
- Easily extensible to customize your project as needed
Requirements¶
- Node.js v8.3+
- Yarn v1.2.1+, or npm v5.4+
- Neutrino v8
Installation¶
@neutrinojs/react
can be installed via the Yarn or npm clients. Inside your project, make sure
neutrino
and @neutrinojs/react
are development dependencies. You will also need React and React DOM for actual
React development.
Yarn¶
❯ yarn add --dev neutrino @neutrinojs/react ❯ yarn add react react-dom
npm¶
❯ npm install --save-dev neutrino @neutrinojs/react ❯ npm install --save react react-dom
Project Layout¶
@neutrinojs/react
follows the standard project layout specified by Neutrino. This
means that by default all project source code should live in a directory named src
in the root of the
project. This includes JavaScript files, CSS stylesheets, images, and any other assets that would be available
to import your compiled project.
Quickstart¶
The fastest way to get started is by using the create-project
scaffolding tool.
Don’t want to use the CLI helper? No worries, we have you covered with the manual installation.
create-project¶
Run the following command to start the process. Substitute <directory-name>
with the directory name you wish to create
for this project.
Yarn¶
❯ yarn create @neutrinojs/project <directory-name>
Note: The create
command is a shorthand that helps you do two things at once. See the Yarn create docs for more details.
npm/npx¶
npx
comes pre-installed with npm
. If you’re running an older version of npm
, then
npm install -g npm
to update to the latest version.
❯ npx @neutrinojs/create-project <directory-name>
The CLI helper will prompt for the project to scaffold, and will offer to set up a test runner as well as linting to your project. Refer to the Create new project section for details on all available options.
Manual Installation¶
After installing Neutrino and the React preset, add a new directory named src
in the root of the project, with
a single JS file named index.js
in it.
❯ mkdir src && touch src/index.js
This React preset exposes an element in the page with an ID of root
to which you can mount your application. Edit
your src/index.js
file with the following:
import { render } from 'react-dom'; render(<h1>Hello world!</h1>, document.getElementById('root'));
Now edit your project's package.json to add commands for starting and building the application:
{ "scripts": { "start": "neutrino start --use @neutrinojs/react", "build": "neutrino build --use @neutrinojs/react" } }
If you are using .neutrinorc.js
, add this preset to your use array instead of --use
flags:
module.exports = { use: ['@neutrinojs/react'] };
Start the app, then open a browser to the address in the console:
Yarn¶
❯ yarn start ✔ Development server running on: http://localhost:5000 ✔ Build completed
npm¶
❯ npm start ✔ Development server running on: http://localhost:5000 ✔ Build completed
Building¶
@neutrinojs/react
builds static assets to the build
directory by default when running neutrino build
. Using
the quick start example above as a reference:
❯ yarn build ✔ Building project completed Hash: b26ff013b5a2d5f7b824 Version: webpack 3.5.6 Time: 9773ms Asset Size Chunks Chunk Names index.dfbad882ab3d86bfd747.js 181 kB index [emitted] index runtime.3d9f9d2453f192a2b10f.js 1.51 kB runtime [emitted] runtime index.html 846 bytes [emitted] ✨ Done in 14.62s.
You can either serve or deploy the contents of this build
directory as a static site.
Static assets¶
If you wish to copy files to the build directory that are not imported from application code, use the @neutrinojs/copy preset alongside this one.
Paths¶
The @neutrinojs/web
preset loads assets relative to the path of your application by setting webpack's
output.publicPath
to ./
. If you wish to load
assets instead from a CDN, or if you wish to change to an absolute path for your application, customize your build to
override output.publicPath
. See the Customizing section below.
For details on merging and overriding Babel configuration, such as supporting decorator syntax, read more
about using the compile-loader
merge
once you
are comfortable customizing your build.
Preset options¶
You can provide custom options and have them merged with this preset's default options to easily affect how this
preset builds. You can modify React preset settings from .neutrinorc.js
by overriding with an options object. Use
an array pair instead of a string to supply these options in .neutrinorc.js
.
The following shows how you can pass an options object to the React preset and override its options. See the Web documentation for specific options you can override with this object.
module.exports = { use: [ ['@neutrinojs/react', { /* preset options */ // Example: disable Hot Module Replacement hot: false, // Example: change the page title html: { title: 'Epic React App' }, // Target specific browsers with @babel/preset-env targets: { browsers: [ 'last 1 Chrome versions', 'last 1 Firefox versions' ] }, // Add additional Babel plugins, presets, or env options babel: { // Override options for @babel/preset-env: presets: [ ['@babel/preset-env', { modules: false, useBuiltIns: true, }] ] } }] ] };
Customizing¶
To override the build configuration, start with the documentation on customization.
@neutrinojs/react
does not use any additional named rules, loaders, or plugins that aren't already in use by the
Web preset. See the Web documentation customization
for preset-specific configuration to override.
For details on merging and overriding Babel configuration, such as supporting decorator syntax, read more
about using the compile-loader
merge
once you
are comfortable customizing your build.
Advanced configuration¶
By following the customization guide and knowing the rule, loader, and plugin IDs from
@neutrinojs/web
, you can override and augment the build by providing a function to your .neutrinorc.js
use
array. You can also make these changes from the Neutrino API in custom middleware.
By default Neutrino, and therefore this preset, creates a single main index
entry point to your application, and
this maps to the index.*
file in the src
directory. The extension is resolved by webpack. This value is provided by
neutrino.options.mains
at neutrino.options.mains.index
. This means that the Web preset is optimized toward the use
case of single-page applications over multi-page applications. If you wish to output multiple pages, you can detail
all your mains in your .neutrinorc.js
.
module.exports = { options: { mains: { index: 'index', // outputs index.html from src/index.* admin: 'admin', // outputs admin.html from src/admin.* account: 'user' // outputs account.html from src/user.* } }, use: ['@neutrinojs/react'] }
Vendoring¶
External dependencies are automatically split into separate chunks from the application code, by the new webpack SplitChunksPlugin.
Example: The splitChunks settings can be adjusted like so:
module.exports = { use: [ '@neutrinojs/react', (neutrino) => { neutrino.config .optimization .merge({ splitChunks: { // Decrease the minimum size before extra chunks are created, to 10KB minSize: 10000 } }); } ] };
Hot Module Replacement¶
While @neutrinojs/react
supports Hot Module Replacement for your app using
React Hot Loader, it does require some application-specific changes in order to
operate.
First, install react-hot-loader
as a dependency, this must be
React Hot Loader v4+:
Yarn¶
❯ yarn add react-hot-loader
npm¶
❯ npm install --save react-hot-loader
Neutrino will then automatically load React Hot Loader then next time a build is performed. Next, you need to mark your root component as hot-exported.
For example, if your src/index
main entry renders a root component from
App.jsx
, then the exported component needs to have a hot export:
// src/App.jsx import React from 'react' import { hot } from 'react-hot-loader' const App = () => <div>Hello World!</div> export default hot(module)(App);
See the React Hot Loader docs for any API specifics on hot reloading other components.
Contributing¶
This preset is part of the neutrino-dev repository, a monorepo containing all resources for developing Neutrino and its core presets and middleware. Follow the contributing guide for details.