Neutrino Compile Loader Middleware
@neutrinojs/compile-loader
is Neutrino middleware for compiling source code
with Babel.
Requirements
- Node.js 10+
- Yarn v1.2.1+, or npm v5.4+
- Neutrino 9
- webpack 4
Installation
@neutrinojs/compile-loader
can be installed via the Yarn or npm clients.
Yarn
❯ yarn add --dev @neutrinojs/compile-loader
npm
❯ npm install --save-dev @neutrinojs/compile-loader
Usage
@neutrinojs/compile-loader
can be consumed from the Neutrino API, middleware,
or presets. Require this package and plug it into Neutrino:
const compileLoader = require('@neutrinojs/compile-loader');
neutrino.use(
compileLoader({
test: neutrino.regexFromExtensions(),
include: [],
exclude: [],
babel: {},
ruleId: 'compile',
useId: 'babel',
}),
);
const compileLoader = require('@neutrinojs/compile-loader');
module.exports = {
use: [
compileLoader({
test: neutrino.regexFromExtensions(),
include: [],
exclude: [],
babel: {},
ruleId: 'compile',
useId: 'babel',
}),
],
};
include
should be an array of paths to include in the compilation. Maps to
webpack's
Rule.include
exclude
should be an array of paths to exclude from the compilation. Maps to
webpack's
Rule.exclude
babel
is a Babel configuration object,
consumed by babel-loader. Use this to set properties such as presets
,
plugins
, and env
.ruleId
is the identifier to the compiler loader rule. Override this to add
an additional compile-loader instanceuseId
is the identifier for the babel loader. Override this to change the
identifier.
Merging Babel Configuration
To correctly merge Babel configurations use the
babel-merge package.
const babelMerge = require('babel-merge');
const together = babelMerge(
{
presets: [
[
'@babel/preset-env',
{
targets: {
browsers: ['latest 1 Chrome'],
},
},
],
],
},
{
presets: [
[
'@babel/preset-env',
{
targets: {
browsers: ['latest 1 Firefox'],
},
},
],
],
},
);
console.log(together);
{
presets: [
[
'@babel/preset-env',
{
targets: {
browsers: ['latest 1 Chrome', 'latest 1 Firefox'],
},
},
],
];
}
Advanced merging
Should you need to do merging of Babel configuration that is more advanced than
this, such as re-ordering the options, you will need to tap
into the existing
Babel options to do so. This still involves using babel-merge
.
Example: enable current decorator syntax in the compile loader:
const babelMerge = require('babel-merge');
config.module
.rule('compile')
.use('babel')
.tap((options) =>
babelMerge(
{
plugins: [
require.resolve('@babel/plugin-proposal-decorators'),
require.resolve('@babel/plugin-proposal-class-properties'),
],
},
options,
),
);
Compiling node_modules
Neutrino does not compile node_modules
by default, since packages should be
compiling down to ES5 themselves (even when using the module
property in
package.json
) to maximize ecosystem compatibility. If you encounter packages
that need to be compiled from node_modules
, you can write an override after
the inclusion of compile-loader
or a dependent preset:
Example: compile node_modules
after including React preset.
const react = require('@neutrinojs/react');
const { join } = require('path');
module.exports = {
use: [
react(),
(neutrino) => {
neutrino.config.module
.rule('compile')
.include.add(join(__dirname, 'node_modules'));
},
],
};
babel.config.js
Should you wish to use the Babel configuration outside of webpack, create a
babel.config.js
file in the root of the project, containing the following:
const neutrino = require('neutrino');
module.exports = neutrino().babel();
Customization
@neutrinojs/compile-loader
creates some conventions to make overriding the
configuration easier once you are ready to make changes.
Rules
The following is a list of rules and their identifiers which can be overridden:
Name | Description | NODE_ENV |
---|
compile | Compiles JS and JSX files from the src directory using Babel. Contains a single loader named babel . | all |
Contributing
This middleware is part of the
neutrino repository, a monorepo
containing all resources for developing Neutrino and its core presets and
middleware. Follow the
contributing guide for details.