Options

• Primary options
• Config Loading options
• Plugin and Preset configuration
• Config Merging options
• Source Map options
• Misc options
• Code Generator options
• AMD / UMD / SystemJS options
• CLI options
• Option concepts

Options can be passed to Babel in a variety of ways. When passed directly to Babel,you can just pass the objects object. When Babel is used via a wrapper, it may also benecessary, or at least more useful, to pass the options via configuration files.

If passing options via @babel/cli you'll need to kebab-case the names. i.e.

npx babel --root-mode upward file.js # equivalent of passing the rootMode config option

Primary options

These options are only allowed as part of Babel's programmatic options, sothey are primarily for use by tools that wrap around Babel, or people callingbabel.transform directly. Users of Babel's integrations, like babel-loaderor @babel/register are unlikely to use these.

cwd

Type: stringDefault: process.cwd()

The working directory that all paths in the programmatic options will be resolvedrelative to.

caller

Type: Object with a string-typed "name" property.

Utilities may pass a caller object to identify themselves to Babel and passcapability-related flags for use by configs, presets and plugins. For example

babel.transformFileSync("example.js", {
  caller: {
    name: "my-custom-tool",
    supportsStaticESM: true
  },
})

would allow plugins and presets to decide that, since ES modules are supported,they will skip compilation of ES modules into CommonJS modules.

filename

Type: string

The filename associated with the code currently being compiled, if there is one.The filename is optional, but not all of Babel's functionality is available whenthe filename is unknown, because a subset of options rely on the filenamefor their functionality.

The three primary cases users could run into are:

• The filename is exposed to plugins. Some plugins may require the presence of the filename.
• Options like "test", "exclude", and "ignore" require the filename for string/RegExp matching.
• .babelrc.json files are loaded relative to the file being compiled. If this option is omitted, Babel will behave as if babelrc: false has been set.

filenameRelative

Type: stringDefault: path.relative(opts.cwd, opts.filename) (if "filename" was passed)

Used as the default value for Babel's sourceFileName option, and usedas part of generation of filenames for the AMD / UMD / SystemJS module transforms.

code

Type: booleanDefault: true

Babel's default return value includes code and map properties with theresulting generated code. In some contexts where multiple calls to Babelare being made, it can be helpful to disable code generation and insteaduse ast: true to get the AST directly in order to avoid doing unnecessary work.

ast

Type: booleanDefault: false

Babel's default is to generate a string and a sourcemap, but in somecontexts it can be useful to get the AST itself. The primary use case for thiswould be a chain of multiple transform passes, along the lines of

const filename = "example.js";
const source = fs.readFileSync(filename, "utf8");
// Load and compile file normally, but skip code generation.
const { ast } = babel.transformSync(source, { filename, ast: true, code: false });
// Minify the file in a second pass and generate the output code here.
const { code, map } = babel.transformFromAstSync(ast, source, {
  filename,
  presets: ["minify"],
  babelrc: false,
  configFile: false,
});

Note: This option is not on by default because the majority of users won't needit and because we'd like to eventually add a caching layer to Babel. Havingto cache the AST structure will take significantly more space.

Config Loading options

Loading configuration can get a little complex as environments can have severaltypes of configuration files, and those configuration files can have variousnested configuration objects that apply depending on the configuration.

root

Type: stringDefault: opts.cwdPlacement: Only allowed in Babel's programmatic options

The initial path that will be processed based on the "rootMode"to determine the conceptual root folder for the current Babel project.This is used in two primary cases:

• The base directory when checking for the default "configFile" value
• The default value for "babelrcRoots".

rootMode

Type: "root" | "upward" | "upward-optional"Default: "root"Placement: Only allowed in Babel's programmatic optionsVersion: ^7.1.0

This option, combined with the "root" value, defines how Babelchooses its project root. The different modes define different ways thatBabel can process the "root" value to get the final project root.

• "root" - Passes the "root" value through as unchanged.
• "upward" - Walks upward from the "root" directory, lookingfor a directory containing a babel.config.jsonfile, and throws an error if a babel.config.jsonis not found.
• "upward-optional" - Walk upward from the "root" directory,looking for a directory containing a babel.config.jsonfile, and falls back to "root" if a babel.config.jsonis not found.

