CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-std--esm

Enable ES modules in Node.js 6+ environments with zero dependencies and full CommonJS compatibility

—

Pending
Overview
Eval results
Files

configuration.mddocs/

Configuration

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

Capabilities

Main Options Interface

Core configuration options for controlling ES module behavior.

/**
 * Configuration options object for @std/esm
 */
const options = {
  // File processing mode - which files to treat as ES modules
  mode: "mjs",  // "mjs" | "js" | "all"
  
  // Enable caching or specify cache directory
  cache: true,  // boolean or string path
  
  // Enable debug mode with unmasked stack traces
  debug: false,
  
  // Include inline source maps
  sourceMap: false,
  
  // Enable development warnings
  warnings: true,
  
  // Enable top-level await in modules without exports (Node 7.6+)
  await: false,
  
  // Enable CJS features in ESM
  cjs: false  // boolean or CjsOptions object
};

CJS Compatibility Options

Detailed CommonJS compatibility options when cjs is enabled.

/**
 * CJS compatibility options when cjs is enabled
 */
const cjsOptions = {
  // Store ES modules in require.cache
  cache: false,
  
  // Respect require.extensions in ESM
  extensions: false,
  
  // Enable __esModule interoperability
  interop: false,
  
  // Import named exports from CJS modules
  namedExports: false,
  
  // Follow CJS path resolution rules
  paths: false,
  
  // Allow top-level return statements
  topLevelReturn: false,
  
  // Provide __dirname, __filename, require in ESM
  vars: false
};

Option Processing

Static method for normalizing and validating configuration options.

/**
 * Normalizes and validates configuration options
 * @param options - Raw options object
 * @returns Standardized configuration object
 */
Package.createOptions(options: any): EsmOptions;

Default Options

Default configuration values used when options are not specified.

Package.defaultOptions: {
  mode: "mjs",
  cache: true,
  debug: false,
  sourceMap: undefined,
  warnings: process.env.NODE_ENV !== "production",
  await: false,
  cjs: false
}

Configuration Sources

Function Parameter

Direct options passed to the main function.

Usage Examples:

// Enable .js files with ESM syntax
require = require("@std/esm")(module, { mode: "js" });

// Enable CJS compatibility with detailed options
require = require("@std/esm")(module, {
  mode: "js",
  cjs: {
    cache: true,
    interop: true,
    namedExports: true,
    vars: true
  }
});

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

Package.json Field

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

Usage Examples:

{
  "name": "my-app",
  "@std/esm": "js"
}
{
  "name": "my-app",
  "@std/esm": "cjs"
}
{
  "name": "my-app",
  "@std/esm": {
    "mode": "js",
    "cjs": true,
    "cache": "./custom-cache",
    "warnings": false
  }
}

RC Files

Configuration files in various formats for project-specific settings.

Supported RC Files:

  • .esmrc - JSON6 format (JSON with comments and trailing commas)
  • .esmrc.json - Standard JSON format
  • .esmrc.js - CommonJS module exporting configuration
  • .esmrc.mjs - ES module exporting configuration

Usage Examples:

.esmrc (JSON6):

{
  "mode": "js",
  "cjs": {
    cache: true,
    interop: true,
    namedExports: true
  },
  // Enable source maps for debugging
  "sourceMap": true
}

.esmrc.js (CommonJS):

module.exports = {
  mode: "js",
  cjs: {
    cache: true,
    interop: true,
    namedExports: true
  }
};

.esmrc.mjs (ES Module):

export default {
  mode: "js",
  cjs: {
    cache: true,
    interop: true,
    namedExports: true
  }
};

Environment Variable

Global configuration using the ESM_OPTIONS environment variable.

Usage Examples:

# JSON6 format
export ESM_OPTIONS='{"mode":"js","cjs":true}'

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

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

Mode Options

Mode: "mjs" (Default)

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

require = require("@std/esm")(module, { mode: "mjs" });
// Processes: main.mjs, utils.mjs
// Ignores: main.js, utils.js (treated as CommonJS)

Mode: "js"

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

require = require("@std/esm")(module, { mode: "js" });
// Processes: main.mjs, main.js, utils.mjs, utils.js

Mode: "all"

Process all files as ES modules regardless of extension.

require = require("@std/esm")(module, { mode: "all" });
// Processes: any file as ES module

Configuration Shortcuts

String Shortcuts

Convenient string shortcuts for common configurations.

// Shortcut for { mode: "js" }
"@std/esm": "js"

// Shortcut for { cjs: true, mode: "js" }
"@std/esm": "cjs"

Priority Order

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

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

Install with Tessl CLI

npx tessl i tessl/npm-std--esm

docs

configuration.md

index.md

module-bridge.md

tile.json