babel-plugin-polyfill-custom

2.0.49 verified Sat Apr 25 auth: no javascript

A Babel plugin that allows developers to freely customize polyfills, enabling the selection of any polyfill implementation (e.g., whatwg-fetch, unfetch, Zousan) instead of being limited to core-js or es-shims. Current stable version is 2.0.49, released on 2026-04-21, with weekly updates and frequent dependency bumps. Key differentiators: supports any polyfill, not just ECMAScript; uses browserslist to determine required polyfills; inserts polyfills via base64 data URIs for differential bundle serving. Alternative to @babel/preset-env's core-js-based polyfilling.

Common errors

error Error: Cannot find module 'babel-plugin-polyfill-custom' ↓

cause Package not installed or installed as devDependency without proper resolution.

fix

npm install --save-dev babel-plugin-polyfill-custom

error TypeError: babelPluginPolyfillCustom is not a function ↓

cause Incorrect import (default import used with require() without destructuring).

fix

Use const babelPluginPolyfillCustom = require('babel-plugin-polyfill-custom'); (no .default)

error Error: [BABEL] ...: Cannot find module './polyfills' from 'babel-plugin-polyfill-custom' ↓

cause Missing or incorrect polyfill path in configuration.

fix

Ensure polyfill paths are absolute or correctly resolved from node_modules.

Warnings

gotcha babel-plugin-polyfill-custom cannot transpile ECMAScript syntax; must be used with @babel/preset-env for syntax transformation. ↓

fix Add @babel/preset-env to your Babel config alongside this plugin.

gotcha Polyfills are inserted via base64 data URIs; bundlers like webpack 5.38.0+ or Rollup with @rollup/plugin-data-uri are required. ↓

fix Configure your bundler to handle data URIs (see README for webpack/Rollup/Parcel examples).

breaking v2.0.0 dropped support for CommonJS require() returning object with .default property; now ESM-only default export. ↓

fix Use ESM import syntax or const plugin = require('babel-plugin-polyfill-custom') (no .default).

deprecated The 'polyfill' option (singular) was renamed to 'polyfills' (plural) in v1.5.0. Using singular still works but logs a warning. ↓

fix Rename the option to 'polyfills'.

gotcha Using 'method: 'usage-pure'' may result in duplicate polyfills if @babel/plugin-transform-runtime is also used. ↓

fix Avoid combining with @babel/plugin-transform-runtime; use 'usage-entry' or 'entry' method instead.

Install

npm install babel-plugin-polyfill-custom

yarn add babel-plugin-polyfill-custom

pnpm add babel-plugin-polyfill-custom

Imports

default

wrong

const babelPluginPolyfillCustom = require('babel-plugin-polyfill-custom').default

correct

import babelPluginPolyfillCustom from 'babel-plugin-polyfill-custom'

ESM default export; in CommonJS, require returns the plugin function directly (no .default).

customPolyfills

wrong

const customPolyfills = require('babel-plugin-polyfill-custom/customPolyfills')

correct

import { customPolyfills } from 'babel-plugin-polyfill-custom'

Named export available since v2.0.0; using require requires destructuring from main module.

PluginConfig

import type { PluginConfig } from 'babel-plugin-polyfill-custom'

TypeScript type import available; not a runtime value.

Quickstart

Configures babel-plugin-polyfill-custom with custom polyfill sources for Promise, fetch, and Object.assign, using usage-pure method.

// babel.config.js
import babelPluginPolyfillCustom from 'babel-plugin-polyfill-custom';

export default {
  presets: [
    ['@babel/preset-env', { targets: 'last 2 versions' }]
  ],
  plugins: [
    [
      babelPluginPolyfillCustom,
      {
        polyfills: {
          'Promise': 'core-js-pure/stable/promise',
          'fetch': 'whatwg-fetch',
          'Object.assign': '@babel/runtime/helpers/extends'
        },
        method: 'usage-pure',
        browserlist: 'last 2 versions'
      }
    ]
  ]
};