Skip to main content

Upgrade to Babel 8 (Integration)

Refer plugin developers or integration users to this document when upgrading to Babel 8.


Check out the v8-migration guide for other user-level changes.

AST Changes


  • Dynamic import() is parsed as an ImportExpression (#15682, #16114).

    // Example input
    import("foo", options);

    // AST in Babel 7
    type: "CallExpression",
    callee: { type: "Import" },
    arguments: [

    // AST in Babel 8
    type: "ImportExpression",
    source: StringLitera("foo"),
    options: Identifier("options")

    Migration: You are encouraged to test your Babel plugins with the new AST, starting from v7.23.0, specifying { parserOpts: { createImportExpressions: true } } in the Babel config. For end users utilizing Babel plugins that rely on the legacy import() AST, it is possible to set createImportExpressions to false. Note that the Babel 7 import() AST is now considered deprecated, it does not support new ES features such as Source Phrase Imports. We will remove the createImportExpressions parser option in Babel 9.

  • Use an identifier for (#12829).

    For a TS type parameter node, is a string in Babel 7 while in Babel 8 it is an Identifier.

    // T is a TSTypeParameter
    function process<T>(input: T): T {}

    Migration: If you have a customized plugin accessing the name of a type parameter node, use in Babel 8.

  • Rename parameters to params, typeAnnotation to returnType for TSCallSignatureDeclaration, TSConstructSignatureDeclaration, TSFunctionType, TSConstructorType and TSMethodSignature (#9231, #13709)

    interface Foo {
    // TSCallSignatureDeclaration
    <T>(): string;

    // TSMethodSignature
    foo<T>(): string;

    // TSConstructSignatureDeclaration
    new <T>(): string;

    // TSFunctionType
    type Bar = <T>() => string;

    // TSConstructorType
    type Baz = new <T>() => string;

    Migration: If you have a customized plugin accessing properties of these TS nodes, make adjustments accordingly:

    • For node.parameters in Babel 7, use node.params in Babel 8
    • For node.typeAnnotation in Babel 7, use node.returnType in Babel 8


  • Don't generate TSParenthesizedType unless createParenthesizedExpression is enabled(#9546, #12608)

    type T = ({});
    // createParenthesizedExpression: true
    TSParenthesizedType { typeAnnotation: TSTypeLiteral { members: [] } }
    // createParenthesizedExpression: false
    TSTypeLiteral { members: [] }

    Migration: If you need informations about parentheses, specify the createParenthesizedExpression parser option.

    { "parserOpts": { "createParenthesizedExpression": true } }

    When createParenthesizedExpression is false, you can also use node.extra.parenthesized to detect whether node is wrapped in parentheses.

API Changes

All packages


  • Disallow importing internal files (#14013, #14179).

    Migration: Use the exported API only. If you are relying on Babel internals, please open an issue and let us know.



  • Disallow using babel.transform, babel.transformFile, babel.transformFromAst, babel.parse, babel.loadOptions, babel.loadPartialConfig and babel.createConfigItem synchronously (#11110, #12695, #15869).

    Migration: The API above require a callback argument. If you are not providing a callback, please use their sync versions: babel.transformSync, babel.transformFileSync, babel.transformFromAstSync, babel.parseSync, babel.loadOptionsSync, babel.loadPartialConfigSync and babel.createConfigItemSync.



  • Remove CodeGenerator class (#16126)

    Migration: In Babel 8 the undocumented CodeGenerator class has been removed, please use the default exported generate function instead.

    - new CodeGenerator(ast).generate()
    + generate(ast)



  • Reject invalid identifier names in t.identifier builder (#10917).

    // Empty string is an invalid identifier name

    Migration: Call t.identifier with a valid name.

  • Remove Super from the Expression alias (#14750).

    A Super node represents super in super call super() and super property super can not be a standalone expression. In other words, t.isExpression(t.super()) will return false in Babel 8.

    Migration: Search usage of t.isExpression, t.assertsExpression and Expression alias in the plugin visitor, and if necessary, update the usage when you are handling super call and super property. For example,

    // Add `.foo` to an expression
    - if (t.isExpression(path.node)) {
    + if (t.isExpression(path.node) || t.isSuper(path.node)) {

    You don't have to update the usage if super() and is not involved:

    // define an expression as a computed key of `foo`
    if (t.isExpression(path.node)) {
    // `super` can not be a computed key, so we don't update `isExpression`
    /* computed */ true


  • Remove t.jSX* and t.tS* builder aliases (#6989, #15527)

    Migration: Use t.jsx* and t.ts* instead. For example, replace t.jSXIdentifier("foo") with t.jsxIdentifier("foo").

  • Remove selfClosing argument from t.jsxElement (#14464)

    - t.jsxElement(openingElement, closingElement, children, selfClosing?: boolean)
    + t.jsxElement(openingElement, closingElement, children)

    Migration: The selfClosing argument was already not used in the builder. You can safely remove it.

  • Remove optional argument from t.memberExpression (#13407)

    - t.memberExpression(object, property, computed, optional?: boolean)
    + t.memberExpression(object, property, computed)

    Migration: The optional argument was already not used in the builder. You can safely remove it.

  • Remove the Noop node type (#12361)

    Migration: The Noop node is not used. If you are depending on the Noop node, please open an issue and talk about your use case.

  • Initialize indexers, callProperties and internalSlots in the node ObjectTypeAnnotation as an empty array in t.objectTypeAnnotation (#14465)

    Migration: In Babel 7 the builder t.objectTypeAnnotation initializes them as null, this is inconsistent with how @babel/parser will parse the Flow object type annotations. In Babel 8 the new default value [] matches the parser behaviour. Adapt to the new default value if you are depending on this.

  • Reject negative and NaN/infinite numbers from t.numericLiteral (#15802)

    // NumericLiterals must be non-negative finite numbers.

    Migration: Babel 7 silently ignores such invalid usage. Use t.valueToNode(-1) instead.



  • Align Babel parser error codes between Flow and TypeScript (#13294)

    Migration: The error.code for OptionalBindingPattern is renamed as PatternIsOptional.

  • Remove updateContext field from tokens[].type returned from option tokens: true (#13768)

    import { parse } from "@babel/parser";

    const { tokens } = parse("a = 42", { tokens: true });
    // Babel 7
    // { label: "name", updateContext: null, ...other properties }
    // Babel 8
    // { label: "name", ... other properties }

    Migration: This change probably won't affect your integration. The tokens[].type is an object storing meta information of a token as implementation details.

  • Tokenize private name #priv as a single privateName token (#13256)

    This change will affect your integration only when you are using tokens: true and are depending on the extra tokens AST output.

    import { parse } from "@babel/parser";

    const { tokens } = parse("class C { #priv }", { tokens: true });
    tokens.filter(t => t.start >= 10 && t.end <= 15) // get tokens for `#priv`
    // Babel 7
    // [
    // Token (#) { value: "#", start: 10, end: 11 },
    // Token (name) { value: "priv", start: 11, end: 15 }
    // ]
    // Babel 8
    // [
    // Token (privateName) { value: "priv", start: 10, end: 15 }
    // ]

    Migration: Adapt to the new privateName token. If you want to restore to the Babel 7 behaviour, manually process the privateName token into the # token and the name token (example).

  • Tokenize string template as templateNonTail and templateTail (#13919)

    This change will affect your integration only when you are using tokens: true and are depending on the extra tokens AST output.

    import { parse } from "@babel/parser";

    const { tokens } = parse("`head${x}middle${y}tail`", { tokens: true });
    console.log(tokens); // print tokens
    // Babel 7
    // [
    // Token (`),
    // Token (template) { value: "head" }, Token (${),
    // Token (name) { value: "x" }, Token (}),
    // Token (template) { value: "middle" }, Token (${),
    // Token (name) { value: "y" }, Token (}),
    // Token (template) { value: "tail" }
    // Token (`)
    // ]
    // Babel 8
    // [
    // Token (templateNonTail) { value: "head" },
    // Token (name) { value: "x" },
    // Token (templateNonTail) { value: "middle" },
    // Token (name) { value: "y" },
    // Token (templateTail) { value: "tail" }
    // ]

    Migration: Adapt to the new token design. If you want to restore to the Babel 7 behaviour, manually transform them to the Babel 7 tokens (example).



  • Remove block argument from Scope#rename (#15288)

    - rename(oldName: string, newName?: string, block?: t.Pattern | t.Scopable)
    + rename(oldName: string, newName?: string)

    Migration: In Babel 8 the third argument block is not used by the method. Consider remove it if you are depending on Scope#rename.

  • Allow skipped NodePaths to be requeued (#13291)

    Notes: NodePath#requeue() can requeue a skipped NodePath. This is actually a bugfix, but it causes an infinite loop in the tdz implementation of @babel/plugin-transform-block-scoping in Babel 7. So it may break other plugins as well.

    Migration: Adapt to the new behaviour. You can use NodePath#shouldSkip to check whether a NodePath has been skipped before calling NodePath#requeue().



  • Remove ios_saf from data/native-modules.json (#15068)

    Migration: Use ios instead.

  • Rename stage 4 plugin entries from proposal-* to transform-* in plugins.json (#14976)

    Migration: For example, use transform-class-properties rather than proposal-class-properties. For a complete list of renamed plugin, see Packages Renames section of Babel 8 migration.



  • The default named exports has been removed (#14180)

    Migration: This change has no effect if you are using the plugin in your ESLint config. However, if you are extending @babel/eslint-plugin, ensure that you obtain exports from require("@babel/eslint-plugin") rather than require("@babel/eslint-plugin").default.

    // Don't add `.default` after `require()`
    const { rules, rulesConfig } = require("@babel/eslint-plugin")



  • isRequired will not accept renamed proposal- queries (#14976)

    module.exports = api => {
    const targets = api.targets();
    // The targets have native optional chaining support
    // if `transform-optional-chaining` is _not_ required
    const optionalChainingSupported = !isRequired(
    - "proposal-optional-chaining",
    + "transform-optional-chaining",

    Migration: Use the transform-* plugin name if the plugin is listed in the Packages Renames section of Babel 8 migration.



  • Remove named export environmentVisitor (#15550)

    Migration: Import it from @babel/helper-environment-visitor.

    - import { environmentVisitor } from "@babel/helper-replace-supers";
    + import environmentVisitor from `@babel/helper-environment-visitor`;
  • Remove named export skipAllButComputedKey (#15550)

    Migration: Use requeueComputedKeyAndDecorators instead. Find and replace the following import and usage

    import { skipAllButComputedKey } from "@babel/helper-replace-supers";


    import { requeueComputedKeyAndDecorators } from `@babel/helper-environment-visitor`;



  • Remove the the third parameter includeUpdateExpression from the default export (#15550)

    This change probabaly won't break your integration as includeUpdateExpression defaults to true in Babel 7. If you are using includeUpdateExpression: false, adapt to the new behaviour.



Plugin changes


  • Remove getModuleName from plugin pass (#12724)

    Migration: Use .file.getModuleName instead. For example,

    module.exports = {
    name: "my-babel-plugin",
    visitor: {
    Identifier(path, pass) {
    - const moduleName = pass.getModuleName();
    + const moduleName = pass.file.getModuleName();


  • Remove addImport from plugin pass (#15576)

    Migration: This change probably will not affect your plugin as this method is already throwing an error in Babel 7. Use addNamed or addDefault from @babel/helper-module-imports instead.

  • Stop supporting fields as named exports (#15576)

    Migration: This change disallows plugins declared from named exports, for example,

    legacy-babel-plugin.js = "legacy-babel-plugin";
    exports.visitor = {
    Identifier() {}

    find such patterns and migrate to the following patterns.

    module.exports = {
    name: "babel-plugin",
    visitor: {
    Identifier() {}