"root" is the default mode because it avoids the risk that Babel willaccidentally load a babel.config.json that is entirely outside of the currentproject folder. If you use "upward-optional", be aware that it will walk up thedirectory structure all the way to the filesystem root, and it is alwayspossible that someone will have a forgotten babel.config.json in their homedirectory, which could cause unexpected errors in your builds.

Users with monorepo project structures that run builds/tests on a per-package basismay well want to use "upward" since monorepos often have a babel.config.jsonin the project root. Running Babel in a monorepo subdirectory without "upward",will cause Babel to skip loading any babel.config.jsonfiles in the project root, which can lead to unexpected errors and compilation failure.

envName

Type: stringDefault: process.env.BABEL_ENV || process.env.NODE_ENV || "development"Placement: Only allowed in Babel's programmatic options

The current active environment used during configuration loading. This valueis used as the key when resolving "env" configs, and is alsoavailable inside configuration functions, plugins, and presets, via theapi.env() function.

configFile

Type: string | booleanDefault: path.resolve(opts.root, "babel.config.json"), if it exists, false otherwisePlacement: Only allowed in Babel's programmatic options

Defaults to searching for a default babel.config.json file, but can be passedthe path of any JS or JSON5 config file.

NOTE: This option does not affect loading of .babelrc.json files, so whileit may be tempting to do configFile: "./foo/.babelrc.json", it is not recommended.If the given .babelrc.json is loaded via the standardfile-relative logic, you'll end up loading the same config file twice, merging it with itself.If you are linking a specific config file, it is recommended to stick with anaming scheme that is independent of the "babelrc" name.

babelrc

Type: booleanDefault: true as long as the filename option has been specifiedPlacement: Allowed in Babel's programmatic options, or inside of the loaded "configFile". A programmatic option will override a config file one.

true will enable searching for configuration files relativeto the "filename" provided to Babel.

A babelrc value passed in the programmatic options will override one setwithin a configuration file.

Note: .babelrc.json files are only loaded if the current "filename" is inside ofa package that matches one of the "babelrcRoots" packages.

babelrcRoots

Type: boolean | MatchPattern | Array<MatchPattern>Default: opts.rootPlacement: Allowed in Babel's programmatic options, or inside of the loaded configFile. A programmatic option will override a config file one.

By default, Babel will only search for .babelrc.json files within the "root" packagebecause otherwise Babel cannot know if a given .babelrc.json is meant to be loaded, orif it's "plugins" and "presets" have even been installed, since the file beingcompiled could be inside node_modules, or have been symlinked into the project.

This option allows users to provide a list of other packages that should be considered"root" packages when considering whether to load .babelrc.json files.

For example, a monorepo setup that wishes to allow individual packages tohave their own configs might want to do

babelrcRoots: [
  // Keep the root as a root
  ".",
  // Also consider monorepo packages "root" and load their .babelrc.json files.
  "./packages/*"
]

Plugin and Preset options

plugins

Type: Array<PluginEntry | Plugin> (PluginEntry)Default: []

An array of plugins to activate when processing this file. For more information on howindividual entries interact, especially when used across multiple nested "env" and"overrides" configs, see merging.

Note: The option also allows Plugin instances from Babel itself, butusing these directly is not recommended. If you need to create a persistentrepresentation of a plugin or preset, you should use babel.createConfigItem().

presets

Type: Array<PresetEntry> (PresetEntry)Default: []

An array of presets to activate when processing this file. For more information on howindividual entries interact, especially when used across multiple nested "env" and"overrides" configs, see merging.

Note: The format of presets is identical to plugins, except for the fact thatname normalization expects "preset-" instead of "plugin-", and presets cannotbe instances of Plugin.

passPerPreset

Type: booleanDefault: falseStatus: Deprecated

Instructs Babel to run each of the presets in the presets array as anindependent pass. This option tends to introduce a lot of confusion aroundthe exact ordering of plugins, but can be useful if you absolutely need to runa set of operations as independent compilation passes.

Note: This option may be removed in future Babel versions as we add bettersupport for defining ordering between plugins.

Config Merging options

extends

Type: stringPlacement: Not allowed inside of presets

Configs may "extend" other configuration files. Config fields in the currentconfig will be merged on top of the extended file's configuration.

