or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-babel--plugin-transform-reserved-words

Babel plugin that ensures no reserved words are used as identifiers by automatically renaming them to valid ES3 identifiers.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@babel/plugin-transform-reserved-words@7.27.x

To install, run

npx @tessl/cli install tessl/npm-babel--plugin-transform-reserved-words@7.27.0

index.mddocs/

@babel/plugin-transform-reserved-words

A Babel plugin that ensures no reserved words are used as identifiers by automatically renaming them to valid ES3 identifiers. This plugin is essential for transpiling modern JavaScript to run in legacy environments where certain words are reserved and cannot be used as identifiers.

Package Information

  • Package Name: @babel/plugin-transform-reserved-words
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev @babel/plugin-transform-reserved-words or yarn add @babel/plugin-transform-reserved-words --dev

Core Imports

The plugin is typically used via Babel configuration rather than direct imports. However, the plugin itself can be imported:

import transformReservedWords from "@babel/plugin-transform-reserved-words";

For CommonJS:

const transformReservedWords = require("@babel/plugin-transform-reserved-words");

Internal imports (from the plugin source):

import { declare } from "@babel/helper-plugin-utils";
import { types as t, type NodePath } from "@babel/core";

Basic Usage

Babel Configuration

Add the plugin to your Babel configuration:

{
  "plugins": ["@babel/plugin-transform-reserved-words"]
}

Or with the full package name:

{
  "plugins": ["@babel/plugin-transform-reserved-words"]
}

Programmatic Usage

import { transform } from "@babel/core";
import transformReservedWords from "@babel/plugin-transform-reserved-words";

const code = `
function utf8CheckByte(byte) {
  if (byte <= 0x7F) return 0;
  return -1;
}
`;

const result = transform(code, {
  plugins: [transformReservedWords]
});

console.log(result.code);
// Output: function utf8CheckByte(_byte) { ... }

Capabilities

Reserved Word Transformation

The plugin automatically identifies JavaScript identifiers that are not valid in ES3 environments and renames them to valid alternatives.

/**
 * Babel plugin created using the declare helper from @babel/helper-plugin-utils
 * The plugin transforms reserved words to valid ES3 identifiers
 */
declare const transformReservedWords: BabelPlugin;

interface BabelPlugin {
  /** Plugin factory function created by declare() */
  (api: BabelAPI): BabelPluginObject;
}

interface BabelAPI {
  /** Assert minimum Babel version compatibility */
  assertVersion(version: number | string): void;
}

interface BabelPluginObject {
  /** Plugin name identifier */
  name: "transform-reserved-words";
  /** Babel visitor object for AST transformation */
  visitor: BabelVisitor;
}

interface BabelVisitor {
  /** 
   * Visitor method for binding and referenced identifiers
   * Processes both variable declarations and variable references
   */
  "BindingIdentifier|ReferencedIdentifier"(path: NodePath<t.Identifier>): void;
}

Transformation Behavior

The plugin works by:

  1. Plugin Creation: Uses declare() from @babel/helper-plugin-utils with version assertion REQUIRED_VERSION(7)
  2. Identifying Invalid Identifiers: Uses Babel's t.isValidES3Identifier() to check if an identifier is valid in ES3
  3. Automatic Renaming: Leverages Babel's scope renaming mechanism path.scope.rename() to automatically rename invalid identifiers
  4. Scope-Aware: Maintains proper variable scoping during the renaming process
  5. Complete Coverage: Processes both binding identifiers (declarations) and referenced identifiers (usage)

Input Example:

function utf8CheckByte(byte) {
  if (byte <= 0x7F) return 0;
  return -1;
}

Output Example:

function utf8CheckByte(_byte) {
  if (_byte <= 0x7F) return 0;
  return -1;
}

Plugin Implementation

The actual plugin implementation is concise:

import { declare } from "@babel/helper-plugin-utils";
import { types as t, type NodePath } from "@babel/core";

export default declare(api => {
  api.assertVersion(REQUIRED_VERSION(7));

  return {
    name: "transform-reserved-words",
    visitor: {
      "BindingIdentifier|ReferencedIdentifier"(path: NodePath<t.Identifier>) {
        if (!t.isValidES3Identifier(path.node.name)) {
          path.scope.rename(path.node.name);
        }
      },
    },
  };
});

Types

/** Babel AST node path for identifier nodes */
type NodePath<T> = import("@babel/core").NodePath<T>;

/** Babel AST types namespace */
type t = typeof import("@babel/core").types;

/** Babel AST identifier node */
interface Identifier {
  type: "Identifier";
  name: string;
}

/** REQUIRED_VERSION function for version assertion */
declare function REQUIRED_VERSION(version: number): number | string;

Plugin Structure

The plugin follows Babel's standard plugin architecture:

/**
 * Plugin entry point - default export from declare()
 */
interface PluginExport {
  /** Default export is the plugin function */
  default: BabelPlugin;
}

/**
 * Plugin visitor pattern for AST transformation
 */
interface VisitorPattern {
  /** Combined visitor for both binding and referenced identifiers */
  "BindingIdentifier|ReferencedIdentifier": (path: NodePath<t.Identifier>) => void;
}

Dependencies

Runtime Dependencies

  • @babel/helper-plugin-utils: Provides the declare function for plugin creation with API version assertions
  • @babel/core: Provides AST types and node path utilities (imported as types as t, type NodePath)

Peer Dependencies

  • @babel/core: Version ^7.0.0-0 or higher

Error Handling

The plugin operates at the AST level and handles errors through Babel's standard error reporting mechanisms. Common scenarios:

  • Invalid AST: Babel will report parsing errors before the plugin runs
  • Scope Issues: Babel's scope analysis handles complex scoping scenarios automatically
  • API Version: Plugin asserts Babel version 7 compatibility and will fail on incompatible versions

Compatibility

  • Node.js: Requires Node.js >= 6.9.0
  • Babel: Compatible with Babel 7.x
  • Target Environment: Specifically designed for ES3 compatibility
  • Language Support: Works with JavaScript and TypeScript (via Babel parser)