@babel/plugin-transform-block-scoping

What is @babel/plugin-transform-block-scoping?

The @babel/plugin-transform-block-scoping npm package is a Babel plugin that transforms JavaScript code to convert block scoping (let and const) to function scoping (var) where necessary. This is particularly useful for ensuring compatibility with older environments that do not support ES6 block-scoped variables.

What are @babel/plugin-transform-block-scoping's main functionalities?

Transform let and const to var

This feature transforms block-scoped variables (let and const) into function-scoped variables (var) to ensure compatibility with older JavaScript engines.

if (true) {
  let x = 'hello';
}
// Transformed to:
if (true) {
  var x = 'hello';
}

Block scoping for loops

This feature correctly scopes the loop variable within closures, preventing common errors when using setTimeout or similar asynchronous functions within loops.

for (let i = 0; i < 3; i++) {
  setTimeout(function() { console.log(i); }, 0);
}
// Transformed to:
for (var i = 0; i < 3; i++) {
  (function(i) {
    setTimeout(function() { console.log(i); }, 0);
  })(i);
}

Other packages similar to @babel/plugin-transform-block-scoping

babel-plugin-transform-es2015-block-scoping

This package is a predecessor to @babel/plugin-transform-block-scoping and offers similar functionality, transforming ES2015 block-scoped variables to ES5. It is now deprecated in favor of the @babel suite of plugins.

fast-async

While not a direct alternative, fast-async is a Babel plugin that transforms async/await and generators to ES5, including handling block scoping within async functions. It provides a different set of features but deals with modern JavaScript syntax transformation like @babel/plugin-transform-block-scoping.

babel-preset-env

babel-preset-env is a Babel preset that includes @babel/plugin-transform-block-scoping among other plugins. It automatically determines the Babel plugins and polyfills you need based on your supported environments. It's a more comprehensive solution that includes similar functionality.

README

@babel/plugin-transform-block-scoping

Compile ES2015 block scoping (const and let) to ES5

Examples

In

{
  let a = 3
}

let a = 3

Out

{
  var _a = 3;
}

var a = 3;

Constant checks

This plugin also validates all const variables. Reassignment of constants is a runtime error and it will insert the necessary error code for those.

Installation

npm install --save-dev @babel/plugin-transform-block-scoping

Usage

Via .babelrc (Recommended)

.babelrc

Without options:

{
  "plugins": ["@babel/plugin-transform-block-scoping"]
}

With options:

{
  "plugins": [
    ["@babel/plugin-transform-block-scoping", {
      "throwIfClosureRequired": true
    }]
  ]
}

Via CLI

babel --plugins @babel/plugin-transform-block-scoping script.js

Via Node API

require("@babel/core").transform("code", {
  plugins: ["@babel/plugin-transform-block-scoping"]
});

Options

throwIfClosureRequired

boolean, defaults to false.

In cases such as the following it's impossible to rewrite let/const without adding an additional function and closure while transforming:

for (let i = 0; i < 5; i++) {
  setTimeout(() => console.log(i), 1);
}

In extremely performance-sensitive code, this can be undesirable. If "throwIfClosureRequired": true is set, Babel throws when transforming these patterns instead of automatically adding an additional function.

tdz

boolean, defaults to false.

By default this plugin will ignore the temporal dead zone (TDZ) for block-scoped variables. The following code will not throw an error when transpiled with Babel, which is not spec compliant:

i
let i;

If you need these errors you can tell Babel to try and find them by setting "tdz": true for this plugin. However, the current implementation might not get all edge cases right and its best to just avoid code like this in the first place.