0
# Module Bridge
1

2
The module bridge is the core functionality of @std/esm that creates a CommonJS bridge enabling ES module syntax in Node.js environments. This is the primary interface that most developers will use.
3

4
## Capabilities
5

6
### Main Export Function
7

8
The @std/esm package exports a single function that creates an enhanced require function with ES module support.
9

10
```javascript { .api }
11
/**
12
 * Main export function that enables ES module support
13
 * @param {Object} module - The module object (typically 'module')
14
 * @param {Object} [options] - Configuration options
15
 * @returns {Function} Enhanced require function with ESM capabilities
16
 */
17
require("@std/esm")(module, options)
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
// Basic usage - enables .mjs files
24
require = require("@std/esm")(module);
25

26
// With options - enable .js files with ESM syntax
27
require = require("@std/esm")(module, { mode: "js" });
28

29
// Full CJS bridge pattern
30
require = require("@std/esm")(module, { cjs: true, mode: "js" });
31
module.exports = require("./main.mjs").default;
32
```
33

34
### REPL Integration
35

36
Special behavior when used in Node.js REPL environment.
37

38
```javascript { .api }
39
/**
40
 * REPL integration that returns a status message
41
 * @returns String message indicating @std/esm is enabled
42
 */
43
require("@std/esm"): "@std/esm enabled";
44
```
45

46
**Usage Examples:**
47

48
```bash
49
$ node -r @std/esm
50
> import { readFile } from 'fs';  // ES modules work directly
51

52
$ node
53
> require("@std/esm")
54
@std/esm enabled
55
> import { readFile } from 'fs';  // ES modules now work
56
```
57

58
### CLI Integration
59

60
Command-line integration using Node.js `-r` flag for preloading.
61

62
**Usage Examples:**
63

64
```bash
65
# Enable ESM for a specific file
66
node -r @std/esm main.mjs
67

68
# Works with any Node.js CLI options
69
node -r @std/esm --inspect main.mjs
70

71
# Can be combined with other preloaded modules
72
node -r @std/esm -r other-module main.mjs
73
```
74

75
### Test Framework Integration
76

77
Integration patterns for popular Node.js test frameworks.
78

79
**Usage Examples:**
80

81
```javascript
82
// AVA configuration (package.json)
83
{
84
  "ava": {
85
    "require": ["@std/esm"]
86
  }
87
}
88

89
// Mocha usage
90
mocha -r @std/esm test/**/*.mjs
91

92
// NYC coverage
93
nyc --require @std/esm mocha test/**/*.mjs
94

95
// Node-tap
96
node-tap --node-arg=-r --node-arg=@std/esm test/**/*.mjs
97

98
// PM2 process manager
99
pm2 start app.mjs --node-args="-r @std/esm"
100
```
101

102
## Context-Aware Behavior
103

104
The module bridge automatically detects execution context and adapts its behavior:
105

106
- **CJS Bridge**: When used with `module` parameter, creates enhanced require
107
- **CLI**: When preloaded with `-r`, enables ESM for the main script
108
- **REPL**: When used in REPL, enables ESM and returns status message
109
- **Eval**: When used in eval context, provides appropriate ESM support
110

111
## Performance Features
112

113
- **Bytecode Caching**: Compiled modules are cached to `.cache` directory for faster subsequent loads
114
- **Lazy Loading**: Hooks are applied only when needed to minimize startup overhead
115
- **V8 Optimization**: Uses V8 script caching for optimal performance