0
# Configuration
1

2
@std/esm provides a comprehensive configuration system that supports multiple sources and allows fine-tuned control over ES module behavior. Configuration can be provided through function parameters, package.json fields, RC files, or environment variables.
3

4
## Capabilities
5

6
### Main Options Interface
7

8
Core configuration options for controlling ES module behavior.
9

10
```javascript { .api }
11
/**
12
 * Configuration options object for @std/esm
13
 */
14
const options = {
15
  // File processing mode - which files to treat as ES modules
16
  mode: "mjs",  // "mjs" | "js" | "all"
17
  
18
  // Enable caching or specify cache directory
19
  cache: true,  // boolean or string path
20
  
21
  // Enable debug mode with unmasked stack traces
22
  debug: false,
23
  
24
  // Include inline source maps
25
  sourceMap: false,
26
  
27
  // Enable development warnings
28
  warnings: true,
29
  
30
  // Enable top-level await in modules without exports (Node 7.6+)
31
  await: false,
32
  
33
  // Enable CJS features in ESM
34
  cjs: false  // boolean or CjsOptions object
35
};
36
```
37

38
### CJS Compatibility Options
39

40
Detailed CommonJS compatibility options when `cjs` is enabled.
41

42
```javascript { .api }
43
/**
44
 * CJS compatibility options when cjs is enabled
45
 */
46
const cjsOptions = {
47
  // Store ES modules in require.cache
48
  cache: false,
49
  
50
  // Respect require.extensions in ESM
51
  extensions: false,
52
  
53
  // Enable __esModule interoperability
54
  interop: false,
55
  
56
  // Import named exports from CJS modules
57
  namedExports: false,
58
  
59
  // Follow CJS path resolution rules
60
  paths: false,
61
  
62
  // Allow top-level return statements
63
  topLevelReturn: false,
64
  
65
  // Provide __dirname, __filename, require in ESM
66
  vars: false
67
};
68
```
69

70
### Option Processing
71

72
Static method for normalizing and validating configuration options.
73

74
```javascript { .api }
75
/**
76
 * Normalizes and validates configuration options
77
 * @param options - Raw options object
78
 * @returns Standardized configuration object
79
 */
80
Package.createOptions(options: any): EsmOptions;
81
```
82

83
### Default Options
84

85
Default configuration values used when options are not specified.
86

87
```javascript { .api }
88
Package.defaultOptions: {
89
  mode: "mjs",
90
  cache: true,
91
  debug: false,
92
  sourceMap: undefined,
93
  warnings: process.env.NODE_ENV !== "production",
94
  await: false,
95
  cjs: false
96
}
97
```
98

99
## Configuration Sources
100

101
### Function Parameter
102

103
Direct options passed to the main function.
104

105
**Usage Examples:**
106

107
```javascript
108
// Enable .js files with ESM syntax
109
require = require("@std/esm")(module, { mode: "js" });
110

111
// Enable CJS compatibility with detailed options
112
require = require("@std/esm")(module, {
113
  mode: "js",
114
  cjs: {
115
    cache: true,
116
    interop: true,
117
    namedExports: true,
118
    vars: true
119
  }
120
});
121

122
// Disable caching for development
123
require = require("@std/esm")(module, { cache: false });
124
```
125

126
### Package.json Field
127

128
Configuration stored in package.json under the "@std/esm" field.
129

130
**Usage Examples:**
131

132
```json
133
{
134
  "name": "my-app",
135
  "@std/esm": "js"
136
}
137
```
138

139
```json
140
{
141
  "name": "my-app",
142
  "@std/esm": "cjs"
143
}
144
```
145

146
```json
147
{
148
  "name": "my-app",
149
  "@std/esm": {
150
    "mode": "js",
151
    "cjs": true,
152
    "cache": "./custom-cache",
153
    "warnings": false
154
  }
155
}
156
```
157

158
### RC Files
159

160
Configuration files in various formats for project-specific settings.
161

162
**Supported RC Files:**
163
- `.esmrc` - JSON6 format (JSON with comments and trailing commas)
164
- `.esmrc.json` - Standard JSON format
165
- `.esmrc.js` - CommonJS module exporting configuration
166
- `.esmrc.mjs` - ES module exporting configuration
167

168
**Usage Examples:**
169

170
**.esmrc (JSON6):**
171
```json
172
{
173
  "mode": "js",
174
  "cjs": {
175
    cache: true,
176
    interop: true,
177
    namedExports: true
178
  },
179
  // Enable source maps for debugging
180
  "sourceMap": true
181
}
182
```
183

184
**.esmrc.js (CommonJS):**
185
```javascript
186
module.exports = {
187
  mode: "js",
188
  cjs: {
189
    cache: true,
190
    interop: true,
191
    namedExports: true
192
  }
193
};
194
```
195

196
**.esmrc.mjs (ES Module):**
197
```javascript
198
export default {
199
  mode: "js",
200
  cjs: {
201
    cache: true,
202
    interop: true,
203
    namedExports: true
204
  }
205
};
206
```
207

208
### Environment Variable
209

210
Global configuration using the ESM_OPTIONS environment variable.
211

212
**Usage Examples:**
213

214
```bash
215
# JSON6 format
216
export ESM_OPTIONS='{"mode":"js","cjs":true}'
217

218
# File path reference
219
export ESM_OPTIONS="./custom-esm-config.json"
220

221
# Run with environment variable
222
ESM_OPTIONS='{"mode":"js"}' node -r @std/esm main.mjs
223
```
224

225
## Mode Options
226

227
### Mode: "mjs" (Default)
228

229
Only process .mjs files as ES modules, treat .js files as CommonJS.
230

231
```javascript
232
require = require("@std/esm")(module, { mode: "mjs" });
233
// Processes: main.mjs, utils.mjs
234
// Ignores: main.js, utils.js (treated as CommonJS)
235
```
236

237
### Mode: "js"
238

239
Process both .mjs and .js files as ES modules.
240

241
```javascript
242
require = require("@std/esm")(module, { mode: "js" });
243
// Processes: main.mjs, main.js, utils.mjs, utils.js
244
```
245

246
### Mode: "all"
247

248
Process all files as ES modules regardless of extension.
249

250
```javascript
251
require = require("@std/esm")(module, { mode: "all" });
252
// Processes: any file as ES module
253
```
254

255
## Configuration Shortcuts
256

257
### String Shortcuts
258

259
Convenient string shortcuts for common configurations.
260

261
```javascript
262
// Shortcut for { mode: "js" }
263
"@std/esm": "js"
264

265
// Shortcut for { cjs: true, mode: "js" }
266
"@std/esm": "cjs"
267
```
268

269
## Priority Order
270

271
Configuration sources are resolved in the following priority order (highest to lowest):
272

273
1. Function parameter options
274
2. ESM_OPTIONS environment variable  
275
3. Local RC files (.esmrc, .esmrc.json, .esmrc.js, .esmrc.mjs)
276
4. package.json "@std/esm" field
277
5. Default options