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',
}),
);
// Using in .neutrinorc.js
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'sRule.include
exclude
should be an array of paths to exclude from the compilation. Maps to webpack'sRule.exclude
babel
is a Babel configuration object, consumed by babel-loader. Use this to set properties such aspresets
,plugins
, andenv
.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);
// Logs:
{
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');
// Decorators generally need to be enabled *before* other
// syntax which exists in both normal plugins, and
// development environment plugins.
// Tap into the existing Babel options and merge our
// decorator options *before* the rest of the existing
// Babel options
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.
// .neutrinorc.js
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.