Reducing Babel Helper Duplication with @babel/plugin-transform-runtime

The problem: duplicated helper functions

When Babel transpiles modern JavaScript syntax—such as class definitions, arrow functions, or async/await—into a form that older browsers can parse, it inlines small utility functions like _classCallCheck, _extends, and _await into every file that references them. In a project with many modules, each module carries its own copy of these helpers, which adds kilobytes of repeated code across every bundle chunk.

Thesis: @babel/plugin-transform-runtime centralises those helpers

The @babel/plugin-transform-runtime plugin changes Babel’s default behaviour: instead of inlining a helper, it emits a reference to a shared module, @babel/runtime. After the transformation, a file that uses a class or async function will contain require("@babel/runtime/helpers/extends") (or an equivalent import), and the actual helper implementation lives once in the runtime chunk that is shipped to the user.

Concrete effect

Imagine a codebase of 40 ES‑class definitions. Without the plugin, each transpiled file might define its own function _classCallCheck() { … }. With the plugin, only a single require("@babel/runtime/helpers/classCallCheck") call appears per file, and the helper is defined once in the runtime bundle.

Installation and Babel configuration

1. Install the plugin as a devDependency – it is only needed at build time.

   npm install --save-dev @babel/plugin-transform-runtime

   Run this command in the root of your project where you have write permissions.

2. Install the runtime as a production dependency – the transpiled code will need this module at runtime.

   npm install @babel/runtime

   Again, execute from the project root; the package will be added to package.json under dependencies.

3. Add the plugin to your Babel configuration (e.g. babel.config.json).

   {
     "presets": ["@babel/preset-env"],
     "plugins": [
       ["@babel/plugin-transform-runtime", {
         "corejs": false,
         "regenerator": true,
         "useESModules": false
       }]
     ]
   }

   These options tell the plugin to:

   • Disable automatic core-js polyfill injection (you can manage polyfills separately with @babel/preset-env.
   • Replace the regenerator runtime with the shared version.
   • Emit CommonJS require calls for compatibility with Node‑style bundlers.

What to check after the transformation

1. Inspect the transpiled output of a single module. Look for require("@babel/runtime/helpers/... instead of an inline function definition.

   // before (inline)
   function _classCheck(instance, Constructor) { ... }
   
   // after (runtime reference)
   require("@babel/runtime/helpers/classCheck");
   

2. Run a bundle‑analyzer tool (for example webpack-bundle-analyzer or source-map-explorer) on a production build. Compare the size of helper‑related code before and after adding the plugin; you should see a reduction in duplicated helper bytes.

   Note: the actual size savings depend on the number of modules and the Babel version in use.

3. Verify package.json: @babel/runtime should appear under dependencies, not devDependencies. If it is missing, the transpiled code may throw Cannot find module '@babel/runtime' at runtime.

Trade‑offs and limitations

• Initial bundle size for very small projects: When a project has only a few modules, the overhead of loading the runtime module can outweigh the savings from eliminating a handful of inline helpers. In such cases the default Babel behaviour may be cheaper.

• Polyfill coordination: The runtime plugin provides an isolated polyfill strategy. If you need global polyfills (e.g., Array.prototype.includes) you must still configure @babel/preset-env with useBuiltIns: "usage" or include core-js manually; the two approaches do not automatically coordinate. Setting corejs: false in the plugin options can help avoid double‑polyfilling, but the exact behaviour depends on your preset‑env version and core-js configuration.

• Configuration discipline: Mixing @babel/preset-env with useBuiltIns: "usage" and the runtime plugin can produce duplicate polyfills if not carefully coordinated. Review your preset‑env settings and adjust the plugin options accordingly.

Actionable next steps

1. Run a quick build with the plugin enabled and use a bundle‑analyzer to measure the helper‑code reduction.
2. If you already rely on core-js for polyfills, keep corejs: false in the plugin config to minimise redundant polyfill inclusion.
3. For projects that target both browsers and Node, consider setting useESModules: false to emit CommonJS require calls that Node can resolve without a bundler.
4. Document the runtime dependency in your project’s README so future contributors understand it is a runtime requirement.

By centralising Babel helpers with @babel/plugin-transform-runtime you reduce duplication, keep your production bundle lean, and avoid polluting the global namespace. It is a small configuration change that can noticeably improve load performance and maintainability, provided you verify the outcome for your specific project and version stack.