Diagnosing Babel preset-env Target Mismatches That Ship Modern Syntax to Old Browsers

Recognizable Condition

Your build finishes without errors, local development works, and modern browsers render the application correctly. Production users on older browsers, however, see a hard SyntaxError the moment the script loads—before any application logic runs. The message typically names modern syntax: Unexpected token '?' for optional chaining, Unexpected token '??' for nullish coalescing, or Unexpected identifier for class fields. Because the failure happens during parsing, not execution, no polyfill or runtime patch can rescue it after the fact.

This pattern usually means @babel/preset-env resolved target environments that are too modern, so it skipped the syntax transforms needed to downlevel (convert newer syntax into older, widely supported equivalents) those features for legacy engines.

Cause and Diagnostic Table

Symptom in build or output	Likely cause	Quick diagnostic
Resolved browserslist lists only recent browsers	Query in .browserslistrc or package.json is too narrow	Run npx browserslist and compare to your support matrix
preset-env receives no explicit targets and no browserslist config exists	preset-env falls back to a modern default baseline	Search the project for any browserslist configuration
Explicit targets in Babel config override browserslist	Hard-coded high versions in babel.config.js or .babelrc	Grep for targets in all Babel config files
Built bundle still contains ?. or ??	preset-env transform for that feature was skipped or disabled	Search the production output for the operator
Syntax is downleveled but runtime APIs are missing	useBuiltIns misconfigured or core-js version absent	Check useBuiltIns and corejs options in preset-env

Ordered Checks

1. Inspect the resolved browserslist for the build environment

   Run the following in your project root (requires Node.js and the browserslist package, which is typically installed transitively by build tools):

   npx browserslist

   Expected check: The output should match your intended support matrix. If it lists only recent Chrome, Firefox, or Safari versions, preset-env will skip transforms for older engines. Note that BROWSERSLIST_ENV or NODE_ENV can change the result; run the command with the same environment variables your production build uses.

2. Confirm preset-env is applying the expected transforms

   Create a minimal file, for example check-syntax.js:

   const value = obj?.prop ?? "default";

   Run it through your project's Babel pipeline. If you use a bundler, inspect the built output for this file. Alternatively, use a small Node script with @babel/core in the project root:

   const { transformFileSync } = require("@babel/core");
   const result = transformFileSync("./check-syntax.js", {
     presets: [["@babel/preset-env", { targets: "> 0.5%, last 2 versions, Firefox ESR" }]],
   });
   console.log(result.code);

   Expected check: The printed output should not contain ?. or ?? if the targets include browsers that lack support. If the operators remain, the targets are too modern or a conflicting plugin is disabling the transform.

3. Inspect the built output for known modern features

   Search the production bundle for optional chaining, nullish coalescing, or private class fields. Run in the build output directory:

   grep -rE '\?\.|\?\?' dist/ | head -n 20

   Expected check: No matches in files intended for legacy browsers. If matches appear, the transform did not run. Be careful to exclude source maps, which may intentionally retain original syntax.

4. Check all Babel and browserslist configuration sources

   Look for browserslist keys in package.json, .browserslistrc files, and environment-specific overrides such as [production] sections. Also inspect babel.config.js, .babelrc, and any tool-specific Babel settings (webpack, Vite, Rollup) for explicit targets or plugins that might conflict.

Fixes Tied to Findings

• If browserslist resolves too modern: Tighten the query. In .browserslistrc:

  > 0.5%
  last 2 versions
  Firefox ESR
  not dead

  Or set explicit targets in babel.config.js:

  module.exports = {
    presets: [
      ["@babel/preset-env", {
        targets: {
          browsers: ["> 0.5%", "last 2 versions", "not ie 11"]
        }
      }]
    ]
  };

  Risk: Broadening support increases bundle size and build time. Test the rebuilt bundle in your lowest-supported browser.

• If preset-env is bypassed by explicit plugins: Remove conflicting syntax plugins such as @babel/plugin-proposal-optional-chaining, or adjust order so preset-env runs first. Plugin order matters; preset-env should generally precede plugins that assume downleveled syntax.

• If useBuiltIns is misconfigured: Ensure core-js is installed and pinned. For useBuiltIns: "usage", preset-env injects polyfills per file based on targets. Example:

  ["@babel/preset-env", {
    useBuiltIns: "usage",
    corejs: { version: "3.36", proposals: false }
  }]

  If corejs is missing or the version is wrong, polyfills may be omitted. Alternatively, use useBuiltIns: "entry" and import core-js/stable once at your entry point. Risk: Incorrect core-js versions can cause duplicate or missing globals.

• If build tool caches config: Clear the cache and rebuild. For webpack, delete node_modules/.cache; for other tools, remove their cache directories. Run the build again and repeat the output inspection.

Escalation Criteria

Escalate to a build or platform team when:

• Errors persist after aligning browserslist and preset-env targets and performing a clean rebuild.
• Multiple build tools merge Babel configurations in opaque ways, such as a monorepo with nested .babelrc files and a root babel.config.js.
• A third-party dependency ships untranspiled modern syntax that your own Babel config cannot reach because it resides in node_modules and is excluded from transforms.
• Runtime errors differ across browsers in ways that do not match published syntax support tables, suggesting a parser or polyfill conflict rather than a simple target mismatch.

Limitations and Verification

Babel major versions change preset-env transform sets and browserslist resolution logic. Verify behavior against the exact Babel version in your lockfile. Development servers often use different presets or source maps than production builds, so always test the production bundle. Changing targets can introduce regressions in environments you did not anticipate; run your test suite and manual smoke tests after adjusting configuration.

Practical verification: After applying a fix, rebuild and run the bundle in the lowest-supported browser or an emulator. The script should load without a SyntaxError. You can also repeat the transform check and the output search to confirm the operators are gone from the production code.