CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-babel--plugin-syntax-import-attributes

Babel syntax plugin that enables parsing of ES2022 import attributes in JavaScript/TypeScript code

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

@babel/plugin-syntax-import-attributes

@babel/plugin-syntax-import-attributes is a Babel syntax plugin that enables parsing of ES2022 import attributes (formerly import assertions) in JavaScript/TypeScript code. It allows the JavaScript parser to understand the 'with' syntax for specifying metadata about imported modules, such as import foo from './module.js' with { type: 'json' }.

Package Information

  • Package Name: @babel/plugin-syntax-import-attributes
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev @babel/plugin-syntax-import-attributes

Core Imports

// ES Modules (recommended)
import plugin from "@babel/plugin-syntax-import-attributes";

CommonJS (legacy support):

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

Note: This plugin is typically not imported directly in user code. Instead, it's configured in Babel configuration files as shown in the Basic Usage section.

Basic Usage

Babel Configuration

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

With options:

// babel.config.js
module.exports = {
  plugins: [
    ["@babel/plugin-syntax-import-attributes", {
      deprecatedAssertSyntax: true
    }]
  ]
};

Enabling Import Attributes Syntax

Once the plugin is configured, you can use import attributes in your code:

// Modern syntax (default)
import config from './config.json' with { type: 'json' };
import styles from './styles.css' with { type: 'css' };

// With deprecatedAssertSyntax: true, also supports legacy syntax
import legacyConfig from './legacy.json' assert { type: 'json' };

Architecture

The plugin operates by:

  1. Parser Integration: Modifies Babel's parser options to recognize import attribute syntax
  2. Generator Configuration: Sets the default keyword for import attributes to "with"
  3. Legacy Support: Optionally enables parsing of the deprecated "assert" syntax
  4. Conflict Resolution: Automatically removes conflicting importAssertions plugin if present

Capabilities

Plugin Factory Function

Main plugin function that creates a Babel plugin object with import attributes support.

/**
 * Default export: Babel plugin function for parsing import attributes
 * Created via declare() from @babel/helper-plugin-utils
 * @param api - Babel plugin API object  
 * @param options - Plugin configuration options (destructured as { deprecatedAssertSyntax })
 * @param dirname - Plugin directory path
 * @returns Babel plugin object with name and manipulateOptions method
 */
export default function(
  api: PluginAPI, 
  options: Options,
  dirname: string
): PluginObject;

interface Options {
  /** Enable support for deprecated 'assert' syntax alongside 'with' syntax */
  deprecatedAssertSyntax?: boolean;
}

interface PluginObject {
  /** Plugin identifier used by Babel */
  name: "syntax-import-attributes";
  /** Method called to configure parser and generator options */
  manipulateOptions(opts: { parserOpts: any; generatorOpts: any }): void;
}

Plugin Name

Identifier constant for the Babel plugin.

const name: "syntax-import-attributes";

Options Configuration

Configuration interface for plugin behavior.

interface Options {
  /**
   * Enable support for deprecated 'assert' syntax alongside 'with' syntax
   * When true, allows parsing both:
   * - import foo from './file.js' with { type: 'json' }
   * - import foo from './file.js' assert { type: 'json' }
   * @default false
   */
  deprecatedAssertSyntax?: boolean;
}

Parser/Generator Configuration

The plugin configures Babel's parser and generator through the manipulateOptions method:

  • Generator Options: Sets importAttributesKeyword to "with" for output generation
  • Parser Plugins: Adds appropriate plugins based on configuration:
    • Default: "importAttributes"
    • With deprecated syntax: "deprecatedImportAssert" and ["importAttributes", { deprecatedAssertSyntax: true }]
  • Conflict Resolution: Removes existing "importAssertions" plugin if present

Error Handling

The plugin validates configuration and provides clear error messages:

/** 
 * Thrown when deprecatedAssertSyntax option is provided but not a boolean
 */
class ConfigurationError extends Error {
  message: "'deprecatedAssertSyntax' must be a boolean, if specified.";
}

Version Compatibility

The plugin requires Babel version ^7.22.0 or higher, enforced internally via api.assertVersion() call.

Types

interface PluginAPI {
  /** Babel version string */
  version: string;
  /** Assert minimum Babel version requirement */
  assertVersion(range: string): void;
}

interface ParserOptions {
  /** Array of parser plugins to enable */
  plugins: Array<string | [string, any]>;
}

interface GeneratorOptions {
  /** Keyword to use for import attributes in generated code */
  importAttributesKeyword?: string;
}

docs

index.md

tile.json