Babel Plugin Transform Import Meta

Babel Plugin Transform Import Meta is a Babel plugin that transforms ES2020 import.meta expressions into Node.js-compatible equivalents for environments that don't natively support import.meta. The plugin transforms four key properties: import.meta.url, import.meta.dirname, import.meta.filename, and import.meta.resolve().

Package Information

• Package Name: babel-plugin-transform-import-meta
• Package Type: npm
• Language: TypeScript
• Installation: npm install --save-dev babel-plugin-transform-import-meta

Core Imports

// Default import (plugin function)
import transformImportMetaPlugin from "babel-plugin-transform-import-meta";

With TypeScript types:

import transformImportMetaPlugin, { type PluginOptions } from "babel-plugin-transform-import-meta";

For CommonJS:

const transformImportMetaPlugin = require("babel-plugin-transform-import-meta");

Basic Usage

Add to your Babel configuration:

{
  "plugins": ["babel-plugin-transform-import-meta"]
}

With ES6 module output:

{
  "plugins": [
    ["babel-plugin-transform-import-meta", { "module": "ES6" }]
  ]
}

Architecture

The plugin implements a Babel visitor pattern that traverses the AST and transforms specific import.meta expressions:

• AST Traversal: Uses Babel's visitor pattern to identify import.meta expressions
• Selective Transformation: Only transforms known properties (url, dirname, filename, resolve)
• Module Format Support: Generates different output based on target module format (CommonJS vs ES6)
• Scope Safety: Automatically handles identifier conflicts by generating unique names
• Template-based Replacement: Uses @babel/template for reliable AST node generation

Capabilities

Plugin Function

The main default export is a Babel plugin function that returns a PluginObj for transforming import.meta expressions.

/**
 * Main Babel plugin function that transforms import.meta expressions
 * @returns PluginObj with visitor pattern for AST transformation
 */
export default function (): PluginObj;

Plugin Configuration

Configuration options for controlling the plugin's behavior.

export interface PluginOptions {
  /** Target module format for output code. Defaults to 'CommonJS' */
  module?: 'CommonJS' | 'ES6' | undefined;
}

Import Meta URL Transformation

Transforms import.meta.url to Node.js compatible file URL.

Input:

console.log(import.meta.url);

CommonJS Output:

console.log(require('url').pathToFileURL(__filename).toString());

ES6 Output:

import url from 'url';
console.log(url.pathToFileURL(__filename).toString());

Import Meta Dirname Transformation

Transforms import.meta.dirname to Node.js __dirname.

Input:

console.log(import.meta.dirname);

Output (both CommonJS and ES6):

console.log(__dirname);

Import Meta Filename Transformation

Transforms import.meta.filename to Node.js __filename.

Input:

console.log(import.meta.filename);

Output (both CommonJS and ES6):

console.log(__filename);

Import Meta Resolve Transformation

Transforms import.meta.resolve(specifier) to Node.js require.resolve() wrapped with URL conversion. Supports both regular and optional chaining calls.

Input:

console.log(import.meta.resolve('./module'));
console.log(import.meta.resolve?.('./optional-module'));

CommonJS Output:

console.log(require('url').pathToFileURL(require.resolve('./module')).toString());
console.log(require('url').pathToFileURL(require.resolve('./optional-module')).toString());

ES6 Output:

import { createRequire } from 'module';
import url from 'url';
console.log(url.pathToFileURL(createRequire(url.pathToFileURL(__filename).toString()).resolve('./module')).toString());
console.log(url.pathToFileURL(createRequire(url.pathToFileURL(__filename).toString()).resolve('./optional-module')).toString());

Plugin Behavior

Module Output Modes

The plugin supports two target module formats:

1. CommonJS (default): Uses require() statements for dependencies
2. ES6: Uses import statements, automatically injected at the top of the file

Scope Safety

The plugin implements scope safety features:

• Generates unique identifiers when url or createRequire conflict with existing scope variables
• Only transforms known import.meta properties (url, dirname, filename, resolve)
• Leaves unknown properties untouched for compatibility with other plugins

Example with scope conflicts:

// Input
const url = '123';
const createRequire = () => {};
console.log(import.meta.resolve('./module'));

// ES6 Output
import { createRequire as _createRequire } from 'module';
import _url from 'url';
const url = '123';
const createRequire = () => {};
console.log(_url.pathToFileURL(_createRequire(_url.pathToFileURL(__filename).toString()).resolve('./module')).toString());

Error Handling

The plugin validates configuration options and throws descriptive errors for invalid configurations.

Error thrown for invalid module option:

Error: Invalid target, must be one of: "CommonJS" or "ES6"

Untransformed Properties

The plugin preserves compatibility by:

• Not transforming import.meta without property access
• Not transforming unknown properties like import.meta.customProperty
• Not transforming non-meta properties like foo.import.meta

Examples that remain unchanged:

console.log(import.meta); // Unchanged
console.log(import.meta.customProperty); // Unchanged
console.log(foo.import.meta); // Unchanged

Types

export interface PluginOptions {
  /** Target module format for output code. Defaults to 'CommonJS' */
  module?: 'CommonJS' | 'ES6' | undefined;
}

interface PluginObj {
  name: string;
  visitor: {
    Program(path: NodePath, state: { opts?: PluginOptions }): void;
  };
}

interface NodePath {
  node: any;
  scope: {
    getAllBindings(): Record<string, any>;
    generateUidIdentifier(name: string): { name: string };
  };
  traverse(visitors: object): void;
  replaceWith(node: any): void;
}

Dependencies

Runtime Dependencies

• @babel/template: ^7.25.9
• tslib: ^2.8.1

Peer Dependencies

• @babel/core: ^7.10.0