@babel/plugin-syntax-module-string-names

@babel/plugin-syntax-module-string-names is a Babel syntax plugin that enables parsing of Unicode string names in import and export statements. It allows JavaScript and TypeScript modules to use string literals (including Unicode characters) as import/export identifiers, enabling support for internationalized module names and special characters.

Package Information

• Package Name: @babel/plugin-syntax-module-string-names
• Package Type: npm
• Language: JavaScript (ES6 modules)
• Installation: npm install --save-dev @babel/plugin-syntax-module-string-names

Core Imports

import pluginSyntaxModuleStringNames from "@babel/plugin-syntax-module-string-names";

For CommonJS:

const pluginSyntaxModuleStringNames = require("@babel/plugin-syntax-module-string-names");

Basic Usage

Babel Configuration

Add the plugin to your Babel configuration to enable module string names syntax:

{
  "plugins": ["@babel/plugin-syntax-module-string-names"]
}

Parser Usage

When using Babel parser directly, include the moduleStringNames plugin:

import { parse } from "@babel/parser";

const code = `import { 'unicode string' as identifier } from 'module';`;

const ast = parse(code, {
  sourceType: "module",
  plugins: ["moduleStringNames"]
});

Enabled Syntax Examples

Once enabled, the plugin allows parsing of the following syntax patterns:

// Named imports with string names
import { 'unicode-string' as identifier } from 'module';
import { 'unicode string with spaces' as identifier } from 'module';
import { '學而時習之，不亦說乎？' as quotation } from 'Confucius';

// Named exports with string names
export { identifier as 'unicode-string' };
export { identifier as 'unicode string with spaces' };
export { quotation as '學而時習之，不亦說乎？' };

// Export from with string names
export { 'string-name' as identifier } from 'module';
export { identifier as 'string-name' } from 'module';
export { 'source-string' as 'target-string' } from 'module';

Architecture

The plugin follows Babel's standard syntax plugin architecture:

• Syntax-only Plugin: Does not transform code, only enables parsing
• Parser Plugin Integration: Adds "moduleStringNames" to parser plugins
• Plugin Utilities: Uses @babel/helper-plugin-utils for standard plugin structure
• Version Compatibility: Requires Babel 7.0.0 or higher

Capabilities

Plugin Export

The main plugin function that enables module string names syntax parsing.

/**
 * Babel syntax plugin that enables parsing of Unicode string names in import/export statements
 * @returns {BabelPlugin} Babel plugin object with name and manipulateOptions method
 */
export default function pluginSyntaxModuleStringNames(): BabelPlugin;

interface BabelPlugin {
  name: string;
  manipulateOptions(opts: any, parserOpts: ParserOptions): void;
}

interface ParserOptions {
  plugins: string[];
}

The plugin is created using the declare helper from @babel/helper-plugin-utils:

/**
 * Plugin implementation function passed to declare()
 * @param {BabelAPI} api - Babel API object with version assertion
 * @returns {BabelPlugin} Plugin configuration object
 */
function pluginImplementation(api: BabelAPI): BabelPlugin;

interface BabelAPI {
  assertVersion(version: number): void;
}

Plugin Properties

Plugin Name: The internal identifier for the plugin.

/**
 * Internal plugin name identifier
 * @type {string}
 * @constant
 */
name: "syntax-module-string-names"

Manipulate Options: Method that modifies parser options to enable the syntax.

/**
 * Modifies parser options to add moduleStringNames plugin
 * @param {any} opts - Babel transform options object (unused)
 * @param {ParserOptions} parserOpts - Parser options object to modify
 * @returns {void}
 */
manipulateOptions(opts: any, parserOpts: ParserOptions): void;

Types

Babel Plugin Type

interface BabelPlugin {
  /** Internal plugin name identifier */
  name: string;
  /** Function to modify parser options and enable syntax */
  manipulateOptions(opts: any, parserOpts: ParserOptions): void;
}

Parser Options Type

interface ParserOptions {
  /** Array of parser plugin names to enable */
  plugins: string[];
}

Babel API Type

interface BabelAPI {
  /** Assert that Babel version meets minimum requirements */
  assertVersion(version: number): void;
}

Usage Patterns

With Other Babel Plugins

The syntax plugin is commonly used alongside transformation plugins:

{
  "plugins": [
    "@babel/plugin-syntax-module-string-names",
    "@babel/plugin-transform-modules-commonjs"
  ]
}

With Babel Parser

Direct parser usage for AST generation:

import { parse } from "@babel/parser";

const ast = parse(sourceCode, {
  sourceType: "module",
  plugins: ["moduleStringNames", "typescript", "jsx"]
});

Development Workflow

Typical usage in a build pipeline:

{
  "presets": ["@babel/preset-env"],
  "plugins": [
    "@babel/plugin-syntax-module-string-names"
  ]
}

Integration Points

This plugin integrates with:

• Babel Parser: Adds syntax support to the parsing stage
• Module Transform Plugins: Enables proper transformation of string-named imports/exports
• TypeScript/Flow: Compatible with type-checking systems
• Build Tools: Works with webpack, Rollup, and other bundlers that use Babel
• Development Tools: Supports proper syntax highlighting and IDE features

Syntax Support Details

The plugin enables parsing of these specific syntax constructs:

Import Statements

• import { 'string-name' as identifier } from 'module';
• Mixed string and identifier imports: import { regularName, 'string-name' as alias } from 'module';

Export Statements

• export { identifier as 'string-name' };
• export { 'string-name' as identifier } from 'module';
• Mixed exports: export { regularName, identifier as 'string-name' };

String Name Requirements

• Must be valid string literals (single or double quotes)
• Can contain any Unicode characters
• Cannot be empty strings
• Must be used with as clause for aliasing

Error Handling

The plugin operates at the parsing stage, so errors are typically parse errors:

• Syntax Errors: Invalid string name syntax will cause parse failures
• Version Errors: Babel version < 7.0.0 will throw BABEL_VERSION_UNSUPPORTED error
• Parser Errors: Malformed import/export statements will fail parsing

The plugin itself does not throw runtime errors during transformation, as it only modifies parser configuration.

Performance Considerations

• Zero Runtime Overhead: Syntax-only plugin with no transformation cost
• Parse-time Only: Minimal impact on build performance
• Lazy Loading: Plugin is only loaded when Babel processes files
• Caching: Babel's plugin caching applies normally

Dependencies

The plugin has minimal dependencies:

• @babel/helper-plugin-utils: Provides the declare utility function
• @babel/core: Peer dependency for Babel integration (version ^7.0.0-0)

No runtime dependencies are added to the final bundle.