Fix Unexpected ES2015+ Syntax in Babel Output – Diagnostic Guide

Recognizable Condition

After running npx babel src -d lib you still see arrow functions, classes or other ES2015+ syntax in lib/index.js. The project declares a browserslist that should support those features (e.g., "> 0.25%, not dead").

Common Causes

Cause	Typical Symptom
Browserslist query does not match the target environment	Preset‑env reports no transformations for the declared feature
Missing or mismatched core-js when useBuiltIns is enabled	Polyfills are not injected; runtime errors in older browsers
Preset‑env placed before custom plugins that alter the AST	Target resolution is overridden; syntax remains
Using an older Babel version that has a bug in target resolution	Unexpected syntax in output, even with correct config

Diagnostic Checklist

1. Verify the browserslist configuration. Open .browserslistrc or the browserslist section in package.json. Ensure the query is what you expect (e.g., "> 0.25%, not dead").
2. Check the Babel config. In babel.config.js confirm that @babel/preset-env is present and that targets or ignoreBrowserslistConfig: false are set correctly.
3. Run Babel with debug output. Execute:

   npx babel src --debug --out-dir lib

   This prints the resolved targets and the list of plugins that will run. Verify that the targets match the browserslist query.
4. Inspect the generated file. Open lib/index.js and look for arrow functions or classes. If they exist, note the line numbers.
5. Confirm useBuiltIns and core-js. If you set useBuiltIns: 'usage' or 'entry', ensure core-js is installed at the same major version as Babel recommends (e.g., core-js@3 for Babel 7.12+).

Fixes Tied to Findings

• Browserslist mismatch. Adjust the query to include the browsers that actually run your code. Example:

  # .browserslistrc
      > 0.25%, not dead
      not ie 11
    

  Re‑run Babel and confirm that the debug output now lists the correct target browsers.
• Missing polyfills. If useBuiltIns is 'usage' or 'entry', install the matching core‑js:

  npm install core-js@3 --save

  Then add an entry point polyfill (for 'entry') or verify that Babel injects imports automatically (for 'usage').
• Plugin order issue. Ensure @babel/preset-env is the last preset in the array, so it can apply syntax transforms after any custom presets. Example:

  module.exports = {
    presets: [
      ['@babel/preset-react', { runtime: 'automatic' }],
      '@babel/preset-env'
    ],
    plugins: [/* custom plugins */]
  };
  

• Babel version. Upgrade to the latest stable Babel if you suspect a bug. Run npm install @babel/core@latest @babel/cli@latest @babel/preset-env@latest.

Escalation Path

If, after applying the above fixes, arrow functions or classes still appear, consider:

• Creating a minimal reproduction with only src/index.js, babel.config.js, and .browserslistrc. If the minimal build works, the issue lies in other plugins or presets.
• Running npx babel --debug and looking for any ignoreBrowserslistConfig: true flags that may be set by a plugin.
• Checking for @babel/plugin-transform-modules-commonjs or similar that might reset the targets to a default of { esmodules: true }.
• Consulting the Babel issue tracker for known bugs in the specific version you use.

Practical Verification Steps

1. Run npx babel src --debug --out-dir lib and capture the targets section. It should list browsers like chrome 80, firefox 75, etc.
2. Open lib/index.js and confirm that arrow functions are replaced with function and classes with var _class = function () { ... }.
3. Execute the output in a browser that matches the lowest target (e.g., Chrome 80). If no syntax errors appear, the transformation succeeded.
4. If you used useBuiltIns: 'usage', search the output for import "core-js/modules/..." statements. They should only appear for features actually used.

Key Takeaway

Unexpected ES2015+ syntax in Babel output usually signals a mis‑configured browserslist, missing polyfills, or a plugin ordering issue. By systematically verifying each layer—query, Babel config, debug output, and final bundle—you can pinpoint the root cause and apply the precise fix.