@babel/register

One of the ways you can use Babel is through the require hook. The require hookwill bind itself to node's require and automatically compile files on thefly. This is equivalent to CoffeeScript'scoffee-script/register.

Install

  1. npm install @babel/core @babel/register --save-dev

Usage

  1. require("@babel/register");

All subsequent files required by node with the extensions .es6, .es, .jsx,.mjs, and .js will be transformed by Babel.

Polyfill not included

You must include the polyfill separately when using features that require it, like generators.

Ignores node_modules by default

NOTE: By default all requires to node_modules will be ignored. You canoverride this by passing an ignore regex via:

  1. require("@babel/register")({
  2.   // This will override `node_modules` ignoring - you can alternatively pass
  3.   // an array of strings to be explicitly matched or a regex / glob
  4.   ignore: [],
  5. });

Specifying options

  1. require("@babel/register")({
  2.   // Array of ignore conditions, either a regex or a function. (Optional)
  3.   // File paths that match any condition are not compiled.
  4.   ignore: [
  5.     // When a file path matches this regex then it is **not** compiled
  6.     /regex/,
  8.     // The file's path is also passed to any ignore functions. It will
  9.     // **not** be compiled if `true` is returned.
  10.     function(filepath) {
  11.       return filepath !== "/path/to/es6-file.js";
  12.     },
  13.   ],
  15.   // Array of accept conditions, either a regex or a function. (Optional)
  16.   // File paths that match all conditions are compiled.
  17.   only: [
  18.     // File paths that **don't** match this regex are not compiled
  19.     /my_es6_folder/,
  21.     // File paths that **do not** return true are not compiled
  22.     function(filepath) {
  23.       return filepath === "/path/to/es6-file.js";
  24.     }
  25.   ],
  27.   // Setting this will remove the currently hooked extensions of `.es6`, `.es`, `.jsx`, `.mjs`
  28.   // and .js so you'll have to add them back if you want them to be used again.
  29.   extensions: [".es6", ".es", ".jsx", ".js", ".mjs"],
  31.   // Setting this to false will disable the cache.
  32.   cache: true,
  33. });

You can pass in all other options as well, including plugins and presets.Note that config files will also be loaded and the programmaticconfig will be merged over top of the file config options.

Environment variables

By default @babel/node cli and @babel/register will save to a json cache in yourtemporary directory.

This will heavily improve with the startup and compilation of your files. Thereare however scenarios where you want to change this behaviour and there areenvironment variables exposed to allow you to do this.

BABEL_CACHE_PATH

Specify a different cache location.

  1. BABEL_CACHE_PATH=/foo/my-cache.json babel-node script.js

BABEL_DISABLE_CACHE

Disable the cache.

  1. BABEL_DISABLE_CACHE=1 babel-node script.js

Compiling plugins and presets on the fly

@babel/register uses Node's require() hook system to compile fileson the fly when they are loaded. While this is quite helpful overall, it meansthat there can be confusing cases where code within a require() hook causesmore calls to require, causing a dependency cycle. In Babel's case forinstance, this could mean that in the process of Babel trying to compile auser's file, Babel could end up trying to compile itself as it is loading.

To avoid this problem, this module explicitly disallows re-entrant compilation,e.g. Babel's own compilation logic explicitly cannot trigger further compilationof any other files on the fly. The downside of this is that if you want todefine a plugin or preset that is itself live-compiled, the process iscomplicated.

The crux of it is that your own code needs to load the plugin/preset first.Assuming the plugin/preset loads all of its dependencies up front, what you'llwant to do is:

  1. require("@babel/register")({
  2.   // ...
  3. });
  5. require("./my-plugin");

Because it is your own code that triggered the load, and not the logic within@babel/register itself, this should successfully compile any plugin/presetthat loads synchronously.