Neutrino TypeScript React Preset
neutrino-preset-ts-react
is a Neutrino preset that supports building React web applications written in TypeScript.
Features
- Zero upfront configuration necessary to start developing and building a React web app
- Write in TypeScript which is a superset of JavaScript
- Support for React Hot Loader
- Write JSX in .tsx files
- Extends from neutrino-preset-ts
- Webpack loaders for importing HTML, CSS, images, icons, and fonts
- Webpack Dev Server during development
- Automatic creation of HTML pages, no templating necessary
- Hot Module Replacement support
- Tree-shaking to create smaller bundles
- Production-optimized bundles with minification and easy chunking
- Code splitting support to easily split your code into various bundles
- Easily extensible to customize your project as needed
Requirements
- Node.js v6.9+
- Yarn or npm client
- Neutrino v5
Installation
neutrino-preset-ts-react
can be installed via the Yarn or npm clients. Inside your project, make sure
neutrino
, typescript
, and neutrino-preset-ts-react
are development dependencies. You will also need React and React DOM
for actual React development.
Yarn
❯ yarn add --dev neutrino typescript neutrino-preset-ts-react❯ yarn add react react-dom
npm
❯ npm install --save-dev neutrino typescript neutrino-preset-ts-react❯ npm install --save react react-dom
Project Layout
neutrino-preset-ts-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 your compiled project.
Quickstart
After installing Neutrino and the TypeScript preset, we need to add some configuration for the TypeScript compiler. Add a
new file named tsconfig.json
in the root of your project.
❯ touch tsconfig.json
This file contains some TypeScript compiler configuration, and you can read more about its options [here][tsconfig-url].
We do not want to move away from using this file because it is very handy and controls a lot of options. Edit your
tsconfig.json
file with the following minimalist configuration:
Add a new directory named src
in the root of the project, with
a single TS file named index.ts
in it.
❯ mkdir src && touch src/index.ts
This preset exposes an element in the page with an ID of root
to which you can mount your application. Edit
your src/index.ts
file with the following:
;; render, document.getElementById'root';
Now edit your project's package.json to add commands for starting and building the application:
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
neutrino-preset-ts-react
builds static assets to the build
directory by default when running neutrino build
. Using
the quick start example above as a reference:
❯ yarn buildclean-webpack-plugin: /react/build has been removed.Build completed in 6.692s Hash: 7a83f769b15f88b80727Version: webpack 2.2.1Time: 6695ms Asset Size Chunks Chunk Names index.b615ea9e95317f530317.bundle.js 143 kB 0, 1 [emitted] indexmanifest.2211d9c1970bbd3c952b.bundle.js 1.41 kB 1 [emitted] manifest index.html 779 bytes [emitted]✨ Done in 8.32s.
You can either serve or deploy the contents of this build
directory as a static site.
Paths
The neutrino-preset-ts
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.
Customizing
To override the build configuration, start with the documentation on customization.
neutrino-preset-ts-react
does not use any additional named rules, loaders, or plugins that aren't already in use by the
TypeScript preset. See the TypeScript documentation customization
for preset-specific configuration to override.
Simple customization
By following the customization guide and knowing the rule, loader, and plugin IDs above, you can override and augment the build directly from package.json.
Vendoring
By defining an entry point in package.json named vendor
you can split out external dependencies into a chunk separate
from your application code. When working with a React application, it is recommended to start out by splitting off
React and React DOM into the vendor
chunk.
Example: Put React and React DOM into a separate "vendor" chunk:
Running the build again, you can contrast the bundles generated here with the one generated in the quick start:
❯ yarn buildclean-webpack-plugin: /react/build has been removed.Build completed in 6.726s Hash: 0468e662989da55bdc5eVersion: webpack 2.2.1Time: 6730ms Asset Size Chunks Chunk Names vendor.0b3c06ba6b2494d683ee.bundle.js 142 kB 0, 2 [emitted] vendor index.d264625fd405d81cb995.bundle.js 276 bytes 1, 2 [emitted] indexmanifest.29ee4d0db8f2534cc643.bundle.js 1.44 kB 2 [emitted] manifest index.html 866 bytes [emitted]✨ Done in 8.21s.
HTML files
If you wish to override how HTML files are created for your React app, refer to the relevant section on neutrino-preset-web.
Example: Change the application mount ID from "root" to "app":
Advanced configuration
By following the customization guide and knowing the rule, loader, and plugin IDs from neutrino-preset-web, you can override and augment the build by creating a JS module which overrides the config.
Vendoring
By defining an entry point named vendor
you can split out external dependencies into a chunk separate
from your application code.
Example: Put React and React DOM into a separate "vendor" chunk:
module { neutrinoconfig ;};
Hot Module Replacement
While neutrino-preset-ts-react
supports Hot Module Replacement 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 v3+ (currently in beta):
Yarn
❯ yarn add react-hot-loader@next
npm
❯ npm install --save react-hot-loader@next
- From your
index
entry point (defaults tosrc/index.ts
fromneutrino.options.entry
), import anAppContainer
fromreact-hot-loader
. - Wrap your top-level React component in the
AppContainer
. - Perform the application render in a reusable function for initial load and subsequent reloads.
- Add the
hot
acceptance to call this function.
For example:
;;;; ; if module.hot load;