or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-esm

ECMAScript module loader that enables ES module syntax in Node.js 6+ without Babel or bundling

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/esm@3.2.x

To install, run

npx @tessl/cli install tessl/npm-esm@3.2.0

ESM

ESM is the world's most advanced ECMAScript module loader. This fast, production-ready, zero-dependency loader enables ES module syntax in Node.js 6+ without requiring Babel or bundling. It provides seamless interoperability between CommonJS and ES modules with extensive configuration options.

Package Information

Package Name: esm
Package Type: npm
Language: JavaScript
Installation: npm install esm
Repository: https://github.com/standard-things/esm

Core Imports

// Main import
const esm = require("esm");

// Create enhanced require function
require = require("esm")(module);

// With options
require = require("esm")(module, options);

Basic Usage

// Method 1: Package-level setup (recommended)
// index.js
require = require("esm")(module)
module.exports = require("./main.js")

// main.js - now supports ES module syntax
import { readFile } from "fs";
import path from "path";
export const myFunction = () => "Hello ES modules!";

// Method 2: CLI usage
// node -r esm main.js

// Method 3: REPL usage
// node -r esm

Architecture

ESM works by providing an enhanced require function that can load both CommonJS and ES modules:

Module Loader: Patches Node.js module system to understand ES syntax
Parser Integration: Uses Acorn parser to detect ES module syntax
Live Bindings: Maintains proper ES module live binding semantics
Compatibility Layer: Provides seamless interoperability between module systems
Caching System: Integrates with Node.js module cache for performance
Hook System: Installs hooks for module, require, vm, and process objects

Capabilities

Main Loader Function

Creates an enhanced require function with ES module support.

/**
 * Create an enhanced require function with ES module support
 * @param {Object} module - The CommonJS module object (usually `module`)
 * @param {ESMOptions|string} [options] - Configuration options or mode string
 * @returns {Function} Enhanced require function with ES module loading capabilities
 */
function esmLoader(module, options);

Usage Examples:

// Basic usage
require = require("esm")(module);

// With string mode
require = require("esm")(module, "auto");

// With configuration object
require = require("esm")(module, {
  mode: "auto",
  cjs: true,
  await: false
});

// Now load ES modules
const myModule = require("./es-module.js");

Configuration Options

Complete configuration object for customizing loader behavior.

/**
 * ESM loader configuration options
 */
interface ESMOptions {
  /** CJS interoperability settings */
  cjs?: boolean | CJSOptions;
  /** Package.json fields to check when importing */
  mainFields?: string[];
  /** Module detection mode */
  mode?: "auto" | "all" | "strict";
  /** Enable top-level await support (Node 10+) */
  await?: boolean;
  /** Apply options to all module loads */
  force?: boolean;
  /** Enable WebAssembly module support (Node 8+) */
  wasm?: boolean;
  /** Cache directory path or toggle */
  cache?: boolean | string;
  /** Include inline source maps */
  sourceMap?: boolean;
}

/**
 * CommonJS interoperability configuration
 */
interface CJSOptions {
  /** Store ES modules in require.cache */
  cache?: boolean;
  /** Remove dangling .default access */
  dedefault?: boolean;
  /** Enable __esModule interoperability */
  esModule?: boolean;
  /** Respect require.extensions in ESM */
  extensions?: boolean;
  /** Enable mutable namespace objects */
  mutableNamespace?: boolean;
  /** Import named exports of CJS modules */
  namedExports?: boolean;
  /** Follow CJS path rules in ESM */
  paths?: boolean;
  /** Enable top-level return support */
  topLevelReturn?: boolean;
  /** Provide __dirname, __filename, require in ESM */
  vars?: boolean;
}

Configuration Examples:

// Auto mode with full CJS compatibility (recommended)
require = require("esm")(module, {
  mode: "auto",
  cjs: true
});

// Custom CJS interop settings
require = require("esm")(module, {
  mode: "auto",
  cjs: {
    cache: true,
    namedExports: true,
    vars: true,
    esModule: false
  }
});

// All files as ES modules
require = require("esm")(module, {
  mode: "all",
  force: true
});

Mode Configuration

Module detection and processing modes.

/**
 * Module detection modes
 */
type ModuleMode = "auto" | "all" | "strict";

/**
 * - "strict": Only .mjs files are treated as ES modules
 * - "auto": Detect ES modules by syntax (import/export/import.meta/"use module") or .mjs extension  
 * - "all": All files except those with "use script" directive or .cjs extension are ES modules
 */

Mode Examples:

// Strict mode - only .mjs files
require = require("esm")(module, "strict");

// Auto mode - detect by syntax
require = require("esm")(module, "auto");

// All mode - assume ES modules
require = require("esm")(module, "all");

Environment Configuration

External configuration through environment variables and config files.

/**
 * Environment configuration options
 */
interface EnvironmentConfig {
  /** ESM_OPTIONS: JSON6 configuration string or config file path */
  ESM_OPTIONS?: string;
  /** ESM_DISABLE_CACHE: Disable caching when truthy */
  ESM_DISABLE_CACHE?: string;
}

Environment Examples:

# JSON6 configuration
export ESM_OPTIONS='{"mode":"auto","cjs":true}'

# Config file path
export ESM_OPTIONS="./config/esm-config.json"

# Disable caching
export ESM_DISABLE_CACHE=true

# Then run
node -r esm main.js

Config file formats:

// .esmrc.js
module.exports = {
  mode: "auto",
  cjs: true
};

// .esmrc.json
{
  "mode": "auto", 
  "cjs": true
}

// package.json
{
  "esm": {
    "mode": "auto",
    "cjs": true
  }
}

Advanced Features

Enhanced capabilities and integrations.

/**
 * Advanced feature flags
 */
interface AdvancedFeatures {
  /** Top-level await support (Node 10+) */
  await?: boolean;
  /** WebAssembly module support (Node 8+) */
  wasm?: boolean;
  /** Force options on all loads */
  force?: boolean;
  /** Source map generation */
  sourceMap?: boolean;
}

Advanced Examples:

// Enable top-level await
require = require("esm")(module, {
  mode: "auto",
  await: true,
  cjs: true
});

// WebAssembly support
require = require("esm")(module, {
  mode: "auto",
  wasm: true
});

// Force all modules through ESM
require = require("esm")(module, {
  mode: "auto",
  force: true,
  sourceMap: true
});

Error Handling

ESM throws standard Node.js module errors and includes specific validation:

// Invalid module parameter
try {
  require("esm")("not-a-module");
} catch (error) {
  // ERR_INVALID_ARG_TYPE: The "module" argument must be of type object
}

// Module syntax errors are reported normally
try {
  require("./invalid-syntax.js");
} catch (error) {
  // SyntaxError with file location and details
}

Integration Patterns

Testing Frameworks

// Jest
require = require("esm")(module);

// Mocha
// mocha --require esm test/**/*.js

// AVA
// ava --require esm test/**/*.js

Development Tools

// Webpack
module.exports = {
  resolve: {
    mainFields: ["module", "main"]
  }
};

// Package.json for bundlers
{
  "main": "index.js",
  "module": "main.js"
}

Supported Features

✅ ES Module import/export statements
✅ Dynamic import() expressions
✅ import.meta object support
✅ Live bindings between modules
✅ File URI scheme support
✅ Node.js CLI integration (--eval, --print, --check)
✅ REPL support
✅ Full CommonJS interoperability
✅ WebAssembly module loading (Node 8+)
✅ Top-level await (Node 10+)
✅ Source map support
✅ Yarn PnP integration
✅ Multiple configuration sources