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.

Solution 1 (Recommended for Applications): Using @babel/preset-env

@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:

   npm install --save core-js@3
   
   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
         },
       ],
     ],
   };

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:

   npm install --save-dev @babel/plugin-transform-runtime
   
   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
         },
       ],
     ],
   };

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).

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.