Configure Babel
All Babel API options are allowed. However, if the option requires JavaScript, you may want to use a JavaScript .
- You are using a monorepo?
- You want to compile
node_modules
?
- You have a configuration that only applies to a single part of your project?
- Guy Fieri is your hero?
Create a file called babel.config.json
with the following content at the root of your project (where the package.json
is).
module.exports = function (api) {
api.cache(true);
const presets = [ ... ];
const plugins = [ ... ];
return {
presets,
plugins
};
}
Check out the babel.config.json documentation to see more configuration options.
Create a file called .babelrc.json
with the following content in your project.
{
"presets": [...],
"plugins": [...]
}
Check out the to see more configuration options.
Alternatively, you can choose to specify your .babelrc.json config from within package.json
using the babel
key like so:
{
"name": "my-package",
"version": "1.0.0",
"babel": {
"presets": [ ... ],
"plugins": [ ... ],
}
}
const presets = [ ... ];
const plugins = [ ... ];
module.exports = { presets, plugins };
You are allowed to access any Node.js APIs, for example a dynamic configuration based on the process environment:
const presets = [ ... ];
const plugins = [ ... ];
if (process.env["ENV"] === "prod") {
plugins.push(...);
}
module.exports = { presets, plugins };
You can read more about JavaScript configuration files in the
Check out the babel-cli documentation to see more configuration options.
require("@babel/core").transformSync("code", {
plugins: ["@babel/plugin-transform-arrow-functions"],
});
Check out the to see more configuration options.
You can tell Babel to print effective configs on a given input path
# *nix or WSL
BABEL_SHOW_CONFIG_FOR=./src/myComponent.jsx npm start
$env:BABEL_SHOW_CONFIG_FOR = ".\src\myComponent.jsx"; npm start
BABEL_SHOW_CONFIG_FOR
accepts both absolute and relative file paths. If it is a relative path, it will be resolved from cwd.
Once Babel processes the input file specified by BABEL_SHOW_CONFIG_FOR
, Babel will print effective configs to the console. Here is an example output:
Babel configs on "/path/to/cwd/src/index.js" (ascending priority):
config /path/to/cwd/babel.config.json
{
"sourceType": "script",
"plugins": [
"@foo/babel-plugin-1"
],
"extends": "./my-extended.js"
}
config /path/to/cwd/babel.config.json .env["test"]
{
"plugins": [
[
"@foo/babel-plugin-3",
{
"noDocumentAll": true
},
]
]
}
config /path/to/cwd/babel.config.json .overrides[0]
{
"test": "src/index.js",
}
config /path/to/cwd/.babelrc
{}
programmatic options from @babel/cli
{
"sourceFileName": "./src/index.js",
"presets": [
"@babel/preset-env"
],
"configFile": "./my-config.js",
"caller": {
},
"filename": "./src/index.js"
}
Babel will print effective config sources ordered by ascending priority. Using the example above, the priority is:
babel.config.json < .babelrc < programmatic options from @babel/cli
In other words, babel.config.json
is overwritten by .babelrc
, and .babelrc
is overwritten by programmatic options.
If your input is ignored by ignore
or only
, Babel will print that this file is ignored.
Babel’s configuration merging is relatively straightforward. Options will overwrite existing options when they are present and their value is not undefined
. There are, however, a few special cases:
- For
assumptions
,parserOpts
andgeneratorOpts
, objects are merged, rather than replaced. - For
plugins
andpresets
, they are replaced based on the identity of the plugin/preset object/function itself combined with the name of the entry.
Option (except plugin/preset) merging
As an example, consider a config with:
When NODE_ENV
is test
, the sourceType
option will be replaced and the assumptions
option will be merged. The effective config is:
{
sourceType: "module", // sourceType: "script" is overwritten
assumptions: {
setClassFields: true,
iterableIsArray: true, // assumptions are merged by Object.assign
},
}
Plugin/Preset merging
As an example, consider a config with:
plugins: [
'./other',
['./plug', { thing: true, field1: true }]
],
overrides: [{
plugins: [
['./plug', { thing: false, field2: true }],
]
}]
The overrides
item will be merged on top of the top-level options. Importantly, the plugins
array as a whole doesn’t just replace the top-level one. The merging logic will see that "./plug"
is the same plugin in both cases, and { thing: false, field2: true }
will replace the original options, resulting in a config as
plugins: [
'./other',
['./plug', { thing: false, field2: true }],
],
Since merging is based on identity + name, it is considered an error to use the same plugin with the same name twice in the same plugins
/presets
array. For example
is considered an error, because it’s identical to . Additionally, even
plugins: [["./plug", { one: true }], ["./plug", { two: true }]];
is considered an error, because the second one would just always replace the first one.
because each instance has been given a unique name and thus a unique identity.