0
# @std/esm
1

2
@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.
3

4
**Note**: This package has been discontinued in favor of [`esm`](https://www.npmjs.com/package/esm). This documentation covers version 0.26.0, the final release.
5

6
## Package Information
7

8
- **Package Name**: @std/esm
9
- **Package Type**: npm
10
- **Language**: JavaScript (Node.js)
11
- **Installation**: `npm install @std/esm`
12
- **Node.js Support**: Node 6+
13

14
## Core Imports
15

16
```javascript
17
// CJS bridge pattern
18
require = require("@std/esm")(module, options);
19
```
20

21
## Basic Usage
22

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

25
```javascript
26
// 1. CJS Bridge - most common pattern
27
// index.js
28
require = require("@std/esm")(module, options);
29
module.exports = require("./main.mjs").default;
30
```
31

32
```bash
33
# 2. CLI usage with -r flag
34
node -r @std/esm main.mjs
35

36
# 3. REPL usage
37
node -r @std/esm
38
# or after entering REPL:
39
# require("@std/esm")  // returns "@std/esm enabled"
40
```
41

42
## Architecture
43

44
@std/esm is built around several key components:
45

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

52
## Capabilities
53

54
### Main Export Function
55

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

58
```javascript { .api }
59
/**
60
 * Main export function that enables ES module support
61
 * @param {Object} module - The module object (typically 'module')
62
 * @param {Object} [options] - Configuration options
63
 * @returns {Function} Enhanced require function with ESM capabilities
64
 */
65
require("@std/esm")(module, options)
66
```
67

68
[Module Bridge](./module-bridge.md)
69

70
### Configuration System
71

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

74
```javascript { .api }
75
/**
76
 * Configuration options object
77
 */
78
const options = {
79
  // File processing mode
80
  mode: "mjs" | "js" | "all",
81
  
82
  // Enable caching or specify cache directory
83
  cache: true,  // boolean or string
84
  
85
  // Development options
86
  debug: false,     // boolean
87
  sourceMap: false, // boolean
88
  warnings: true,   // boolean
89
  
90
  // Enable top-level await (Node 7.6+)
91
  await: false,     // boolean
92
  
93
  // CJS compatibility features
94
  cjs: {
95
    cache: false,        // Store ES modules in require.cache
96
    extensions: false,   // Respect require.extensions in ESM
97
    interop: false,      // __esModule interoperability
98
    namedExports: false, // Import named exports of CJS modules
99
    paths: false,        // Follow CJS path rules in ESM
100
    topLevelReturn: false, // Allow top-level return
101
    vars: false          // Provide __dirname, __filename, require in ESM
102
  }
103
};
104
```
105

106
[Configuration](./configuration.md)
107

108
### Standard Features Supported
109

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

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

121
### Advanced Configuration
122

123
Detailed configuration options and patterns for complex use cases.
124

125
[Configuration](./configuration.md)
126

127
### Integration Examples
128

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

131
[Module Bridge](./module-bridge.md)