@babel/plugin-syntax-import-assertions

Allow parsing of the module assertion attributes in the import statement. This plugin enables parsing of the deprecated import assertions syntax (with assert keyword) while providing intelligent handling to upgrade to the newer import attributes syntax when both plugins are present.

Package Information

• Package Name: @babel/plugin-syntax-import-assertions
• Package Type: npm
• Language: TypeScript
• Installation: npm install --save-dev @babel/plugin-syntax-import-assertions or yarn add @babel/plugin-syntax-import-assertions --dev

Core Imports

import plugin from "@babel/plugin-syntax-import-assertions";

For CommonJS:

const plugin = require("@babel/plugin-syntax-import-assertions");

Basic Usage

This plugin is typically used in Babel configurations to enable parsing of import assertion syntax:

// babel.config.js
module.exports = {
  plugins: ['@babel/plugin-syntax-import-assertions']
};

Or with options:

// babel.config.js  
module.exports = {
  plugins: [
    ['@babel/plugin-syntax-import-assertions', options]
  ]
};

The plugin enables parsing of import assertions like:

// Standard import assertions with type
import json from './data.json' assert { type: 'json' };
import styles from './styles.css' assert { type: 'css' };

// Import assertions with custom attributes
import foo from "foo.json" assert { lazy: "true" };

// Dynamic import assertions  
import('./data.json', { assert: { type: 'json' } });

// Export assertions
export { default } from "foo.json" assert { lazy: "true" };

Architecture

The plugin works by manipulating Babel's parser options rather than transforming the AST. Key components:

• Plugin Declaration: Uses @babel/helper-plugin-utils for plugin creation and version compatibility
• Parser Manipulation: Modifies Babel's parser options to enable specific syntax features
• Plugin Coordination: Intelligently handles interaction with related import syntax plugins
• Legacy Support: Maintains backward compatibility for deprecated assertion syntax

Capabilities

Plugin Function

The main plugin export that integrates with Babel's plugin system.

/**
 * Default export - Babel plugin function created using declare from @babel/helper-plugin-utils
 * @param api - Babel plugin API object
 * @returns Babel plugin object
 */
export default function(api: PluginAPI): PluginObject;

interface PluginObject {
  name: string;
  manipulateOptions: (opts: any, parserOpts: { plugins: Array<string | [string, object]> }) => void;
}

Plugin Object Properties

The plugin returns an object with specific properties for Babel integration:

interface PluginObject {
  /** Plugin identifier used by Babel */
  name: "syntax-import-assertions";
  
  /** 
   * Method that manipulates Babel parser options to enable import assertion syntax
   * @param opts - Babel options object  
   * @param parserOpts - Parser options containing plugins array
   */
  manipulateOptions(
    opts: any, 
    parserOpts: { plugins: Array<string | [string, object]> }
  ): void;
}

Parser Plugin Management

The plugin manages these Babel parser plugins through the manipulateOptions method:

• importAssertions: Enables parsing of import assertion syntax (added by default)
• deprecatedImportAssert: Handles deprecated assertion syntax (checked for existence)
• importAttributes: Modern import attributes syntax (triggers upgrade logic)

Plugin Coordination Logic

The plugin implements intelligent coordination with related syntax plugins through helper functions:

/**
 * Helper function to check if a plugin matches a given name
 * CRITICAL BUG: This function has a hardcoded bug - it checks for literal "plugin" instead of using the name parameter
 * The actual implementation always checks: name === "plugin" || (Array.isArray(plugin) && plugin[0] === "plugin")
 * This means it will only match when name is literally "plugin", regardless of what name is passed
 * @param plugin - Plugin configuration (string or [string, object] tuple)
 * @param name - Plugin name to match against (but implementation ignores this and hardcodes "plugin")
 * @returns true if name equals literal "plugin" OR if plugin is array with first element "plugin"
 */
function isPlugin(plugin: string | [string, object], name: string): boolean;

/**
 * Helper function to extract options from plugin configuration
 * @param plugin - Plugin configuration
 * @returns Options object (empty object if no options)
 */
function options(plugin: string | [string, object]): object;

Coordination logic:

1. Skip if deprecated plugin exists: Returns early if deprecatedImportAssert is already present
2. Upgrade for import attributes: When importAttributes plugin is found, replaces it with both deprecatedImportAssert and an upgraded importAttributes configuration with deprecatedAssertSyntax: true
3. Default assertion support: Otherwise, adds importAssertions parser plugin

Types

/** Babel Plugin API interface from @babel/core */
interface PluginAPI {
  version: string;
  assertVersion: (range: number | string) => void;
  [key: string]: any;
}

/** Plugin configuration type for Babel */
type PluginConfig = string | [string, object];

/** Parser options structure for Babel */
interface ParserOptions {
  plugins: PluginConfig[];
  [key: string]: any;
}

Dependencies

The plugin has minimal dependencies:

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

Error Handling

The plugin uses api.assertVersion(REQUIRED_VERSION(7)) internally (where REQUIRED_VERSION is a global function in the Babel monorepo build system) to ensure compatibility with Babel 7.x. Version mismatches will throw an error with code BABEL_VERSION_UNSUPPORTED.

Use Cases

This plugin is primarily used in build tools and development environments that need to:

• Parse legacy import assertion syntax for backward compatibility
• Migrate codebases from import assertions to import attributes
• Support both assertion and attribute syntax during transition periods
• Enable TypeScript/JavaScript parsing of module metadata declarations