We plan to release a new major version in 2024 (milestone).

This release won't have all the migration pain which there was while migrating from Babel 5 to Babel 6 and then from Babel 6 to Babel 7. We plan to only make a few breaking changes, and provide an easy migration strategy for each of them. Because of this, you won't see ~80 prereleases like we did in for Babel 7.0.0, but we plan to only release a few of them.

Babel 8.0.0 will only contain breaking changes: we will release a minor version the same day, containing all the bug fixes and new features that would otherwise be released in 8.0.0.

This document is still a work in progress, but you can already start by applying the suggested migration strategies to your own codebase.

• Compilation breaking changes

  • Don't remove uninitialized class fields when using Flow/TS (pr for flow: #10120, pr for TS: #11114)

    • Area: Flow and TypeScript transforms

    • Impact: High (only for flow and TypeScript users)

    • Migration:
      You can use the new declare syntax, introduced in TypeScript 3.7 (Babel 7.7) and in Flow 0.120 (Babel 7.9), if you don't want fields to be initialized to undefined:

      class A {
        foo: string | void; // initialized to undefined
        declare bar: number; // type-only
      }

      Note that while this syntax is enabled by default in @babel/parser when using the typescript or flow plugins, if you are using Babel to remove type annotations you must enable the allowDeclareFields option:

      // TypeScript
      {
        presets: [
          ["@babel/typescript", { "allowDeclareFields": true }]
        ]
      }
      
      // Flow
      {
        presets: [
          ["@babel/flow", { "allowDeclareFields": true }]
        ]
      }

  • Disallow sequence expressions inside JSX attributes (pr: #8787)

    • Area: JSX, @babel/parser
    • Impact: Low
    • Migration: If you are using them, you can already wrap them in parentheses:

      <div key={foo, bar}></div> // Invalid
      <div key={(foo, bar)}></div> // Valid

  • Disallow } and > in JSX text (pr: feat(babel-parser): throw syntax error for } and > in JSX text #11046)

    • Area: @babel/parser with JSX
    • Impact: Low
    • Migration: You can use {'}'} and {'>'} instead.
    • Notes: This is technically a bug fix becase the specification already forbids them. However, we have chosen to postpone it until Babel 8 because it could break someone's code.

  • Transforms JSX spread properties using object spread (pr: #11141, docs: website#2289)

    • Area: JSX
    • Impact: Medium
    • Migration: You can already have this behavior by using the useSpread option in Babel 7.7.0. If your code needs to run in an environment which doesn't support object spread, you can either use @babel/preset-env (recommended) or @babel/plugin-proposal-object-rest-spread. If you want to transpile Object.assign down to Babel's _extends helper (which is the current default behavior) you also need to enable @babel/plugin-transform-object-assign.

  • Use the new JSX implementation by default (pr: #11436, docs: website#2289)

    • Area: JSX
    • Impact: High
    • Migration: Starting from Babel 7.9.0, you can pass the runtime: "classic" option to @babel/preset-react or @babel/plugin-transform-react-jsx to be explicit about your usage of createElement (or the equivalent function in other libraries).
      If you are using a modern enough version of React or Preact, you can already use the new runtime: "automatic" implementation.

  • Parse JSX elements when both the JSX and TS plugins are enabled, and throw an error when both Flow and TS are enabled (pr: #11316)

    • Area: JSX, TypeScript
    • Impact: Low
    • Migration: If you don't want <Foo> to be parsed as a JSX element, but as a TypeScript typecast, you can disable the JSX plugin.
    • Note: The current behavior is that JSX parsing is only handled by the isTSX option of the TypeScript plugin. We are also removing this option. We think that having the JSX plugin control JSX parsing is less confusing for our users.

  • Remove moduleAttributes support (pr: #13308)

    • Area: Import assertions ES proposal
    • Impact: Low
    • Migration: Replace @babel/plugin-syntax-module-attributes by @babel/plugin-syntax-import-assertions: you can already start doing this in Babel 7. After you replace the plugin, you should search the following patterns in your codebase

    import value from "module" with type: "json";

    and replace them by

    import value from "module" assert { type: "json" };

    If you are not using @babel/plugin-syntax-module-attributes, you don't need to do anything.

  • Remove support for the 2018-09 decorators proposal (pr: #12712)

    • Area: @babel/plugin-proposal-decorators
    • Impact: Medium
    • Migration: You should migrate to the new version of the proposal. The syntax is the same, but you will need to rewrite your decorator functions. You can already migrate since Babel 7.17.0, using the "version": "2021-12" option of @babel/plugin-proposal-decorators.

• Configuration breaking changes

  • Require @babel/plugin-proposal-dynamic-import when transforming import() to SystemJS (#12700)
    • Area: @babel/plugin-transform-modules-systemjs
    • Impact: Medium
    • Migration: Add @babel/plugin-proposal-dynamic-import to your config: you can already do it in Babel 7. If you are using @babel/preset-env, you don't need to do anything.
    • Notes: All the other plugins which support dynamic import (transform-modules-commonjs and transform-modules-amd) require the separate plugin since it was introduced. We couldn't change it for transform-modules-systemjs because that package did already support dynamic import.
  • Use defaults, not ie 11 as default targets
    • Area: @babel/preset-env
    • Impact: Medium
    • Migration: If you are already using targets or have a .browserslist config file, this change won't affect you. Otherwise, you'll probably be fine with the new behavior (which supports these modern browsers). Note that the default targets does not include IE. If you still need to support IE, please specify IE 11 in targets. If you need to enable every possible plugin for even older browsers, you can already enable the forceAllTransforms option.
  • Remove uglify target (pr: #10895, docs: website#2290)
    • Area: @babel/preset-env
    • Impact: Low
    • Migration: The uglifyjs target had been deprecated since 7.0.0-beta.0, if you still need this, you can enable the forceAllTransforms option.
  • Move root AMD/UMD/SystemJS options to be plugin/preset options (pr: Allow defining the moduleIds-related option in the transform plugins #11194, [babel 8] Remove module-specific options from @babel/core #12724)
    • Area: @babel/core, @babel/cli, @babel/plugin-transform-modules-amd, @babel/plugin-transform-modules-umd, @babel/plugin-transform-modules-systemjs
    • Impact: Medium
    • Migration: When upgrading to Babel 8, you'll move to modify your config and pass these options to the correct plugin or preset.
      If you are passing these options using the cli, you'll need to create a configuration file.
  • Drop support for core-js 2 (pr: #11751)
    • Area: @babel/preset-env, @babel/plugin-transform-runtime, @babel/compat-data
    • Impact: High
    • Migration: You can already change your config to use core-js@3. Don't forget to npm install it!
    • Notes:
      1. When useBuiltIns is enabled, the default core-js version is now 3.6 instead of 2
      2. If you still need core-js@2 support, you can use babel-plugin-polyfill-core-js2.
  • Add mandatory version option to the decorators plugins, and merge the two plugins in @babel/parser.
  • Better file extension handling for TS and Flow presets (pr: #14955)
    • Area: @babel/preset-typescript, @babel/preset-flow, @babel/plugin-transform-typescript, @babel/plugin-transform-flow-strip-types
    • Impact: Medium
    • Migration:
      • You can already avoid enabling both the TS and Flow plugins on the same file, using the overrides option (this is not necessary if you are using the presets, and not directly the plugins)
      • When migrating to Babel 8, you can remove the isTSX option from @babel/preset-typescript and instead enable the relevant JSX preset/plugin.
    • Notes: See the PR description for more details.

• API breaking changes

  • Bump Node Support to >=14.19 (pr for >= 10: #10747)
    • Area: Every package
    • Impact: Medium
    • Notes: Node.js 12's EOL is on 2022-04-30.
  • Ship Babel as native ECMAScript modules
    • Area: Every package
    • Impact: High
    • Notes: Native modules are supported in Node.js 12!
  • Disallow using babel.transform, babel.transformFile, babel.transformFromAst, babel.parse, babel.loadOptions and babel.loadPartialConfig synchronously (pr: #11110, #12695)
    • Area: @babel/core
    • Impact: Medium
    • Migration: You can use babel.transformSync, babel.transformFromAstSync and babel.transformFileSync, supported since version 7.0.0. babel.parseSync, babel.loadOptionsSync and babel.loadPartialConfigSync will be introduced in v7.8.0.
  • Don't generate TSParenthesizedType unless createParenthesizedExpression is enabled (pr: #11200)
    • Area: @babel/parser
    • Impact: Low
    • Migration: If you need informations about parentheses, you can already enable the createParenthesizedExpression parser option (supported since Babel 7.4.0)
  • Remove t.jSX* and t.tS* builder aliases (pr: #6993)
    • Area: @babel/types
    • Impact: Low
    • Migration: Use t.jsx* and t.ts* instead, which have been supported since Babel 7.0.0
  • Reject invalid identifiers in t.identifier builder (#10917)
    • Area: @babel/types
    • Impact: Medium
    • Notes: Breaks metro bundler as of Nov 2019 (#10645)
  • Remove jsonCompatibleStrings generator option (pr: #9958)
    • Area: @babel/generator
    • Impact: Medium
    • Migration: @babel/generator allows to specify options for jsesc, the library used to escape printed values.
      If you are using the jsonCompatibleStrings option, you can replace it with jsescOption: { json: true }.
  • Disallow useBuiltIns: 0 when transforming JSX (pr: #12460, #12741, #12751)
    • Area: @babel/plugin-transform-react-jsx, @babel/preset-env
    • Impact: Low
    • Migration: Use useBuiltIns: false instead.

• AST breaking changes

  • Use an identifier for TSTypeParameter.name (#12829)

    • Area: @babel/parser
    • Impact: High for customized Babel plugin depending on TypeScript TSTypeParameter, e.g. the T in function f<T>() {}
    • Notes: For a TS type parameter node, node.name is a string in Babel 7 while in Babel 8 it is an Identifier
    • Migration: If you have a customized plugin accessing the name of a type parameter node, use node.name.name in Babel 8.

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

    • Area: @babel/parser
    • Impact: High for customized Babel plugin depending on these TS nodes:

    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

• Misc breaking changes

  • Bump peer dependency on @babel/core to ^8.0.0
    • Area: Every package
    • Impact: None if you update every @babel/* package
  • ESM runtime helper files should have the .mjs extension
    (EDIT: we now use "type": "module")
    • Area: @babel/runtime, @babel/runtime-corejs2, @babel/runtime-corejs3
    • Impact: Medium
    • Notes: ES Modules are now unflagged (nodejs/node#29866), and .js modules don't work with native import unless our package.json specifies type: "module" (which will break cjs helpers).
  • Change the format of CommonJS helpers in @babel/runtime
    • Area: @babel/runtime, @babel/runtime-corejs2, @babel/runtime-corejs3
    • Impact: Low
    • Notes: This will only affect you if you are using @babel/runtime 7.x with @babel/plugin-transform-runtime 8.x (or the other way around), which woudln't be supported anyway.
  • Disallow importing internal files of the different packages (pr: #14013)
    • Area: Every package
    • Impact: High
    • Notes: This will break at least vue-cli (cc @sodatea) and ember-cli-babel [2] (cc @rwjblue). We will provide targets-parser as a separate helper in v7.8.0.
      ⚠️ If anyone else is relying on internal Babel files, please let us know!
  • Output non-ASCII characters as-is in string literal (pr: #11384)
    • Area: @babel/generator
    • Impact: High only if you are manually calling the babel.transform API and your server is not serving js files in the utf8 encoding.
    • Notes: If you are using any one of @babel/cli, WebPack, Rollup, create-react-app or other Node.js powered bundlers, the transformed code is always encoded with utf-8. That said, this issue probably won't affect your app.
    • Mitigation: Ensure your server is always serving js files in the utf8 encoding. If you can not control the server output, use <script charset="utf-8" src="your-app.js"></script> in the html files. You may also restore to the Babel 7 behaviour by

      {
        generatorOpts: {
          jsescOption: {
            minimal: false
          }
        }
      }

  • Align Babel parser error codes between Flow and TypeScript (pr: #13294)
    • Area: @babel/parser
    • Impact: Low. It has an effect only if you handle the Babel parsing error when error.code is OptionalBindingPattern .
    • Mitigation The error.code for OptionalBindingPattern is renamed as PatternIsOptional.

• Other possibly breaking changes

  • Remove ts type imports on Program:exit (pr: #10009, #12706)
    • Area: @babel/plugin-transform-typescript
    • Impact: Low
  • Allow skipped NodePaths to be requeued (pr: #13291)
    • Area: @babel/traverse
    • Impact: Low
    • Notes: This is actually a bugfix, but it causes an infinite loop in the tdz implementation of @babel/plugin-transform-block-scoping
  • Look for comments containing "Babel 8" in the source code
    • Area: Every package
    • Impact: Low
    • Notes: Most of those comments are just for internal dependencies between packages. Any significant change will have a dedicated point in this list of breaking changes.

Related: #10752

Note for contributors

~~We implement Babel 8 breaking changes under the BABEL_8_BREAKING env flag. To test the breaking changes, please duplicate the affected tests with the -babel-7 suffix and add BABEL_8_BREAKING: false to test options. The breaking changes will be merged to the main branch but stripped before publishing. ~~