Babel Plugin Polyfill Regenerator

0.6.8 verified Sat Apr 25 auth: no javascript

A Babel plugin that automatically imports regenerator-runtime when generator/async functions are used. Part of the babel-polyfills monorepo, this is the recommended replacement for @babel/plugin-transform-regenerator's built-in helper. Current version 0.6.8, released as part of the @babel/preset-env polyfill strategy. Unlike older approaches, it avoids bundling regenerator-runtime if not needed (tree-shaking friendly) and integrates with the broader babel polyfill ecosystem (corejs, entry/usage transforms). Requires @babel/core >=7.4 or ^8.0.0-0. Deprecated in favor of @babel/plugin-transform-runtime for library authors, but still maintained for use with @babel/preset-env usage-based polyfilling.

Common errors

error SyntaxError: Unexpected token 'import' > 1 | import "regenerator-runtime/runtime"; ↓

cause The plugin injects ESM import statements but the target environment does not support native ESM. This can happen if Babel is configured to output CommonJS but the plugin still outputs import.

fix

Ensure Babel is configured to output CommonJS (e.g., with @babel/preset-env's modules: 'commonjs' or @babel/plugin-transform-modules-commonjs).

error Error: [BABEL] ...: Cannot find module 'babel-plugin-polyfill-regenerator' ↓

cause The package is not installed or is missing from node_modules.

fix

Run npm install babel-plugin-polyfill-regenerator --save-dev

error ReferenceError: regeneratorRuntime is not defined ↓

cause regenerator-runtime is not included at runtime. The plugin assumes regenerator-runtime is a global or imported; if you are using modules, it should work, but if the import is stripped or not loaded, it fails.

fix

Make sure regenerator-runtime is included in your bundle. If using preset-env with useBuiltIns: 'usage', it should inject the import automatically. If not, add import 'regenerator-runtime/runtime' at the entry point.

Warnings

deprecated This plugin is deprecated in favor of using @babel/plugin-transform-runtime for libraries or relying on preset-env's built-in polyfill handling. New projects should use @babel/preset-env with corejs and let it handle regenerator automatically. ↓

fix Remove explicit babel-plugin-polyfill-regenerator and configure @babel/preset-env with useBuiltIns: 'usage' and corejs: 3.

breaking In v0.6.0, the plugin changed its internal logic to align with the broader babel-polyfills refactor. Projects that relied on specific import paths or module injection behavior may break. ↓

fix Ensure you are using the latest version (0.6.8) and that your Babel configuration does not have conflicting polyfill plugins.

gotcha If you use this plugin without @babel/preset-env set to useBuiltIns: 'usage', the plugin will not inject any imports because it only triggers when preset-env's polyfill detection marks code as needing regenerator. Standalone use without preset-env will do nothing. ↓

fix Configure @babel/preset-env with appropriate useBuiltIns setting, or switch to @babel/plugin-transform-runtime for standalone needs.

gotcha The plugin only injects imports for regenerator-runtime, not for other polyfills. To polyfill other features (e.g., promises, array methods), you must also include core-js via @babel/plugin-polyfill-corejs3 or similar. ↓

fix Add babel-plugin-polyfill-corejs3 or use @babel/preset-env with corejs setting.

Install

npm install babel-plugin-polyfill-regenerator

yarn add babel-plugin-polyfill-regenerator

pnpm add babel-plugin-polyfill-regenerator

Imports

default
wrong
```
import regenerator from 'babel-plugin-polyfill-regenerator'
```
correct
```
module.exports = require('babel-plugin-polyfill-regenerator')
```
This is a Babel plugin; it's imported as a CommonJS module using require(). ESM imports may fail or require .default.
default
wrong
```
plugins: [['babel-plugin-polyfill-regenerator', { method: 'usage-global' }]]
```
correct
```
plugins: [require('babel-plugin-polyfill-regenerator')]
```
The plugin does not accept options; options are passed via the parent preset-env. Passing options incorrectly may cause silent failure.

Quickstart

Configures Babel with preset-env and the regenerator polyfill plugin to automatically inject regenerator-runtime for async/generator functions.

// babel.config.js
module.exports = {
  presets: [
    ['@babel/preset-env', {
      targets: '> 0.25%, not dead',
      useBuiltIns: 'usage',
      corejs: 3
    }]
  ],
  plugins: [
    require('babel-plugin-polyfill-regenerator')
  ]
};

// Source (async.js)
async function foo() {
  await bar();
}

// Transpiled output (with regenerator import)
import "regenerator-runtime/runtime"; // or require(...)

function asyncGeneratorStep() { /* ... */ }
function _asyncToGenerator(fn) { /* ... */ }
var foo = function () {
  var _ref = _asyncToGenerator( /*#__PURE__*/ regeneratorRuntime.mark(function _callee() {
    return regeneratorRuntime.wrap(function _callee$(_context) {
      while (1) {
        switch (_context.prev = _context.next) {
          case 0:
            _context.next = 2;
            return bar();
          case 2:
          case 'end':
            return _context.stop();
        }
      }
    }, _callee);
  }));
  return function foo() {
    return _ref.apply(this, arguments);
  };
}();