env

Type: { [envKey: string]: Options }Placement: May not be nested inside of another env block.

Allows for entire nested configuration options that will only be enabledif the envKey matches the envName option.

Note: env[envKey] options will be merged on top of the options specified inthe root object.

overrides

Type: Array<Options>Placement: May not be nested inside of another overrides object, or within an env block.

Allows users to provide an array of options that will be merged into the currentconfiguration one at a time. This feature is best used alongside the "test"/"include"/"exclude"options to provide conditions for which an override should apply. For example:

overrides: [{
  test: "./vendor/large.min.js",
  compact: true,
}],

could be used to enable the compact option for one specific file that is knownto be large and minified, and tell Babel not to bother trying to print the file nicely.

test

Type: MatchPattern | Array<MatchPattern> (MatchPattern)

If all patterns fail to match, the current configuration object is consideredinactive and is ignored during config processing. This option is most usefulwhen used within an overrides option object, but it's allowed anywhere.

Note: These toggles do not affect the programmatic and config-loading optionsin earlier sections, since they are taken into account long before theconfiguration that is prepared for merging.

include

Type: MatchPattern | Array<MatchPattern> (MatchPattern)

This option is a synonym for "test".

exclude

Type: MatchPattern | Array<MatchPattern> (MatchPattern)

If any of patterns match, the current configuration object is consideredinactive and is ignored during config processing. This option is most usefulwhen used within an overrides option object, but it's allowed anywhere.

Note: These toggles do not affect the programmatic and config-loading optionsin earlier sections, since they are taken into account long before theconfiguration that is prepared for merging.

ignore

Type: Array<MatchPattern> (MatchPattern)Placement: Not allowed inside of presets

If any of the patterns match, Babel will immediately stop all processing ofthe current build. For example, a user may want to do something like

ignore: [
  "./lib",
]

to explicitly disable Babel compilation of files inside the lib directory.

Note: This option disables all Babel processing of a file. While that hasits uses, it is also worth considering the "exclude" option as a less aggressivealternative.

only

Type: Array<MatchPattern> (MatchPattern)Placement: Not allowed inside of presets

If all of the patterns fail to match, Babel will immediately stop all processingof the current build. For example, a user may want to do something like

only: [
  "./src",
]

to explicitly enable Babel compilation of files inside the src directorywhile disabling everything else.

Note: This option disables all Babel processing of a file. While that hasits uses, it is also worth considering the "test"/"include"options as a less aggressive alternative.

Source Map options

inputSourceMap

Type: boolean | SourceMapDefault: true

true will attempt to load an input sourcemap from the file itself, if itcontains a //# sourceMappingURL=… comment. If no map is found, or themap fails to load and parse, it will be silently discarded.

If an object is provided, it will be treated as the source map object itself.

sourceMaps

Type: boolean | "inline" | "both"Default: false

• true to generate a sourcemap for the code and include it in the result object.
• "inline" to generate a sourcemap and append it as a data URL to the end of the code, but not include it in the result object.
• "both" is the same as inline, but will include the map in the result object.

@babel/cli overloads some of these to also affect how maps are written to disk:

• true will write the map to a .map file on disk
• "inline" will write the file directly, so it will have a data: containing the map
• "both" will write the file with a data: URL and also a .map.

Note: These options are bit weird, so it may make the most sense to just usetrue and handle the rest in your own code, depending on your use case.

sourceMap

This is an synonym for sourceMaps. Using sourceMaps is recommended.

sourceFileName

Type: stringDefault: path.basename(opts.filenameRelative) when available, or "unknown"

The name to use for the file inside the source map object.

sourceRoot

Type: string

The sourceRoot fields to set in the generated source map, if one is desired.

Misc options

sourceType

Type: "script" | "module" | "unambiguous"Default: "module"

• "script" - Parse the file using the ECMAScript Script grammar. No import/export statements allowed, and files are not in strict mode.
• "module" - Parse the file using the ECMAScript Module grammar. Files are automatically strict, and import/export statements are allowed.
• "unambiguous" - Consider the file a "module" if import/export statements are present, or else consider it a "script".

unambiguous can be quite useful in contexts where the type is unknown, but it can lead tofalse matches because it's perfectly valid to have a module file that does not use import/exportstatements.

