Babel Plugin Transform Named Capturing Groups Regex

A Babel plugin that transforms JavaScript regular expressions using named capturing groups into ES5-compatible syntax. It provides compile-time transformation of regex patterns containing named groups (like /(?<name>\w+)/) into equivalent ES5 regex syntax with numeric groups, ensuring compatibility with older JavaScript environments.

Package Information

• Package Name: @babel/plugin-transform-named-capturing-groups-regex
• Package Type: npm
• Language: TypeScript
• Installation: npm install --save-dev @babel/plugin-transform-named-capturing-groups-regex

Core Imports

// ESM
import plugin from "@babel/plugin-transform-named-capturing-groups-regex";

// CommonJS  
const plugin = require("@babel/plugin-transform-named-capturing-groups-regex");

Basic Usage

Babel Configuration

Add the plugin to your Babel configuration:

{
  "plugins": ["@babel/plugin-transform-named-capturing-groups-regex"]
}

With Options

{
  "plugins": [
    ["@babel/plugin-transform-named-capturing-groups-regex", {
      "runtime": false
    }]
  ]
}

Transformation Example

Input (ES2018+ named groups):

const dateRegex = /(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/;
const result = dateRegex.exec("2023-12-25");
console.log(result.groups.year);  // "2023"
console.log(result.groups.month); // "12"
console.log(result.groups.day);   // "25"

Output (ES5 compatible):

const dateRegex = /(\d{4})-(\d{2})-(\d{2})/;
const result = dateRegex.exec("2023-12-25");
// Runtime support provides .groups property access
console.log(result.groups.year);  // "2023"
console.log(result.groups.month); // "12"
console.log(result.groups.day);   // "25"

Capabilities

Plugin Export

The main plugin export provides a Babel plugin for transforming named capturing groups in regular expressions.

/**
 * Default export: Babel plugin for transforming named capturing groups
 * @param api - Babel API object 
 * @param options - Plugin configuration options
 * @returns Babel plugin object with transformation logic
 */
declare function plugin(api: any, options?: PluginOptions): any;
export default plugin;

/**
 * Plugin configuration options
 */
interface PluginOptions {
  /** Enable runtime mode for dynamic regex patterns (default: false) */
  runtime?: boolean;
}

Option Details:

• runtime (optional, boolean): When set to true, enables runtime mode for handling dynamic regex patterns. In runtime mode, the plugin includes additional runtime support for transforming patterns created at runtime. Defaults to false for compile-time only transformation.

Error Handling

The plugin validates configuration options and throws errors for invalid input:

// Throws Error if runtime option is not a boolean
throw new Error("The 'runtime' option must be boolean");

Common Error Scenarios:

• Providing a non-boolean value for the runtime option
• Invalid Babel API usage (handled by Babel core)

Advanced Usage

Runtime Mode

Enable runtime mode for applications that create regex patterns dynamically:

{
  "plugins": [
    ["@babel/plugin-transform-named-capturing-groups-regex", {
      "runtime": true
    }]
  ]
}

This mode provides additional runtime support for regex patterns that cannot be analyzed at compile time.

Integration with Other Plugins

The plugin works seamlessly with other Babel regex plugins and should be ordered appropriately in your plugin chain:

{
  "plugins": [
    "@babel/plugin-transform-unicode-regex",
    "@babel/plugin-transform-named-capturing-groups-regex",
    "@babel/plugin-transform-sticky-regex"
  ]
}

Browser Compatibility

This plugin enables named capturing groups to work in environments that don't support ES2018 regex features:

• Before transformation: Requires ES2018+ (Chrome 64+, Firefox 78+, Safari 11.1+)
• After transformation: Works in ES5+ environments (IE11+, legacy mobile browsers)

Plugin Integration

This plugin is part of the Babel RegExp features plugin system and automatically handles:

• Compile-time transformation: Transforms literal regex patterns in source code
• Runtime support: When enabled, provides runtime compatibility for dynamic patterns
• ES5 compatibility: Converts named capturing groups to numbered groups with .groups property polyfill

The plugin integrates seamlessly with other Babel regex transformation plugins and preset-env.