babel-register

6.26.0 verified Sat Apr 25 auth: no javascript

Babel's require hook for Node.js that automatically compiles files on the fly when required. Current stable version is 6.26.0 (legacy Babel 6) and 7.x (latest v7.29.2). Babel 8 (v8.0.0-rc.3) is in release candidate phase. This package binds to Node's require() to transpile .es6, .es, .jsx, and .js files. Key differentiator: it's the simplest way to use Babel without a build step, ideal for development or small scripts. Alternatives like @babel/register for Babel 7+ are recommended. Supports caching via BABEL_CACHE_PATH, and ignores node_modules by default. Note: does not include polyfills; requires separate babel-polyfill for generators/async.

Common errors

error ReferenceError: regeneratorRuntime is not defined ↓

cause babel-register does not include the runtime polyfill for generators/async.

fix

Install babel-polyfill and add require('babel-polyfill') before require('babel-register').

error Error: Cannot find module 'babel-core' ↓

cause babel-core is a required peer dependency not installed.

fix

Run npm install babel-core --save-dev (or babel-core@^7 for Babel 7).

error Error: Plugin/Preset files are not allowed to export objects, only functions. ↓

cause Using an outdated Babel 6 plugin/preset with Babel 7.

fix

Upgrade all Babel packages to @babel/scoped versions (e.g., @babel/core instead of babel-core).

Warnings

deprecated babel-register is deprecated in favor of @babel/register for Babel 7+. ↓

fix Replace require('babel-register') with require('@babel/register') in Babel 7 projects.

gotcha Files in node_modules are ignored by default; you must set ignore: false or a custom regex to compile them. ↓

fix Add { ignore: false } or { only: /your_folder/ } to options.

gotcha Cannot compile files used by babel-register itself (e.g., config files, the entry script). ↓

fix Use babel-node instead, or pre-compile those files.

gotcha Polyfill is not included; features like generators and async/await require babel-polyfill or @babel/polyfill. ↓

fix Add require('babel-polyfill') before require('babel-register').

breaking Babel 8 (v8.0.0-rc.1+) removes babel-register; @babel/register is the replacement. ↓

fix Use @babel/register with Babel 8.

Install

npm install babel-register

yarn add babel-register

pnpm add babel-register

Imports

require hook
wrong
```
import 'babel-register'
```
correct
```
require('babel-register')
```
This is a CommonJS module; ESM import syntax may work in some environments but the require hook pattern is standard and expected.
options object
wrong
```
const babelRegister = require('babel-register'); babelRegister.configure({ ignore: /regex/ })
```
correct
```
require('babel-register')({ ignore: /regex/ })
```
The package exports a single function that optionally accepts options. There is no named export; calling require() returns the function directly.
cache environment variables
wrong
```
process.env.BABEL_CACHE_PATH = '/path/cache.json'; require('babel-register')
```
correct
```
BABEL_CACHE_PATH=/path/cache.json node script.js
```
Environment variables must be set before the process starts; modifying process.env before require usually works but is not recommended.

Quickstart

Demonstrates basic usage of babel-register to transpile files on the fly with preset-env and caching.

// Install: npm install babel-register babel-preset-env --save-dev
// Create .babelrc with {"presets":["env"]}

require('babel-register');
require('./app.js'); // app.js can use ES2015+ features

// With options:
require('babel-register')({
  presets: ['env'],
  ignore: /node_modules/,
  cache: true
});