This option is important because the type of the current file affects bothparsing of input files, and certain transforms that may wish to addimport/require usage to the current file.

For instance, @babel/plugin-transform-runtimerelies on the type of the current document to decide whether to insertan import declaration, or a require() call.@babel/preset-env also does the same for its"useBuiltIns" option. Since Babel defaults to treating filesare ES modules, generally these plugins/presets will insert import statements. Settingthe correct sourceType can be important because having the wrong type can lead to caseswhere Babel would insert import statements into files that are meant to be CommonJSfiles. This can be particularly important in projects where compilationof node_modules dependencies is being performed, because inserting animport statements can cause Webpack and other tooling to see a fileas an ES module, breaking what would otherwise be a functional CommonJS file.

Note: This option will not affect parsing of .mjs files, as they are currentlyhard-coded to always parse as "module" files.

highlightCode

Type: booleanDefault: true

Highlight tokens in code snippets in Babel's error messages to make them easier to read.

wrapPluginVisitorMethod

Type: (key: string, nodeType: string, fn: Function) => Function

Allows users to add a wrapper on each visitor in order to inspect the visitorprocess as Babel executes the plugins.

• key is a simple opaque string that represents the plugin being executed.
• nodeType is the type of AST node currently being visited.
• fn is the visitor function itself.

Users can return a replacement function that should call the original functionafter performing whatever logging and analysis they wish to do.

parserOpts

Type: {}

An opaque object containing options to pass through to the parser being used.

generatorOpts

Type: {}

An opaque object containing options to pass through to the code generator being used.

Code Generator options

retainLines

Type: booleanDefault: false

Babel will make an effort to generate code such that items are printed on thesame line that they were on in the original file. This option exists so thatusers who cannot use source maps can get vaguely useful error line numbers,but it is only a best-effort, and is not guaranteed in all cases with all plugins.

compact

Type: boolean | "auto"Default: "auto"

"auto" will set the value by evaluating code.length > 500_000

All optional newlines and whitespace will be omitted when generating code incompact mode.

minified

Type: booleanDefault: false

Includes compact: true, omits block-end semicolons, omits () fromnew Foo() when possible, and may output shorter versions of literals.

auxiliaryCommentBefore

Type: string

Allows specifying a prefix comment to insert before pieces of code that werenot present in the original file.

Note: The definition of what is and isn't present in the original file canget a little ugly, so usage of this option is not recommended. If you need toannotate code somehow, it is better to do so using a Babel plugin.

auxiliaryCommentAfter

Type: string

Allows specifying a prefix comment to insert after pieces of code that werenot present in the original file.

Note: The definition of what is and isn't present in the original file canget a little ugly, so usage of this option is not recommended. If you need toannotate code somehow, it is better to do so using a Babel plugin.

comments

Type: booleanDefault: true

Provides a default comment state for shouldPrintComment if no functionis given. See the default value of that option for more info.

shouldPrintComment

Type: (value: string) => booleanDefault without minified: (val) => opts.comments || /@license|@preserve/.test(val)Default with minified: () => opts.comments

A function that can decide whether a given comment should be included in theoutput code from Babel.

AMD / UMD / SystemJS module options

moduleIds

Type: booleanDefault: !!opts.moduleId

Enables module ID generation.

moduleId

Type: string

A hard-coded ID to use for the module. Cannot be used alongside getModuleId.

getModuleId

Type: (name: string) => string

Given the babel-generated module name, return the name to use. Returninga falsy value will use the original name.

moduleRoot

Type: string

A root path to include on generated module names.

CLI options

Copy ignored files

Include ignored files when copying non-compilable files.

npx babel src --out-dir lib --ignore "src/**/*.spec.js" --copy-ignored

Options Concepts

MatchPattern

