Eli Perelman
8 years ago
11 changed files with 382 additions and 21 deletions
@ -0,0 +1 @@ |
|||
# Neutrino API |
|||
@ -0,0 +1 @@ |
|||
# Neutrino CLI |
|||
@ -0,0 +1,3 @@ |
|||
# Creating Neutrino Presets |
|||
|
|||
## Publishing (npm, GitHub) |
|||
@ -0,0 +1,18 @@ |
|||
# Neutrino Customization |
|||
|
|||
No two JavaScript projects are ever the same, and as such there may be times when you will need to make modifications |
|||
to the way your Neutrino preset is building your project. Neutrino provides two ways you can augment a preset in the |
|||
context of a project without resorting to creating and publishing an entirely independent preset. |
|||
|
|||
### Simple Customization |
|||
|
|||
By defining a configuration object within your package.json, Neutrino will merge this information with that provided by |
|||
your preset, effectively overriding those options with your custom data. |
|||
|
|||
### Advanced Customization |
|||
|
|||
You can also create a configuration override directly in your project which can extend the presets you are using. |
|||
|
|||
--- |
|||
|
|||
Continue for details on each technique. |
|||
@ -0,0 +1,85 @@ |
|||
# Advanced Neutrino Customization |
|||
|
|||
No two JavaScript projects are ever the same, and as such there may be times when you will need to make modifications |
|||
to the way your Neutrino preset is building your project. If you need more customization than can be afforded by |
|||
augmenting your project's package.json, consider using this advanced configuration guide to modify your build as |
|||
needed. |
|||
|
|||
## Creating a project-specific preset |
|||
|
|||
Neutrino configurations are backed by [webpack-chain](https://github.com/mozilla-rpweb/webpack-chain), a library for |
|||
making modifications to a Webpack configuration using a fluent or chained API. When your project needs more advanced |
|||
build overrides, you will be interacting with this API in order to perform modifications. |
|||
|
|||
First, we need to create a project-specific preset to make these changes. This can either be a JS file or a directory |
|||
with an `index.js` file. Since Neutrino uses Node.js and Webpack for interacting with presets, it is helpful to |
|||
understand that this is a Node.js module. By exporting a function from your module, you will be provided with a Neutrino |
|||
instance for modifying the build. Let's create a file called `neutrino-custom.js` in the root of our example project: |
|||
|
|||
```js |
|||
// neutrino-custom.js |
|||
module.exports = neutrino => { |
|||
// ... |
|||
}; |
|||
``` |
|||
|
|||
At the moment our custom configurator isn't doing anything, but it does get us far enough to be able to tell Neutrino |
|||
to use it for additional configuration. Modify your package.json and add `neutrino-custom.js` as an additional preset. |
|||
|
|||
_Note: Neutrino will attempt to load this module relative to the current working directory, which should be the root of |
|||
your project._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"presets": [ |
|||
"neutrino-preset-react", |
|||
"neutrino-preset-karma", |
|||
"neutrino-custom.js" |
|||
] |
|||
}, |
|||
"scripts": { |
|||
"build": "neutrino build" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Other than actually changing the config, that is all the setup necessary for Neutrino to pick up your custom changes. |
|||
|
|||
## Configuring |
|||
|
|||
The Neutrino instance provided to your custom configurator has a `config` property that is an instance of |
|||
[webpack-chain](https://github.com/mozilla-rpweb/webpack-chain). We won't go in-depth of all the configuration |
|||
possibilities here, but encourage you to check out the documentation for webpack-chain for instruction on your |
|||
particular use case. |
|||
|
|||
This `neutrino.config` is an accumulation of all configuration set up to this moment. Every Neutrino preset interacts |
|||
with and makes changes through this config, which is all available to you. For example, if you are using the presets |
|||
`neutrino-preset-react` and `neutrino-preset-karma`, any options set can be extended, manipulated, or removed. |
|||
|
|||
_Example: Neutrino's React preset adds `.jsx` as a module extension. Let's remove it._ |
|||
|
|||
```js |
|||
module.exports = neutrino => { |
|||
neutrino.config.resolve.extensions.delete('.jsx'); |
|||
}; |
|||
``` |
|||
|
|||
_Example: Neutrino's Node.js preset uses `babel-preset-env` to support Node.js v6.9. Let's change it to support back to |
|||
v4.2. This preset has a rule named "compile" and a loader named "babel"._ |
|||
|
|||
```js |
|||
module.exports = neutrino => { |
|||
neutrino.config.module |
|||
.rule('compile') |
|||
.loader('babel', ({ options }) => { |
|||
options.presets[0][1].targets.node = 4.2; |
|||
|
|||
return { options }; |
|||
}); |
|||
}; |
|||
``` |
|||
|
|||
Presets can also have their own custom data in addition to the Neutrino config. See your respective preset for details. |
|||
Again, rather than reiterate the documentation for [webpack-chain](https://github.com/mozilla-rpweb/webpack-chain) here, |
|||
please refer to its documentation for all ways you can modify a config instance to solve your use cases. |
|||
@ -0,0 +1,238 @@ |
|||
# Simple Neutrino Customization |
|||
|
|||
No two JavaScript projects are ever the same, and as such there may be times when you will need to make modifications |
|||
to the way your Neutrino preset is building your project. By defining a configuration object within your package.json, |
|||
Neutrino will merge this information with that provided by your preset, effectively overriding those options with your |
|||
custom data. |
|||
|
|||
## Prepare package.json |
|||
|
|||
First, you will need to define a `config` section within your package.json. You |
|||
[may have already done this](/usage.md#using-multiple-presets) if you |
|||
specified your presets through the `config` as opposed to flags through `scripts`: |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"presets": [ |
|||
"neutrino-preset-react", |
|||
"neutrino-preset-karma" |
|||
] |
|||
}, |
|||
"scripts": { |
|||
"start": "neutrino start", |
|||
"build": "neutrino build" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Add a new property to `config` named `neutrino`. This will be an object where we can provide configuration data: |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"presets": [], |
|||
"neutrino": { |
|||
|
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Populate this object with configuration overrides. This is not a Webpack configuration, but rather a Neutrino-compatible |
|||
object based on [webpack-chain](https://github.com/mozilla-rpweb/webpack-chain). |
|||
|
|||
## Usage |
|||
|
|||
### Entries |
|||
|
|||
Add files to named entry points, or define new entry points. This is a key named `entry`, with a value being an object. |
|||
This maps to points to enter the application. At this point the application starts executing. |
|||
|
|||
_Example: Define an entry point named `vendor` that bundles React packages separately from the application code._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"entry": { |
|||
"vendor": [ |
|||
"react", |
|||
"react-dom", |
|||
"react-hot-loader", |
|||
"react-router-dom" |
|||
] |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Module |
|||
|
|||
The `module` object defines how the different types of modules within a project will be treated. Any additional |
|||
properties attached to `module` not defined below will be set on the final module configuration. |
|||
|
|||
#### Module Rules |
|||
|
|||
Using `module.rule` creates rules that are matched to requests when modules are created. These rules can modify how the |
|||
module is created. They can apply loaders to the module, or modify the parser. |
|||
|
|||
Using `module.rule.loader` allows to you define the Webpack loader and its options for processing a particular rule. |
|||
This loader is usually a `dependency` or `devDependency` of your project. Each `loader` object can specify a property |
|||
for the string `loader` and an `options` object. |
|||
|
|||
_Example: Add LESS loading to the project._ |
|||
|
|||
```json |
|||
{ |
|||
"dependencies": { |
|||
"less": "^2.7.2", |
|||
"less-loader": "^2.2.3" |
|||
}, |
|||
"config": { |
|||
"neutrino": { |
|||
"module": { |
|||
"rule": { |
|||
"styles": { |
|||
"test": "/\\.less$/", |
|||
"loader": { |
|||
"less": { |
|||
"loader": "less-loader", |
|||
"options": { |
|||
"noIeCompat": true |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Output |
|||
|
|||
The `output` object contains a set of options instructing Webpack on how and where it should output your bundles, |
|||
assets, and anything else you bundle or load with Webpack. This option can be any property/value combination that |
|||
[Webpack accepts](https://webpack.js.org/configuration/output/). |
|||
|
|||
_Example: Change the public path of the application._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"output": { |
|||
"publicPath": "https://cdn.example.com/assets/" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Node |
|||
|
|||
Use `node` to customize the Node.js environment using polyfills or mocks: |
|||
|
|||
_Example: mock the `__filename` and `__dirname` Node.js globals._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"node": { |
|||
"__filename": "mock", |
|||
"__dirname": "mock" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### DevServer |
|||
|
|||
Use `devServer` to customize webpack-dev-server and change its behavior in various ways. |
|||
|
|||
_Example: gzip the application when serving and listen on port 9000._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"devServer": { |
|||
"compress": true, |
|||
"port": 9000 |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Resolve |
|||
|
|||
Use `resolve` to change how modules are resolved. When using `resolve.extensions` and `resolve.modules`, these should be |
|||
specified as arrays, and will be merged with their respective definitions used in inherited presets. Any additional |
|||
properties attached to `resolve` not defined below will be set on the final module configuration. |
|||
|
|||
_Example: Add `.mjs` as a resolving extension and specify modules are located in a `custom_modules` directory._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"resolve": { |
|||
"extensions": [".mjs"], |
|||
"modules": ["custom_modules"] |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### ResolveLoader |
|||
|
|||
Use `resolveLoader` to change how loader packages are resolved. When using `resolveLoader.extensions` and |
|||
`resolveLoader.modules`, these should be specified as arrays, and will be merged with their respective definitions used |
|||
in inherited presets. Any additional properties attached to `resolveLoader` not defined below will be set on the final |
|||
module configuration. |
|||
|
|||
_Example: Add `.loader.js` as a loader extension and specify modules are located in a `web_loaders` directory._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"resolve": { |
|||
"extensions": [".loader.js"], |
|||
"modules": ["web_loaders"] |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Additional configuration |
|||
|
|||
Any top-level properties you set on `config.neutrino` will be added to the configuration. |
|||
|
|||
_Example: Change the Webpack performance options to error when exceeding performance budgets._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"performance": { |
|||
"hints": "error" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Advanced Configuration |
|||
|
|||
With the options defined above in your package.json, you can perform a variety of build customizations on a per-project |
|||
basis. In the event that you need more customization than what is afforded through JSON, consider either switching to |
|||
[advanced configuration](/customization/advanced.md), or [creating your own preset](/creating-presets.md). |
|||
Loading…
Reference in new issue