@babel/plugin-transform-numeric-separator

@babel/plugin-transform-numeric-separator is a Babel plugin that removes numeric separators (underscores) from numeric literals during JavaScript/TypeScript compilation. It transforms ES2021 numeric separator syntax to ensure compatibility with older JavaScript environments while preserving numeric values.

Package Information

• Package Name: @babel/plugin-transform-numeric-separator
• Package Type: npm
• Language: TypeScript
• Installation: npm install --save-dev @babel/plugin-transform-numeric-separator

Core Imports

This plugin is not imported directly in your code - it's used as part of your Babel configuration:

{
  "plugins": ["@babel/plugin-transform-numeric-separator"]
}

Or with options (none required for this plugin):

{
  "plugins": [["@babel/plugin-transform-numeric-separator", {}]]
}

Basic Usage

Add the plugin to your Babel configuration file:

.babelrc.json:

{
  "plugins": ["@babel/plugin-transform-numeric-separator"]
}

babel.config.js:

module.exports = {
  plugins: ["@babel/plugin-transform-numeric-separator"]
};

Input code with numeric separators:

// Decimal numbers
const million = 1_000_000;
const large = 1_000;

// Binary literals
const binary = 0b1010_0001_1000_0101;

// Hexadecimal literals  
const hex = 0xA0_B0_C0;

// Octal literals
const octal = 0o0_6_6_6;

// BigInt literals
const bigint = 9_007_199_254_740_993n;

Output after transformation:

// Decimal numbers
const million = 1000000;
const large = 1000;

// Binary literals
const binary = 0b1010000110000101;

// Hexadecimal literals
const hex = 0xA0B0C0;

// Octal literals
const octal = 0o0666;

// BigInt literals
const bigint = 9007199254740993n;

Architecture

The plugin operates as a Babel AST visitor that:

• Traverses the Abstract Syntax Tree (AST) during compilation
• Identifies NumericLiteral and BigIntLiteral nodes containing underscore separators
• Removes underscores from the raw representation while preserving actual numeric values
• Works with all numeric formats: Decimal, Binary (0b), Hexadecimal (0x), Octal (0o), and BigInt (n suffix)

Capabilities

Plugin Export

The main export is a Babel plugin created using the declare helper utility from @babel/helper-plugin-utils.

/**
 * Default export: Babel plugin that transforms numeric separators
 * Created using declare() from @babel/helper-plugin-utils
 */
const plugin: BabelPlugin;
export default plugin;

// Plugin configuration returned by the factory
interface BabelPlugin {
  /** Plugin identifier name */
  name: "transform-numeric-separator";
  /** AST visitor configuration */
  visitor: {
    NumericLiteral: (path: NodePath<NumericLiteral>) => void;
    BigIntLiteral: (path: NodePath<BigIntLiteral>) => void;
  };
  /** Parser plugin configuration (conditional based on Babel version) */
  manipulateOptions?: (options: any, parser: { plugins: string[] }) => void;
}

Babel Types Integration

The plugin works with standard Babel AST node types for numeric literals.

// Import types from @babel/types or @babel/core
import type { NodePath } from "@babel/core";
import type { NumericLiteral, BigIntLiteral } from "@babel/types";

// The plugin processes these AST node types:
type NumericLiteral = {
  type: "NumericLiteral";
  value: number;
  extra?: { raw?: string };
};

type BigIntLiteral = {
  type: "BigIntLiteral"; 
  value: string;
  extra?: { raw?: string };
};

type NodePath<T> = {
  node: T;
  // Additional Babel NodePath properties...
};

Supported Numeric Formats

The plugin transforms all JavaScript numeric literal formats:

• Decimal: 1_000_000 → 1000000
• Binary: 0b1010_0001 → 0b10100001
• Hexadecimal: 0xAE_BE_CE → 0xAEBECE
• Octal: 0o0_6_6_6 → 0o0666
• BigInt: 123_456n → 123456n

Plugin Dependencies

{
  "peerDependencies": {
    "@babel/core": "^7.0.0-0"
  },
  "dependencies": {
    "@babel/helper-plugin-utils": "^7.0.0"
  }
}

When using the plugin, ensure these are available in your project:

npm install --save-dev @babel/core @babel/plugin-transform-numeric-separator

Version Compatibility

The plugin uses api.assertVersion(REQUIRED_VERSION(7)) to ensure compatibility:

• Babel 7.x: Compatible with Babel ^7.0.0-0
• Babel 8.x: Compatible during transition with version range ^7.0.0-0 || >8.0.0-alpha <8.0.0-beta
• Parser Plugin: Automatically adds "numericSeparator" parser plugin in non-BABEL_8_BREAKING environments

Node.js Compatibility

• Minimum Node.js Version: 6.9.0
• Babel 8 Breaking Changes: Node.js >=20.19.0 || >=22.12.0
• Module Type: ES Module (CommonJS compatibility maintained)

Configuration Options

This plugin requires no configuration options. It automatically processes all numeric literals with underscore separators found in the source code.

Browser and Environment Support

The plugin enables ES2021 numeric separator syntax to work in:

• Older JavaScript engines that don't support numeric separators natively
• Legacy browser environments
• Node.js versions prior to ES2021 support
• Any JavaScript environment where Babel compilation is used