Type: string | RegExp | (filename: string | void, context: { callee: { name: string } | void, envName: string ) => boolean

Several Babel options perform tests against file paths. In general, theseoptions support a common pattern approach where each pattern can be

• string - A file path with simple support for and * as full slug matches. Any file orparent folder matching the pattern counts as a match. The path follow's Node's normal path logic,so on POSIX is must be /-separated, but on Windows both / and \ are supported.
• RegExp - A regular expression to match against the normalized filename. On POSIX the pathRegExp will run against a /-separated path, and on Windows it will be on a \-separated path.

Importantly, if either of these are used, Babel requires that the filename option be present,and will consider it an error otherwise.

• (filename: string | void, context: { callee: { name: string } | void, envName: string }) => boolean is a general callback that shouldreturn a boolean to indicate whether it is a match or not. The function is passed the filenameor undefined if one was not given to Babel. It is also passed the current envName and calleeoptions that were specified by the top-level call to Babel.

Merging

Babel's configuration merging is relatively straightforward. Options will overwrite existing optionswhen they are present, and their value is not undefined, with a few special cases:

• parserOpts objects are merged, rather than replaced, using the same logic as top-level options.
• generatorOpts objects are merged, rather than replaced, using the same logic as top-level options.
• plugins and presets are replaced based on the identity of the plugin/preset object/function itself combined with the name of the entry.

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 plugins. Importantly, the pluginsarray 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 originaloptions, 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 withthe same name twice in the same plugins/presets array. For example

plugins: [
  './plug',
  './plug',
]

is considered an error, because it's identical to plugins: ['./plug']. Additionally, even

plugins: [
  ['./plug', {one: true}],
  ['./plug', {two: true}]
]

is considered an error, because the second one would just always replace the first one.

If you actually do want to instantiate two separate instances of a plugin, you must assign each onea name to disambiguate them. For example:

plugins: [
  ['./plug', {one: true}, "first-instance-name"],
  ['./plug', {two: true}, "second-instance-name"]
]

because each instance has been given a unique name and this a unique identity.

Plugin/Preset entries

PluginEntry / PresetEntry

Individual plugin/preset items can have several different structures:

• EntryTarget - Individual plugin
• [EntryTarget, EntryOptions] - Individual plugin w/ options
• [EntryTarget, EntryOptions, string] - Individual plugin with options and name (see merging for more info on names)
• ConfigItem - A plugin configuration item created by babel.createConfigItem().

The same EntryTarget may be used multiple times unless each one is given a differentname, and doing so will result in a duplicate-plugin/preset error.

That can be a little hard to read, so as an example:

plugins: [
  // EntryTarget
  '@babel/plugin-transform-classes',
  // [EntryTarget, EntryOptions]
  ['@babel/plugin-transform-arrow-functions', { spec: true }],
  // [EntryTarget, EntryOptions, string]
  ['@babel/plugin-transform-for-of', { loose: true }, "some-name"],
  // ConfigItem
  babel.createConfigItem(require("@babel/plugin-transform-spread")),
],

EntryTarget

Type: string | {} | Function

A plugin/preset target can come from a few different sources:

• string - A require-style path or plugin/preset identifier. Identifiers will be passed through name normalization.
• {} | Function - An actual plugin/preset object or function after it has been require()ed.

EntryOptions

Type: undefined | {} | false

Options are passed through to each plugin/preset when they are executed. undefined will benormalized to an empty object.

false indicates that an entry is entirely disabled. This can be useful in contexts where orderingis important, but a separate condition is needed to decide if something is enabled. For instance:

plugins: [
  'one',
  ['two', false],
  'three',
],
overrides: [{
  test: "./src",
  plugins: [
    'two',
  ]
}]

would enable the two plugin for files in src, but two would still execute between one and three.

Name Normalization

By default, Babel expects plugins to have a babel-plugin- or babel-preset- prefix in their name.To avoid repetition, Babel has a name normalization phase will automatically add these prefixeswhen loading items. This boils down to a few primary rules:

• Absolute paths pass through untouched.
• Relative paths starting with ./ pass through untouched.
• References to files within a package are untouched.
• Any identifier prefixed with module: will have the prefix removed but otherwise be untouched.
• plugin-/preset- will be injected at the start of any @babel-scoped package that doesn't have it as a prefix.
• babel-plugin-/babel-preset- will be injected as a prefix any unscoped package that doesn't have it as a prefix.
• babel-plugin-/babel-preset- will be injected as a prefix any @-scoped package that doesn't have it anywhere in their name.
• babel-plugin/babel-preset will be injected as the package name if only the @-scope name is given.

Here are some examples, when applied in a plugin context: