Skip to main content

How to Resolve "ReferenceError: regeneratorRuntime is not defined" Error in JavaScript

The ReferenceError: regeneratorRuntime is not defined is a common build-time or runtime error that occurs when you are using modern JavaScript features like async/await or Generators, but your build environment is not correctly configured to support them.

This error is a signal that Babel, your JavaScript compiler, has successfully transformed your async/await syntax into older, more compatible code, but the necessary runtime library to execute that transformed code is missing.

This guide will explain why this error happens and walk you through the two modern, standard solutions for configuring Babel correctly using @babel/preset-env or @babel/plugin-transform-runtime.

The Core Problem: Transpiling async/await​

Modern JavaScript features like async/await are not supported in older browsers. To ensure compatibility, tools like Babel transpile (transform) them into a more complex structure using generators and state machines that can run in older JavaScript engines.

This transformed code, however, depends on a helper library called regenerator-runtime. The regeneratorRuntime is not defined error means Babel did its job of transforming your code, but you failed to include this necessary runtime library in your final bundle.

@babel/preset-env is the standard, "all-in-one" preset for modern JavaScript applications. It can automatically include the necessary polyfills and runtime helpers for you based on your target browsers.

Logic: by configuring @babel/preset-env with useBuiltIns: 'usage' and a corejs version, you are telling Babel to automatically inject import statements for any polyfills (including regenerator-runtime) that are needed for the code in each file.

Solution:

  1. Install the necessary dependencies: 
    # Install core-js, which includes the polyfills
    npm install --save core-js@3

    # You should already have @babel/preset-env installed
    npm install --save-dev @babel/preset-env
  2. Configure your Babel config file (babel.config.js or .babelrc): 
    // babel.config.js
    module.exports = {
      presets: [
        [
          '@babel/preset-env',
          {
            useBuiltIns: 'usage', // Automatically injects polyfills
            corejs: 3, // Specify the core-js version
          },
        ],
      ],
    };
note

This is the recommended best practice for applications. It ensures that only the polyfills your code actually uses are included in your final bundle, which keeps your application size optimized.

Solution 2 (For Libraries): Using @babel/plugin-transform-runtime​

If you are building a library instead of an application, you should use @babel/plugin-transform-runtime. This plugin transforms your code to reference helpers from @babel/runtime, which prevents polyfills from being duplicated if multiple libraries are used together in an application.

Solution:

  1. Install the necessary dependencies: 
    # Install the plugin
    npm install --save-dev @babel/plugin-transform-runtime

    # Install the runtime dependency
    npm install --save @babel/runtime
    npm install --save @babel/runtime-corejs3
  2. Configure your Babel config file: 
    // babel.config.js
    module.exports = {
      presets: ['@babel/preset-env'],
      plugins: [
        [
          '@babel/plugin-transform-runtime',
          {
            regenerator: true, // This is true by default
            corejs: 3, // Specify the core-js version
          },
        ],
      ],
    };
note

This approach is slightly more complex but is the correct and professional way to build libraries that don't pollute the global scope or create polyfill conflicts.

The Legacy Solution: Manual regenerator-runtime Import​

Before Babel's automatic polyfilling was perfected, the common solution was to manually import the necessary libraries at the very top of your application's entry point (e.g., src/index.js).

note

This method is now considered outdated and is not recommended because it often includes the entire core-js library, which can significantly increase your bundle size.

The Outdated Solution:

  1. Install the dependencies: 
    npm install --save core-js regenerator-runtime
  2. Add imports to your entry file: 
    // src/index.js (or your main entry point)

    // Add these two lines at the very top
    import 'core-js/stable';
    import 'regenerator-runtime/runtime';

    // ... the rest of your application code

Conclusion​

The regeneratorRuntime is not defined error is a clear sign that your Babel configuration for handling async/await is incomplete.

  • For applications, the recommended best practice is to configure @babel/preset-env with useBuiltIns: 'usage' and corejs: 3. This automatically provides the necessary runtime helpers in an optimized way.
  • For libraries, the correct approach is to use @babel/plugin-transform-runtime to avoid global polyfills and prevent dependency conflicts.
  • Avoid the manual import of core-js and regenerator-runtime in modern projects, as it is less efficient than the automated methods.

Table of Contents