Question

• Primary options

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

  cwd

  Type: string
  Default: process.cwd()
  

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

  caller

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

  Utilities may pass a caller object to identify themselves to Babel and pass capability-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 when the filename is unknown, because a subset of options rely on the filename for 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 filenameRelative

    Type: string
    Default: path.relative(opts.cwd, opts.filename) (if code

    Type: boolean
    Default: true
    

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

    ast

    Type: boolean
    Default: false
    

    Babel's default is to generate a string and a sourcemap, but in some contexts it can be useful to get the AST itself. The primary use case for this would 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 need it and because we'd like to eventually add a caching layer to Babel. Having to cache the AST structure will take significantly more space.

    Config Loading options

    Loading configuration can get a little complex as environments can have several types of configuration files, and those configuration files can have various nested configuration objects that apply depending on the configuration.

    root

    Type: string
    Default: opts.cwd
    Placement: Only allowed in Babel's programmatic options
    

    The initial path that will be processed based on the rootMode

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

    This option, combined with the envName

    Type: string
    Default: 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 value is used as the key when resolving configFile

    Type: string | boolean
    Default: path.resolve(opts.root, "babel.config.js"), if it exists, false otherwise
    Placement: Only allowed in Babel's programmatic options
    

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

    NOTE: This option does not affect loading of .babelrc files, so while it may be tempting to do configFile: "./foo/.babelrc", it is not recommended. If the given .babelrc is loaded via the standard file-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 a naming scheme that is independent of the "babelrc" name.

    babelrc

    Type: boolean
    Default: true as long as the filename option has been specified
    Placement: Allowed in Babel's programmatic options, or inside of the loaded babelrcRoots

    Type: boolean | MatchPattern | Array<MatchPattern>
    Default: opts.root
    Placement: 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 files within the Plugin and Preset options

    plugins

    Type: Array<PluginEntry | Plugin> (presets

    Type: Array<PresetEntry> (passPerPreset

    Type: boolean
    Default: false
    Status: Deprecated
    

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

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

    Config https://www.babeljs.cn/docs/Merging options

    extends

    Type: string
    Placement: Not allowed inside of presets
    

    Configs may "extend" other configuration files. Config fields in the current config will be 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 enabled if the envKey matches the envName option.

    Note: env[envKey] options will be 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 test

    Type: MatchPattern | Array<MatchPattern> (include

    Type: MatchPattern | Array<MatchPattern> (exclude

    Type: MatchPattern | Array<MatchPattern> (ignore

    Type: Array<MatchPattern> (only

    Type: Array<MatchPattern> (Source Map options

    inputSourceMap

    Type: boolean | SourceMap
    Default: true
    

    true will attempt to load an input sourcemap from the file itself, if it contains a //# sourceMappingURL=... comment. If no map is found, or the map 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 use true 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: string
    Default: 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 to false matches because it's perfectly valid to have a module file that does not use import/export statements.

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

    For instance, @babel/plugin-transform-runtime relies on the type of the current document to decide whether to insert an import declaration, or a require() call. @babel/preset-env also does the same for its "useBuiltIns" option. Since Babel defaults to treating files are ES modules, generally these plugins/presets will insert import statements. Setting the correct sourceType can be important because having the wrong type can lead to cases where Babel would insert import statements into files that are meant to be CommonJS files. This can be particularly important in projects where compilation of node_modules dependencies is being performed, because inserting an import statements can cause Webpack and other tooling to see a file as 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 currently hard-coded to always parse as "module" files.

    highlightCode

    Type: boolean
    Default: 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 visitor process 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 function after 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: boolean
    Default: false
    

    Babel will make an effort to generate code such that items are printed on the same line that they were on in the original file. This option exists so that users 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 in compact mode.

    minified

    Type: boolean
    Default: false
    

    Includes compact: true, omits block-end semicolons, omits () from new 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 were not present in the original file.

    Note: The definition of what is and isn't present in the original file can get a little ugly, so usage of this option is not recommended. If you need to annotate 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 were not present in the original file.

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

    comments

    Type: boolean
    Default: true
    

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

    shouldPrintComment

    Type: (value: string) => boolean
    Default 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 the output code from Babel.

    AMD / UMD / SystemJS module options

    moduleIds

    Type: boolean
    Default: !!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. Returning a falsy value will use the original name.

    moduleRoot

    Type: string
    

    A root path to include on generated module names.

    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, these options 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 or parent 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 path RegExp 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 should return a boolean to indicate whether it is a match or not. The function is passed the filename or undefined if one was not given to Babel. It is also passed the current envName and callee options that were specified by the top-level call to Babel.

    https://www.babeljs.cn/docs/Merging

    Babel's configuration merging is relatively straightforward. Options will overwrite existing options when 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 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

    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 one a 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 different name, 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 EntryOptions

      Type: undefined | {} | false

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

      false indicates that an entry is entirely disabled. This can be useful in contexts where ordering is 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 prefixes when 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:

      Input	Normalized
      "/dir/plugin.js"	"/dir/plugin.js"
      "./dir/plugin.js"	"./dir/plugin.js"
      "mod"	"babel-plugin-mod"
      "mod/plugin"	"mod/plugin"
      "babel-plugin-mod"	"babel-plugin-mod"
      "@babel/mod"	"@babel/plugin-mod"
      "@babel/plugin-mod"	"@babel/plugin-mod"
      "@babel/mod/plugin"	"@babel/mod/plugin"
      "@scope"	"@scope/babel-plugin"
      "@scope/babel-plugin"	"@scope/babel-plugin"
      "@scope/mod"	"@scope/babel-plugin-mod"
      "@scope/babel-plugin-mod"	"@scope/babel-plugin-mod"
      "@scope/prefix-babel-plugin-mod"	"@scope/prefix-babel-plugin-mod"
      "@scope/mod/plugin"	"@scope/mod/plugin"
      "module:foo"	"foo"