@babel/plugin-proposal-numeric-separator

@babel/plugin-proposal-numeric-separator is a Babel plugin that removes numeric separators from decimal, binary, hexadecimal, and octal literals. It enables developers to write more readable numeric constants using underscores (like 1_000_000 for one million) while ensuring compatibility with JavaScript engines that don't support this ES2021 feature.

Package Information

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

Core Imports

This package exports a default Babel plugin function that should be configured in your Babel setup:

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

Basic Usage

The plugin automatically transforms numeric literals with separators during Babel's compilation process:

Input code:

// Decimal numbers
const million = 1_000_000;
const billion = 1_000_000_000;

// Hexadecimal numbers  
const hex = 0xFF_EC_DE_5E;

// Binary numbers
const binary = 0b1010_0001_1000_0101;

// Octal numbers
const octal = 0o0_6_6_6;

// BigInt literals
const bigInt = 9_007_199_254_740_993n;

Output code:

// Decimal numbers
const million = 1000000;
const billion = 1000000000;

// Hexadecimal numbers
const hex = 0xFFECDE5E;

// Binary numbers
const binary = 0b1010000110000101;

// Octal numbers
const octal = 0o0666;

// BigInt literals
const bigInt = 9007199254740993n;

Architecture

@babel/plugin-proposal-numeric-separator follows Babel's standard plugin architecture:

• Plugin Declaration: Uses @babel/helper-plugin-utils declare() function for standardized plugin creation
• Syntax Support: Inherits from @babel/plugin-syntax-numeric-separator to enable parsing of numeric separator syntax
• AST Transformation: Implements visitor pattern targeting NumericLiteral and BigIntLiteral AST nodes
• Raw Value Processing: Modifies the extra.raw property by removing underscore characters while preserving the numeric value

The plugin operates during Babel's transform phase, after parsing but before code generation, ensuring numeric separators are removed for broader JavaScript engine compatibility.

Capabilities

Plugin Export

The package exports a default Babel plugin object created using the declare() helper function.

import { declare } from "@babel/helper-plugin-utils";
import syntaxNumericSeparator from "@babel/plugin-syntax-numeric-separator";

/**
 * Default export: Babel plugin that removes numeric separators from literals
 */
const plugin: BabelPlugin;
export default plugin;

/**
 * Plugin definition using Babel's declare helper
 */
interface BabelPlugin {
  name: "proposal-numeric-separator";
  inherits: typeof syntaxNumericSeparator.default;
  visitor: {
    NumericLiteral: RemoverFunction;
    BigIntLiteral: RemoverFunction;
  };
}

type RemoverFunction = (path: {
  node: {
    extra?: {
      raw?: string;
    };
  };
}) => void;

Transformation Features

The plugin provides the following transformation capabilities:

• Decimal Numbers: Removes underscores from decimal numeric literals (e.g., 1_000 → 1000)
• Hexadecimal Numbers: Removes underscores from hexadecimal literals (e.g., 0xFF_FF → 0xFFFF)
• Binary Numbers: Removes underscores from binary literals (e.g., 0b1010_0001 → 0b10100001)
• Octal Numbers: Removes underscores from octal literals (e.g., 0o777_777 → 0o777777)
• BigInt Literals: Removes underscores from BigInt literals (e.g., 123_456n → 123456n)

Plugin Implementation

The plugin uses Babel's standard plugin architecture:

• Inherits syntax support: Automatically includes @babel/plugin-syntax-numeric-separator for parsing
• AST Transformation: Uses visitor pattern to transform NumericLiteral and BigIntLiteral nodes
• Raw value processing: Removes underscores from the extra.raw property of literal nodes

Dependencies

The plugin requires the following dependencies:

• @babel/core: ^7.0.0-0 (peer dependency)
• @babel/helper-plugin-utils: ^7.18.6 (for plugin declaration utilities)
• @babel/plugin-syntax-numeric-separator: ^7.10.4 (for syntax parsing support)

Integration

Babel Configuration

Add to your Babel configuration file:

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

// Or with preset
module.exports = {
  presets: ["@babel/preset-env"],
  plugins: ["@babel/plugin-proposal-numeric-separator"]
};

Build Tools

Webpack with babel-loader:

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'babel-loader',
          options: {
            plugins: ['@babel/plugin-proposal-numeric-separator']
          }
        }
      }
    ]
  }
};

Rollup with @rollup/plugin-babel:

import babel from '@rollup/plugin-babel';

export default {
  plugins: [
    babel({
      plugins: ['@babel/plugin-proposal-numeric-separator']
    })
  ]
};

Compatibility

• Node.js: >=6.9.0
• Browser Support: All browsers supported by your Babel target configuration
• ES2021 Feature: Transforms ES2021 numeric separator syntax for broader compatibility