Babel Preset-Env Target Configuration: A Diagnostic Guide for Missing Polyfills and Browser Compatibility

Recognizable Condition

When your Babel-transpiled JavaScript runs in target browsers but throws ReferenceError: Promise is not defined, Symbol is not defined, or similar errors, you're likely missing polyfills that Babel's @babel/preset-env should have injected based on your targets configuration.

Root Cause Diagnostic Table

Symptom	Most Likely Cause	Verification Step
Runtime ReferenceError for Promise, fetch, Symbol	Missing core-js polyfills; @babel/preset-env didn't include polyfill plugin	Run babel --show-config to check for @babel/plugin-transform-runtime or core-js proposals
Generator functions fail in IE11	Regenerator runtime missing; @babel/plugin-transform-regenerator-runtime not applied	Check for regenerator-runtime in output bundle
Transpiled code uses Object.entries in unsupported browsers	Targets too broad or misconfigured; preset-env didn't detect required transforms	Run babel --show-config and verify transform-object-entries plugin is present
Build works locally but fails on older browsers	Targets not specified or set to 'not dead' which includes outdated browsers	Confirm .babelrc or babel.config.js targets match your browser matrix

Ordered Diagnostic Checks

1. Verify Babel 7+ package naming
   Run npm ls @babel/preset-env in your project root. If you see babel-preset-env (no @ scope) instead, Babel 6 is installed and the modern targets option won't work as expected. Upgrade to @babel packages for full target-based polyfill injection.
2. Inspect current targets configuration
   Check your .babelrc or babel.config.js. A minimal working config for IE11 support should include:

   { "presets": [["@babel/preset-env", { "targets": { "browsers": ["ie 11"] } }]] }

   For Node.js 14 runtime targeting:

   { "presets": [["@babel/preset-env", { "targets": { "node": "14" } }]] }

3. Run babel --show-config to list generated plugins
   Execute npx babel --show-config --config-file .babelrc (or point to your config file). Look for:
   • transform-regenerator-runtime when targeting IE11
   • transform-runtime with corejs option for polyfill injection
   • Specific plugins like transform-object-rest-spread if using those features
   If these are missing, your targets aren't triggering the expected transforms.
4. Check for core-js integration
   If using @babel/usage for automatic polyfill injection, verify core-js is installed: npm ls core-js. The preset needs it to determine which polyfills to include based on usage analysis.
5. Test transpiled output in target environment
   Use a local server with live reload to test. Open browser dev tools and check the Console for ReferenceError messages before your application code executes. This confirms whether the issue is in Babel's output or in runtime environment setup.

Fixes Based on Findings

Fix: Missing IE11 regenerator runtime

If babel --show-config shows no regenerator-runtime plugin when targeting IE11, add it explicitly:

npm install --save-dev @babel/plugin-transform-regenerator-runtime

Then in your config:

{ "plugins": ["@babel/plugin-transform-regenerator-runtime"] }

Fix: Incorrect targets causing unexpected browser support

If targeting modern browsers only, use specific browser versions instead of broad queries:

{ "presets": [["@babel/preset-env", { "targets": { "browsers": ["> 1% in US", "not ie", "not op_mini all"] } }]] }

Fix: No polyfills being injected

If using @babel/usage for automatic polyfills, ensure core-js is available:

npm install core-js

Then configure:

{ "plugins": [["@babel/plugin-transform-runtime", { "corejs": 3 }]] }

Escalation Criteria

• If babel --show-config shows expected plugins but errors persist, the issue may be in module bundling (Webpack/Rollup) stripping or reordering code. Check bundler configuration for target options and plugin ordering.
• If polyfills exist in bundle but still fail, verify the polyfill is loaded before application code. Some setups require explicit import 'core-js/stable'; import 'regenerator-runtime/runtime'; at entry point.
• If transpilation succeeds but bundle size exploded, your targets may be too broad. Use browserslist to audit supported browsers and narrow the list.

Limitations and Verification

Babel's target-based polyfill injection relies on accurate browser feature detection. The 'not dead' target preset may include browsers you don't actually support, increasing bundle size unnecessarily. Always verify the final transpiled output matches your actual browser support requirements.

To verify fixes work:

1. Run npx babel --show-config --config-file .babelrc and confirm required plugins appear
2. Build your project and search the output for regenerator-runtime, core-js, or specific polyfills
3. Test in actual target browsers using a local server with console logging enabled