@std/esm

@std/esm is a fast, small, zero-dependency package that enables ES modules (import/export syntax) in Node.js 6+ environments. It acts as a compatibility bridge between CommonJS and ES module systems, allowing developers to use modern JavaScript module syntax before native ES module support was widely available in Node.js.

Note: This package has been discontinued in favor of esm. This documentation covers version 0.26.0, the final release.

Package Information

• Package Name: @std/esm
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install @std/esm
• Node.js Support: Node 6+

Core Imports

// CJS bridge pattern
require = require("@std/esm")(module, options);

Basic Usage

There are three primary ways to enable ES modules with @std/esm:

// 1. CJS Bridge - most common pattern
// index.js
require = require("@std/esm")(module, options);
module.exports = require("./main.mjs").default;

# 2. CLI usage with -r flag
node -r @std/esm main.mjs

# 3. REPL usage
node -r @std/esm
# or after entering REPL:
# require("@std/esm")  // returns "@std/esm enabled"

Architecture

@std/esm is built around several key components:

• Module Bridge: Core function that creates enhanced require() with ES module support
• Hook System: Patches Node.js built-in modules (require, Module, vm, process) to handle ESM
• Configuration Engine: Flexible options system supporting package.json, RC files, and environment variables
• Context Detection: Automatically adapts behavior for CLI, REPL, eval, and other execution contexts
• Caching System: File-based bytecode caching with automatic invalidation for performance

Capabilities

Main Export Function

The package exports a single function that creates an enhanced require function with ES module support.

/**
 * Main export function that enables ES module support
 * @param {Object} module - The module object (typically 'module')
 * @param {Object} [options] - Configuration options
 * @returns {Function} Enhanced require function with ESM capabilities
 */
require("@std/esm")(module, options)

Module Bridge

Configuration System

Comprehensive configuration system supporting multiple sources and validation. Allows fine-tuned control over ES module behavior.

/**
 * Configuration options object
 */
const options = {
  // File processing mode
  mode: "mjs" | "js" | "all",
  
  // Enable caching or specify cache directory
  cache: true,  // boolean or string
  
  // Development options
  debug: false,     // boolean
  sourceMap: false, // boolean
  warnings: true,   // boolean
  
  // Enable top-level await (Node 7.6+)
  await: false,     // boolean
  
  // CJS compatibility features
  cjs: {
    cache: false,        // Store ES modules in require.cache
    extensions: false,   // Respect require.extensions in ESM
    interop: false,      // __esModule interoperability
    namedExports: false, // Import named exports of CJS modules
    paths: false,        // Follow CJS path rules in ESM
    topLevelReturn: false, // Allow top-level return
    vars: false          // Provide __dirname, __filename, require in ESM
  }
};

Configuration

Standard Features Supported

Out of the box, @std/esm supports all standard ES module features:

• Import/Export Statements: Full support for import and export syntax
• Dynamic Imports: Support for import() expressions
• Import Meta: Access to import.meta object
• Live Bindings: ES module live binding semantics
• File Extensions: Automatic handling of .mjs files as ES modules
• File URI Scheme: Support for file:// URLs
• Node.js Integration: Works with --eval, --print, and REPL
• Improved Errors: Enhanced error messages for module loading issues

Advanced Configuration

Detailed configuration options and patterns for complex use cases.

Configuration

Integration Examples

Practical examples for test frameworks, bundlers, and common Node.js tools.

Module Bridge