Eli Perelman
8 years ago
13 changed files with 529 additions and 465 deletions
@ -1 +0,0 @@ |
|||
# heading |
|||
@ -1 +1,224 @@ |
|||
# heading |
|||
# Neutrino React Preset [![NPM version][npm-image]][npm-url] |
|||
|
|||
`neutrino-preset-react` is a Neutrino preset that supports building React web applications. |
|||
|
|||
## Features |
|||
|
|||
- Modern Babel compilation adding JSX and object rest spread syntax. |
|||
- Support for React Hot Loader |
|||
- Write JSX in .js or .jsx files |
|||
- Extends from [neutrino-preset-web](/presets/neutrino-preset-web/README.md) |
|||
- Modern Babel compilation supporting ES modules, last 2 major browser versions, and async functions |
|||
- 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 |
|||
- Production-optimized bundles with Babili minification and easy chunking |
|||
- Easily extensible to customize your project as needed |
|||
|
|||
## Requirements |
|||
|
|||
- Node.js v6.9+ |
|||
- Yarn or npm client |
|||
- Neutrino v4 |
|||
|
|||
## Installation |
|||
|
|||
`neutrino-preset-react` can be installed via the Yarn or npm clients. Inside your project, make sure |
|||
`neutrino` and `neutrino-preset-react` are development dependencies. You will also need React and React DOM for actual |
|||
React development. |
|||
|
|||
#### Yarn |
|||
|
|||
```bash |
|||
❯ yarn add --dev neutrino neutrino-preset-react |
|||
❯ yarn add react react-dom |
|||
``` |
|||
|
|||
#### npm |
|||
|
|||
```bash |
|||
❯ npm install --save-dev neutrino neutrino-preset-react |
|||
❯ npm install --save react react-dom |
|||
``` |
|||
|
|||
## Project Layout |
|||
|
|||
`neutrino-preset-react` follows the standard [project layout](/project-layout.md) 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 React preset, add a new directory named `src` in the root of the project, with |
|||
a single JS file named `index.js` in it. |
|||
|
|||
```bash |
|||
❯ 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: |
|||
|
|||
```jsx |
|||
import React from 'react'; |
|||
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: |
|||
|
|||
```json |
|||
{ |
|||
"scripts": { |
|||
"start": "neutrino start --presets neutrino-preset-react", |
|||
"build": "neutrino build --presets neutrino-preset-react" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Start the app, then open a browser to the address in the console: |
|||
|
|||
#### Yarn |
|||
|
|||
```bash |
|||
❯ yarn start |
|||
✔ Development server running on: http://localhost:5000 |
|||
✔ Build completed |
|||
``` |
|||
|
|||
#### npm |
|||
|
|||
```bash |
|||
❯ npm start |
|||
✔ Development server running on: http://localhost:5000 |
|||
✔ Build completed |
|||
``` |
|||
|
|||
## Building |
|||
|
|||
`neutrino-preset-react` builds static assets to the `build` directory by default when running `neutrino build`. Using |
|||
the quick start example above as a reference: |
|||
|
|||
```bash |
|||
❯ yarn build |
|||
clean-webpack-plugin: /react/build has been removed. |
|||
Build completed in 6.692s |
|||
|
|||
Hash: 7a83f769b15f88b80727 |
|||
Version: webpack 2.2.1 |
|||
Time: 6695ms |
|||
Asset Size Chunks Chunk Names |
|||
index.b615ea9e95317f530317.bundle.js 143 kB 0, 1 [emitted] index |
|||
manifest.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. |
|||
|
|||
## Customizing |
|||
|
|||
To override the build configuration, start with the documentation on [customization](/customization/README.md). |
|||
`neutrino-preset-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](/presets/neutrino-preset-web#customizing) |
|||
for preset-specific configuration to override. |
|||
|
|||
### Simple customization |
|||
|
|||
By following the [customization guide](/customization/simple.md) 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:_ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"entry": { |
|||
"vendor": [ |
|||
"react", |
|||
"react-dom" |
|||
] |
|||
} |
|||
} |
|||
}, |
|||
"dependencies": { |
|||
"react": "^15.4.2", |
|||
"react-dom": "^15.4.2" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Running the build again, you can contrast the bundles generated here with the one generated in the quick start: |
|||
|
|||
```bash |
|||
❯ yarn build |
|||
clean-webpack-plugin: /react/build has been removed. |
|||
Build completed in 6.726s |
|||
|
|||
Hash: 0468e662989da55bdc5e |
|||
Version: webpack 2.2.1 |
|||
Time: 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] index |
|||
manifest.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](/presets/neutrino-preset-web/README.md#html-files). |
|||
|
|||
_Example: Change the application mount ID from "root" to "app":_ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"html": { |
|||
"appMountId": "app" |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Advanced configuration |
|||
|
|||
By following the [customization guide](/customization/advanced.md) 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:_ |
|||
|
|||
```js |
|||
module.exports = neutrino => { |
|||
neutrino.config |
|||
.entry('vendor') |
|||
.add('react') |
|||
.add('react-dom'); |
|||
}; |
|||
``` |
|||
|
|||
## Contributing |
|||
|
|||
This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo |
|||
containing all resources for developing Neutrino and its core presets. Follow the |
|||
[contributing guide](/contributing/README.md) for details. |
|||
|
|||
[npm-image]: https://badge.fury.io/js/neutrino-preset-react.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-react |
|||
|
|||
@ -1 +1,223 @@ |
|||
# heading |
|||
# Neutrino Web Preset [![NPM version][npm-image]][npm-url] |
|||
|
|||
`neutrino-preset-web` is a Neutrino preset that supports building generic applications for the web. |
|||
|
|||
## Features |
|||
|
|||
- Modern Babel compilation supporting ES modules, last 2 major browser versions, and async functions |
|||
- 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 |
|||
- Production-optimized bundles with Babili minification and easy chunking |
|||
- Easily extensible to customize your project as needed |
|||
|
|||
## Requirements |
|||
|
|||
- Node.js v6.9+ |
|||
- Yarn or npm client |
|||
- Neutrino v4 |
|||
|
|||
## Installation |
|||
|
|||
`neutrino-preset-web` can be installed via the Yarn or npm clients. Inside your project, make sure |
|||
`neutrino` and `neutrino-preset-web` are development dependencies. |
|||
|
|||
#### Yarn |
|||
|
|||
```bash |
|||
❯ yarn add --dev neutrino neutrino-preset-web |
|||
``` |
|||
|
|||
#### npm |
|||
|
|||
```bash |
|||
❯ npm install --save-dev neutrino neutrino-preset-web |
|||
``` |
|||
|
|||
## Project Layout |
|||
|
|||
`neutrino-preset-web` follows the standard [project layout](/project-layout.md) 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 Web preset, add a new directory named `src` in the root of the project, with |
|||
a single JS file named `index.js` in it. |
|||
|
|||
```bash |
|||
❯ mkdir src && touch src/index.js |
|||
``` |
|||
|
|||
This Web 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: |
|||
|
|||
```js |
|||
const app = document.createElement('main'); |
|||
const text = document.createTextNode('Hello world!'); |
|||
|
|||
app.appendChild(text); |
|||
document.getElementById('root').appendChild(app); |
|||
``` |
|||
|
|||
Now edit your project's package.json to add commands for starting and building the application: |
|||
|
|||
```json |
|||
{ |
|||
"scripts": { |
|||
"start": "neutrino start --presets neutrino-preset-web", |
|||
"build": "neutrino build --presets neutrino-preset-web" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Start the app, then open a browser to the address in the console: |
|||
|
|||
#### Yarn |
|||
|
|||
```bash |
|||
❯ yarn start |
|||
✔ Development server running on: http://localhost:5000 |
|||
✔ Build completed |
|||
``` |
|||
|
|||
#### npm |
|||
|
|||
```bash |
|||
❯ npm start |
|||
✔ Development server running on: http://localhost:5000 |
|||
✔ Build completed |
|||
``` |
|||
|
|||
## Building |
|||
|
|||
`neutrino-preset-web` builds static assets to the `build` directory by default when running `neutrino build`. Using the |
|||
quick start example above as a reference: |
|||
|
|||
```bash |
|||
❯ yarn build |
|||
clean-webpack-plugin: /web/build has been removed. |
|||
Build completed in 0.779s |
|||
|
|||
Hash: 55c33df4cd1222a03505 |
|||
Version: webpack 2.2.1 |
|||
Time: 784ms |
|||
Asset Size Chunks Chunk Names |
|||
index.52f2d06086f51d21f9c9.bundle.js 213 bytes 0, 1 [emitted] index |
|||
manifest.c10c6464802bf71a2c3f.bundle.js 1.41 kB 1 [emitted] manifest |
|||
index.html 779 bytes [emitted] |
|||
✨ Done in 2.10s. |
|||
``` |
|||
|
|||
You can either serve or deploy the contents of this `build` directory as a static site. |
|||
|
|||
## Customizing |
|||
|
|||
To override the build configuration, start with the documentation on [customization](/customization/README.md). |
|||
`neutrino-preset-web` creates some conventions to make overriding the configuration easier once you are ready to make |
|||
changes. |
|||
|
|||
By default the Web preset creates a single **main** `index` entry point to your application, and this maps to the |
|||
`index.js` file in the `src` directory. This means that the Web preset is optimized toward the use case of single-page |
|||
applications over multi-page applications. |
|||
|
|||
### Rules |
|||
|
|||
The following is a list of rules and their identifiers which can be overridden: |
|||
|
|||
- `compile`: Compiles JS files from the `src` directory using Babel. Contains a single loader named `babel`. |
|||
- `html`: Allows importing HTML files from modules. Contains a single loader named `file`. |
|||
- `css`: Allows importing CSS stylesheets from modules. Contains two loaders named `style` and `css`. |
|||
- `img`, `svg`, `ico`: Allows import image files from modules. Each contains a single loader named `url`. |
|||
- `woff`, `ttf`: Allows importing WOFF and TTF font files from modules. Each contains a single loader named `url`. |
|||
- `eot`: Allows importing EOT font files from modules. Contains a single loader named `file`. |
|||
|
|||
### Plugins |
|||
|
|||
The following is a list of plugins and their identifiers which can be overridden: |
|||
|
|||
- `env`: Injects the value of `NODE_ENV` into the application as `process.env.NODE_ENV`. |
|||
- `html`: Creates HTML files when building. Has various options that can be configured via package.json. |
|||
- `chunk`: Defines chunks for `manifest` and `vendor` entry points. Can be configured via package.json. |
|||
- `hot`: Enables hot module reloading. |
|||
- `copy`: Copies non-JS files from `src` to `build` when using `neutrino build`. |
|||
- `clean`: Clears the contents of `build` prior to creating a production bundle. |
|||
- `progress`: Displays a progress bar when using `neutrino build`. |
|||
|
|||
### Simple customization |
|||
|
|||
By following the [customization guide](/customization/simple.md) 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. |
|||
|
|||
_Example: Put lodash into a separate "vendor" chunk:_ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"entry": { |
|||
"vendor": [ |
|||
"lodash" |
|||
] |
|||
} |
|||
} |
|||
}, |
|||
"dependencies": { |
|||
"lodash": "*" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
#### HTML files |
|||
|
|||
Under the hood `neutrino-preset-web` uses [html-webpack-template](https://www.npmjs.com/package/html-webpack-template) |
|||
for generating HTML files. If you wish to override how these files are creating, define an object in your package.json |
|||
at `config.html` with options matching the format expected by html-webpack-template. |
|||
|
|||
_Example: Change the application mount ID from "root" to "app":_ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"html": { |
|||
"appMountId": "app" |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Advanced configuration |
|||
|
|||
By following the [customization guide](/customization/advanced.md) and knowing the rule, loader, and plugin IDs above, |
|||
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 lodash into a separate "vendor" chunk:_ |
|||
|
|||
```js |
|||
module.exports = neutrino => { |
|||
neutrino.config |
|||
.entry('vendor') |
|||
.add('lodash'); |
|||
}; |
|||
``` |
|||
|
|||
## Contributing |
|||
|
|||
This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo |
|||
containing all resources for developing Neutrino and its core presets. Follow the |
|||
[contributing guide](/contributing/README.md) for details. |
|||
|
|||
[npm-image]: https://badge.fury.io/js/neutrino-preset-web.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-web |
|||
|
|||
@ -1 +1,11 @@ |
|||
# Neutrino Jest Preset |
|||
# Neutrino Jest Preset [![NPM version][npm-image]][npm-url] |
|||
|
|||
`neutrino-preset-jest` is a Neutrino preset that supports testing JavaScript projects with the Jest test runner. |
|||
|
|||
## Documentation |
|||
|
|||
See the [Neutrino docs](http://neutrino.js.org/presets/neutrino-preset-jest/) |
|||
for details on installation, getting started, usage, and customizing. |
|||
|
|||
[npm-image]: https://badge.fury.io/js/neutrino-preset-jest.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-jest |
|||
|
|||
@ -1 +1,11 @@ |
|||
# Neutrino Karma Preset |
|||
# Neutrino Karma Preset [![NPM version][npm-image]][npm-url] |
|||
|
|||
`neutrino-preset-karma` is a Neutrino preset that supports testing web applications using the Karma test runner. |
|||
|
|||
## Documentation |
|||
|
|||
See the [Neutrino docs](http://neutrino.js.org/presets/neutrino-preset-karma/) |
|||
for details on installation, getting started, usage, and customizing. |
|||
|
|||
[npm-image]: https://badge.fury.io/js/neutrino-preset-karma.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-karma |
|||
|
|||
@ -1 +1,11 @@ |
|||
# Neutrino Mocha Preset |
|||
# Neutrino Mocha Preset [![NPM version][npm-image]][npm-url] |
|||
|
|||
`neutrino-preset-mocha` is a Neutrino preset that supports testing JavaScript projects with the Mocha test runner. |
|||
|
|||
## Documentation |
|||
|
|||
See the [Neutrino docs](http://neutrino.js.org/presets/neutrino-preset-mocha/) |
|||
for details on installation, getting started, usage, and customizing. |
|||
|
|||
[npm-image]: https://badge.fury.io/js/neutrino-preset-mocha.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-mocha |
|||
|
|||
@ -1,108 +1,12 @@ |
|||
# Neutrino Web Preset [![NPM version][npm-image]][npm-url] [![Dependency Status][daviddm-image]][daviddm-url] |
|||
# Neutrino Web Preset [![NPM version][npm-image]][npm-url] |
|||
|
|||
This [neutrino](https://github.com/mozilla-neutrino/neutrino) preset enables building generic web |
|||
applications with a common configuration for Webpack, ESLint, Babel, Karma+Mocha, along with a |
|||
static local development server. |
|||
`neutrino-preset-web` is a Neutrino preset that supports building generic applications for the web. |
|||
|
|||
<sup>This preset extends the [neutrino-preset-base preset](https://github.com/mozilla-neutrino/neutrino-preset-base) by enhancing it with web-specific configuration.</sup> |
|||
## Documentation |
|||
|
|||
# Getting started |
|||
|
|||
Install neutrino and neutrino-preset-web as development dependencies in your project: |
|||
|
|||
```sh |
|||
# npm |
|||
npm install --save-dev neutrino neutrino-preset-web |
|||
|
|||
# yarn |
|||
yarn add neutrino neutrino-preset-web --dev |
|||
``` |
|||
|
|||
Modify your package.json scripts to use the web preset to build your project |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"preset": "neutrino-preset-web" |
|||
}, |
|||
"scripts": { |
|||
"start": "PORT=4000 neutrino start", |
|||
"build": "neutrino build", |
|||
"test": "neutrino test" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Add your source code to `src/`, which is compiled using Babel's es2015 preset. A number of loaders |
|||
are pre-configured, allowing you to use `import` and `export` for CSS, images, HTML, and JSON. |
|||
During development, run `npm start` or `yarn start` to start a local development server for running the application. |
|||
When you are ready to build your project into static assets, run `npm run build` or `yarn run build` which will create |
|||
a `build/` directory in the root of your project. |
|||
|
|||
If you would like to use testing in your project, create a `test/` directory, and write tests in |
|||
JS files with file names ending in `_test.js`, e.g. `test/homepage_test.js` or |
|||
`test/users/admin_test.js`. Run tests with `npm test` or `yarn test`, which will output results to the console, and |
|||
also creates test coverage to a `.coverage/` directory. |
|||
|
|||
# Overriding the preset |
|||
|
|||
There may be times where this preset works well for you, but you need to change some of the defaults |
|||
it provides. Maybe you don't like the opinion of the ESLint rules, or want to add more types of file |
|||
loading. Whatever the reason for needing changes, you can either create a custom preset based on |
|||
this one, or change the values on a project-by-project basis. |
|||
|
|||
To override in your project, create a new file to use as a preset which will modify the existing |
|||
one, e.g. `custom-preset.js`: |
|||
|
|||
```js |
|||
// bring in the existing preset |
|||
const preset = require('neutrino-preset-web'); |
|||
|
|||
// modify the preset |
|||
|
|||
// re-export the preset |
|||
module.exports = preset; |
|||
``` |
|||
|
|||
Now you can pass this file to neutrino to use as the new preset: |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"preset": "custom-preset.js" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
You can also choose to load different presets for different targets if you so wish: |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"preset": "custom-preset.js" |
|||
}, |
|||
"scripts": { |
|||
"start": "neutrino start", |
|||
"test": "neutrino test --preset some-other-preset", |
|||
"build": "neutrino build --preset neutrino-preset-web" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
# Overriding the default page template |
|||
|
|||
By default, HTML files are built using the template located in `src/template.ejs` in this repo. If |
|||
you wish to use a custom template or if the default just doesn't suit your needs, you can create a |
|||
`template.ejs` file in your `src/` directory, and this preset will pick it up automatically. |
|||
|
|||
# Technology |
|||
|
|||
* [neutrino-preset-base](https://www.npmjs.com/package/neutrino-preset-base) |
|||
* [html-webpack-plugin](https://www.npmjs.com/package/html-webpack-plugin) simplifies creation of HTML files to serve webpack bundles |
|||
* [webpack-dev-server](https://www.npmjs.com/package/webpack-dev-server) Serves a webpack app. Updates the browser on changes |
|||
* [Karma](https://www.npmjs.com/package/karma) Test Runner for JavaScript |
|||
|
|||
[npm-image]: https://badge.fury.io/js/neutrino-preset-web.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-web |
|||
[daviddm-image]: https://david-dm.org/mozilla-neutrino/neutrino-preset-web.svg |
|||
[daviddm-url]: https://david-dm.org/mozilla-neutrino/neutrino-preset-web |
|||
See the [Neutrino docs](http://neutrino.js.org/presets/neutrino-preset-web/) |
|||
for details on installation, getting started, usage, and customizing. |
|||
|
|||
[npm-image]: https://badge.fury.io/js/neutrino-preset-web.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-web |
|||
|
|||
@ -1,158 +1,26 @@ |
|||
<p align="center"> |
|||
<img src="https://github.com/mozilla-neutrino/neutrino/raw/logo/neutrino.png" height="150" /> |
|||
</p> |
|||
<h1><p align="center"><a href="http://neutrino.js.org"><img src="https://raw.githubusercontent.com/mozilla-neutrino/neutrino-dev/master/docs/assets/logo.png" height="150"></a></p></h1> |
|||
|
|||
<p align="center">Create and build modern JavaScript applications with zero initial configuration and minimal fuss.</p> |
|||
<p align="center"><a href="https://npmjs.org/package/neutrino"><img src="https://badge.fury.io/js/neutrino.svg"></a> <a href="https://david-dm.org/mozilla-neutrino/neutrino"><img src="https://david-dm.org/mozilla-neutrino/neutrino.svg"></a></p> |
|||
--- |
|||
### Create and build modern JavaScript applications with zero initial configuration |
|||
#### Think Webpack, but with presets. That's Neutrino. |
|||
|
|||
Neutrino is a helper tool which lets you build web and Node.js applications with shared |
|||
configurations. It intends to make the process of initializing and building projects much simpler by |
|||
providing minimal development dependencies. Neutrino uses Webpack to build both web and Node.js |
|||
projects by providing complete build presets which can be shared across targets and projects. You |
|||
can use neutrino base presets to get started building a variety of projects, create your own |
|||
presets by extending the neutrino code presets to be shared across your own projects or even by the |
|||
community. Presets can even be manipulated on a project-by-project basis to handle almost any build |
|||
situation your preset doesn't cover. |
|||
[![NPM version][npm-image]][npm-url] |
|||
|
|||
--- |
|||
|
|||
## Features |
|||
|
|||
- Preset-based Webpack building with development and production support |
|||
- Test web projects with Karma + Mocha, and Node.js projects with Mocha |
|||
|
|||
## Core Presets |
|||
|
|||
- [Web](https://github.com/mozilla-neutrino/neutrino-preset-web): Build modern, generic web applications |
|||
- [Node.js](https://github.com/mozilla-neutrino/neutrino-preset-node): Build modern Node.js applications |
|||
- [React](https://github.com/mozilla-neutrino/neutrino-preset-react): Build React-based web applications |
|||
|
|||
## Requirements |
|||
|
|||
- v3 (latest): Node.js v4+ and yarn |
|||
- v2: Node.js v4+ and npm |
|||
|
|||
## Getting started |
|||
|
|||
Neutrino projects require 2 development dependencies: neutrino itself and a build configuration |
|||
preset. Neutrino provides core presets for building generic web applications, Node.js, or React |
|||
applications. If these presets do not meet your needs, feel free to use a community-provided preset |
|||
or extend one of these presets to meet your needs. |
|||
|
|||
To get started using neutrino in your project, install neutrino and your preset as development |
|||
dependencies. In this example, we want to build a React application: |
|||
|
|||
```sh |
|||
npm install --save-dev neutrino neutrino-preset-react |
|||
``` |
|||
|
|||
With neutrino and your preset in place, modify the `scripts` in your package.json to use |
|||
neutrino for building the project: |
|||
|
|||
```json |
|||
{ |
|||
"scripts": { |
|||
"start": "PORT=3000 neutrino start --preset neutrino-preset-react", |
|||
"test": "neutrino test --preset neutrino-preset-react", |
|||
"build": "neutrino build --preset neutrino-preset-react" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
By default, neutrino preset look for source code in `src/`, and tests in `test/`. Use your npm |
|||
scripts to start building! |
|||
|
|||
```sh |
|||
# Build the application in development mode |
|||
yarn start |
|||
|
|||
# Build the application and run any tests |
|||
yarn test |
|||
|
|||
# Build the application in production mode, outputting content to build/ |
|||
yarn run build |
|||
``` |
|||
|
|||
If you plan to use the same preset across all your script targets, you can add a `config` entry to |
|||
your package.json to specify this: |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"preset": "neutrino-preset-react" |
|||
}, |
|||
"scripts": { |
|||
"start": "PORT=3000 neutrino start", |
|||
"test": "neutrino test", |
|||
"build": "neutrino build" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Overriding presets |
|||
|
|||
Neutrino core presets provide a good baseline for developing a few different types of JavaScript |
|||
applications by providing configuration for Webpack, ESLint, Karma, and Mocha. If you need to modify |
|||
preset configuration, you can `require` the preset in your project and specify a new preset to |
|||
neutrino with the changes. |
|||
|
|||
For example, let's say you have a project using the neutrino `web` preset, but now want to support |
|||
building LESS files. Let's create a new custom preset in your project to handle this, e.g. |
|||
`custom-preset.js`: |
|||
|
|||
```js |
|||
// require the preset to change |
|||
const preset = require('neutrino-preset-web'); |
|||
// also a using helper to deep-copy an object |
|||
const clone = require('lodash.clonedeep'); |
|||
|
|||
// Find the preset's CSS loader |
|||
const cssLoader = preset.module.loaders.find(l => /css/.test(l.test)); |
|||
|
|||
// Make a copy of the loader so we can use it for LESS loading, while still keeping normal |
|||
// CSS loading |
|||
const lessLoader = clone(cssLoader); |
|||
|
|||
// Change the files the loader uses to .less files |
|||
lessLoader.test = /\.less$/; |
|||
|
|||
// Add the less-loader to this loader which handles LESS compilation |
|||
lessLoader.loaders.push(require.resolve('less-loader')); |
|||
|
|||
// Add the new LESS loader to the preset |
|||
preset.module.loaders.push(lessLoader); |
|||
|
|||
// re-export the modified preset |
|||
module.exports = preset; |
|||
``` |
|||
|
|||
Now use your new preset in your package.json scripts: |
|||
|
|||
```json |
|||
{ |
|||
"scripts": { |
|||
"start": "neutrino start -p custom-preset.js" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
# Creating shareable presets |
|||
|
|||
Creating neutrino presets uses the same premise as modifying a preset, but with the addition that |
|||
these can be published to npm and used in numerous projects. See the neutrino core presets for |
|||
examples on how this is accomplished for tips on creating your own presets. |
|||
|
|||
## Contribute |
|||
|
|||
- Issue Tracker: [https://github.com/mozilla-neutrino/neutrino/issues](https://github.com/mozilla-neutrino/neutrino/issues) |
|||
- Source Code: [https://github.com/mozilla-neutrino/neutrino](https://github.com/mozilla-neutrino/neutrino) |
|||
- Code of Conduct: [Adapted from Rust CoC](https://www.rust-lang.org/conduct.html) |
|||
Neutrino is a companion tool which lets you build web and Node.js applications with shared presets or configurations. |
|||
It intends to make the process of initializing and building projects much simpler by providing minimal development |
|||
dependencies. |
|||
|
|||
## Support |
|||
Neutrino uses Webpack to build both web and Node.js projects by providing complete build presets which can be shared |
|||
across targets and projects. You can use Neutrino base presets to get started building a variety of projects, create |
|||
your own presets by extending the Neutrino core ones to be shared across your own projects or even by the community. |
|||
Presets can even be manipulated on a project-by-project basis to handle almost any build situation your preset doesn't |
|||
cover. |
|||
|
|||
If you are having issues, please let us know. |
|||
## Documentation |
|||
|
|||
## License |
|||
See the [Neutrino docs](http://neutrino.js.org/) |
|||
for details on installation, getting started, usage, and customizing. |
|||
|
|||
This project is licensed under the [Mozilla Public License v2.0](https://github.com/mozilla-neutrino/neutrino/blob/master/LICENSE) |
|||
[npm-image]: https://badge.fury.io/js/neutrino.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino |
|||
|
|||
Loading…
Reference in new issue