@babel/plugin-syntax-top-level-await

@babel/plugin-syntax-top-level-await is a Babel syntax plugin that enables parsing of top-level await expressions in JavaScript modules. It provides minimal functionality focused purely on extending Babel's parser to recognize top-level await syntax, making it essential for modern JavaScript applications that use async operations at the module level.

Package Information

• Package Name: @babel/plugin-syntax-top-level-await
• Package Type: npm
• Language: JavaScript (ES6)
• Installation: npm install --save-dev @babel/plugin-syntax-top-level-await

Core Imports

// Default import (CommonJS)
const syntaxTopLevelAwait = require("@babel/plugin-syntax-top-level-await");

// Default import (ES6) 
import syntaxTopLevelAwait from "@babel/plugin-syntax-top-level-await";

Basic Usage

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

// Or with custom options (though this plugin accepts no options)
module.exports = {
  plugins: [
    ["@babel/plugin-syntax-top-level-await", {}]
  ]
};

Once configured, your JavaScript modules can use top-level await:

// module.js - This syntax becomes parseable with the plugin
const data = await fetch('/api/data').then(r => r.json());
const config = await import('./config.js');

export { data, config };

Capabilities

Plugin Factory Function

The main export is a Babel plugin factory function created using @babel/helper-plugin-utils.

/**
 * Default export: Creates a Babel plugin that enables top-level await syntax parsing
 * @param {Object} api - Babel API object with version assertion capabilities
 * @param {Function} api.assertVersion - Method to assert minimum Babel version (called with version 7)
 * @returns {BabelPlugin} Plugin object with name and manipulateOptions method
 */
export default function(api);

interface BabelPlugin {
  /** Plugin identifier used by Babel */
  name: string;
  /** 
   * Babel plugin hook that modifies parser options to enable top-level await
   * @param {Object} opts - Babel transformation options object
   * @param {Object} parserOpts - Babel parser options object (modified in-place)
   */
  manipulateOptions(opts, parserOpts): void;
}

Usage Example:

import syntaxTopLevelAwait from "@babel/plugin-syntax-top-level-await";

// The plugin is typically used via Babel configuration
// but can be instantiated directly for advanced use cases
const babelApi = { 
  assertVersion: (version) => { 
    // Asserts minimum required Babel version (throws if < version)
    if (parseInt(version) > 7) throw new Error("Babel version too old");
  } 
};
const plugin = syntaxTopLevelAwait(babelApi);

console.log(plugin.name); // "syntax-top-level-await"

Plugin Properties

The plugin object returned by the factory function contains:

interface BabelPlugin {
  /** 
   * Plugin identifier string constant
   * Value: "syntax-top-level-await"
   */
  name: "syntax-top-level-await";

  /**
   * Parser options manipulation method
   * Adds "topLevelAwait" to the parser plugins array to enable syntax recognition
   * @param {Object} opts - Babel transformation options (unused)
   * @param {Object} parserOpts - Parser options object with plugins array
   */
  manipulateOptions(opts: Object, parserOpts: { plugins: string[] }): void;
}

Architecture

This plugin follows the minimal Babel syntax plugin pattern:

• Plugin Factory: Uses @babel/helper-plugin-utils declare function for standardized plugin creation
• Parser Integration: Modifies parser options by adding "topLevelAwait" to the plugins array
• Syntax-Only: Provides no transformations, only enables parsing of the top-level await syntax
• Zero Configuration: Accepts no options and requires no additional setup beyond installation

The plugin's manipulateOptions method is called during Babel's initialization phase to configure the parser before any code is processed. This allows the parser to recognize top-level await expressions as valid syntax rather than throwing parsing errors.

The plugin uses the declare utility from @babel/helper-plugin-utils which provides the standardized Babel plugin factory pattern with automatic version checking via api.assertVersion(7).

Dependencies

// External dependency used internally
import { declare } from "@babel/helper-plugin-utils";

Runtime Dependencies:

• @babel/helper-plugin-utils: Provides the declare utility for creating Babel plugins with version checking

Peer Dependencies:

• @babel/core: Babel compiler core (version ^7.0.0-0)

Error Handling

This plugin is syntax-only and does not perform transformations, so it typically does not throw runtime errors. However, standard Babel plugin errors may occur:

• Version Mismatch: If used with incompatible Babel versions (< 7.0.0)
• Parser Errors: If the module contains invalid top-level await usage (e.g., await outside module context)

The plugin itself does not validate await usage - it only enables the parser to recognize the syntax. Actual validation is handled by Babel's parser and other plugins in the transformation pipeline.