babel-plugin-polyfill-es-shims

0.10.11 verified Sat Apr 25 auth: no javascript

A Babel plugin that automatically injects imports for es-shims polyfills based on target environments. Version 0.10.11, stable release part of the babel-polyfills monorepo. Key differentiator: modular approach to polyfilling ECMAScript built-ins, compatible with `core-js` and custom shims. Integrates with `@babel/preset-env` and supports `useBuiltIns: 'usage'` style. Active development, follows Babel releases.

Common errors

error Cannot find module 'babel-plugin-polyfill-es-shims' ↓

cause Package not installed or not in node_modules

fix

npm install babel-plugin-polyfill-es-shims --save-dev

error Error: Invalid method. Expected one of: "usage-global", "usage-pure" ↓

cause Using deprecated 'usage' method string

fix

Change method to 'usage-global' or 'usage-pure' in plugin options

error Polyfill "es.string.trim" is not available. Available polyfills: ... ↓

cause The es-shims package does not include every ES shim; some are provided by other packages

fix

Ensure the needed polyfill is included in your es-shims dependency or use core-js polyfills with babel-plugin-polyfill-corejs3

Warnings

breaking Deprecated method 'usage' replaced by 'usage-global' and 'usage-pure' ↓

fix Use method: 'usage-global' or method: 'usage-pure'

breaking Requires @babel/core ^7.4.0 || ^8.0.0-0 <8.0.0 ↓

fix Update @babel/core to latest 7.x or pre-release 8.x

gotcha Polyfill injection may not work with custom targets if not using @babel/preset-env's built-in support ↓

fix Ensure @babel/preset-env is configured with `useBuiltIns: false` and plugin targets are aligned

gotcha When using `method: 'usage-pure'`, imported polyfills are added as pure expressions and may affect tree-shaking ↓

fix Use `method: 'usage-global'` for global polyfills or ensure tree-shaking is configured correctly

deprecated The `es-shims` package may not be actively maintained; users may prefer `core-js` via babel-plugin-polyfill-corejs3 ↓

fix Consider migrating to babel-plugin-polyfill-corejs3 for better maintenance and compatibility

Install

npm install babel-plugin-polyfill-es-shims

yarn add babel-plugin-polyfill-es-shims

pnpm add babel-plugin-polyfill-es-shims

Imports

default

wrong

const plugin = require('babel-plugin-polyfill-es-shims').default

correct

import plugin from 'babel-plugin-polyfill-es-shims'

CommonJS require works, but avoid .default in ESM contexts

plugin as named export
```
import { default as plugin } from 'babel-plugin-polyfill-es-shims'
```
Only default export is available; named exports are not provided

insert parameters

wrong

['polyfill-es-shims', { targets: { ie: '11' }, method: 'usage' }]

correct

['polyfill-es-shims', { targets: { ie: '11' }, method: 'usage-global' }]

method 'usage' is deprecated; use 'usage-global' or 'usage-pure' since v0.10

Quickstart

Configures Babel to inject imports for ES shims based on target browsers, using the usage-global method.

// babel.config.js
module.exports = {
  presets: [
    ['@babel/preset-env', {
      targets: '> 0.25%, not dead',
      useBuiltIns: false // Let the polyfill plugin handle it
    }]
  ],
  plugins: [
    ['babel-plugin-polyfill-es-shims', {
      method: 'usage-global', // 'usage-pure' or 'usage-global'
      targets: { browsers: '> 0.25%, not dead' },
      shouldInjectPolyfill: (name) => name.startsWith('es.'), // Optional filter
      exclude: ['es.array.iterator'] // Optional exclude specific polyfills
    }]
  ]
};