This plugin is recommended in a library/tool

Note: Instance methods such as 'foobar'.includes('foo') will not work since that would require modification of existing built-ins(Use babel-polyfill for that)

Babel uses very small helpers for common functions such as _extend. By default this will be added to every file that requires it. This duplication is sometimes unnecessary, especially when your application is spread out over multiple files.

This is where the transform-runtime plugin comes in: all of the helpers will reference the module babel-runtime to avoid duplication across your compiled output. The runtime will be compiled into your build.

Another purpose of this transformer is to create a sandboxed environment for your code. If you use babel-polyfill and the built-ins it provides such as Promise, Set and Map, those will pollute the global scope. While this might be ok for an app or a command line tool, it becomes a problem if your code is a library which you intend to publish for other to use or if you can’t exactly control the environment in which your code will run.

The transformer will alias these built-ins to core-js so you can use them seamlessly without having to require the polyfill.

Prod and Dev

In most cases, you should install babel-plugin-transform-runtime as a development dependency, and babel-runtime as a production dependency.

Usage

I prefer to use .babelrc

1
2
3
4
5
6
7
8
9
10
{
  "plugins": [
    ["transform-runtime", {
      "helpers": false,
      "polyfill": false,
      "regenerator": true,
      "moduleName": "babel-runtime"
    }]
  ]
}

There the options are referred.

  • helpers: boolean, default to true

Toggles whether or not inlined babel helpers (classCallCheck, extends, etc) are replaced with calls to moduleName.

  • polyfill: boolean, default to be true

Toggles whether or not new built-ins(Promise, Set, Map, etc) are transformed to use a non-global polluting polyfill.

  • renegerator: boolean, default to true

Toggles whether or not generator functions are transforms to use a regenerator runtime that does not pollute the global scope.

  • moduleName: string, default to babel-runtime

Set the name/path of the module used when importing helpers.

Example:

1
2
3
{
  "moduleName": "flavortown/runtime"
}
1
import extends from 'flavortown/runtime/helpers/extend'

Technical Details

The runtime transformer plugin does three things:

  • Automatically requires babel-runtime/renegerator when you use generator/async functions;

  • Automatically requires babel-runtime/core-js and maps ES6 static methods and built-ins;

  • Removes the inline Babel helpers and uses the module babel-runtime/helpers instead.

You can use built-ins such as Promise, Set, Symbol, etc., as well as use all the Babel features taht require a polyfill seamlessly, without global pollution, making it extremely suitable for libraries.

Regenerator aliasing

1
2
3
function * foo () {

}

the following is generated

1
2
3
4
5
6
7
8
9
10
11
12
13
'use strict'

var _marked = [foo].map(regeneratorRuntime.mark)

function foo () {
  return regeneratorRuntime.wrap(function foo$(_context) {
    while (1) switch (_context_prev = _context.next) {
      case 0:
      case 'end':
        return _context.stop()
    }
  }, _marked[0], this)
}

This isn’t ideal as then you have to include the regenerator runtime which pollutes the global scope.

Instead what the runtime transformer does it compile that to:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
'use strict'

var _regenerator = require('babel-runtime/regenerator')
var _regenerator2 = _interopRequireDefault(_regenerator)

function _interopRequireDefault (obj) {
  return obj && obj.__esModule ? obj : { default: obj }
}

var _marked = [foo].map(_regenerator2.default.mark)

function foo () {
  return regeneratorRuntime.wrap(function foo$(_context) {
    while (1) switch (_context_prev = _context.next) {
      case '0':
      case 'end':
        return _context.stop()
    }
  }, _marked[0], this)
}

This means that you can use the regenerator runtime without polluting your current environment.

The same actions with Core-js Aliasing and Helper Aliasing.