ES Modules FAQ & Common Questions

ES Modules (ESM) are the official standardized module system for JavaScript, introduced in ECMAScript 2015. They use import and export statements to share code between files. Unlike older systems like CommonJS, ES Modules are statically analyzable, support tree-shaking, use live bindings, enforce strict mode, and work natively in browsers, Node.js, Deno, and Bun.

ES Modules offer several advantages over CommonJS:

• Tree-shaking - Dead code elimination for smaller bundles
• Static analysis - Better tooling, IDE support, and error detection
• Live bindings - References instead of value copies
• Browser native - Works without a bundler
• Async loading - Non-blocking module loading
• Universal standard - Same syntax everywhere

Yes, all modern browsers support ES Modules: Chrome 61+, Firefox 60+, Safari 10.1+, and Edge 16+. This covers over 95% of global browser usage. For legacy browsers, use the nomodule fallback attribute on script tags to serve a bundled version:

<script type="module" src="app.js"></script>
<script nomodule src="app-legacy.js"></script>

It depends on the environment:

• Node.js (recommended) - Use .js with "type": "module" in package.json
• Node.js (per-file) - Use .mjs for individual ESM files
• Browser - Any extension works (MIME type matters, not extension)
• TypeScript - Use .ts / .tsx regardless

Adding type="module" to a script tag tells the browser to treat the script as an ES Module. This enables:

• import/export syntax
• Deferred execution by default (like the defer attribute)
• Strict mode enforcement
• CORS requirements for cross-origin scripts
• Module scope (no global variable pollution)
• Each module is only executed once regardless of how many times it is imported

<script type="module">
  import { greet } from './utils.js';
  greet('World'); // Module scope - no global pollution
</script>

ES Modules are always fetched with CORS (Cross-Origin Resource Sharing) for security. Unlike classic scripts, module scripts cannot be loaded from cross-origin sources without proper CORS headers. This prevents sensitive data leakage through module imports. CDNs serving ESM code must include Access-Control-Allow-Origin headers. This is why CDNs like esm.sh, jspm.io, and unpkg include CORS headers by default.

Import maps are a browser feature that lets you control how module specifiers are resolved. They map bare specifiers like 'lodash' to actual URLs:

<script type="importmap">
{
  "imports": {
    "lodash": "https://esm.sh/[email protected]"
  }
}
</script>
<script type="module">
  import { debounce } from 'lodash'; // Just works!
</script>

Use them for: bundler-free development, CDN-based imports, prototyping, or when you want npm-style imports without a build step. Supported in all modern browsers.

Dynamic imports use the import() function syntax, which returns a Promise resolving to the module's namespace object:

// Lazy load on user action
button.addEventListener('click', async () => {
  const { showChart } = await import('./chart.js');
  showChart(data);
});

// Conditional loading
const i18n = await import(`./locales/${lang}.js`);

// With error handling
try {
  const mod = await import('./optional-feature.js');
  mod.init();
} catch {
  console.log('Feature not available');
}

Unlike static imports, dynamic imports can appear anywhere in code and accept computed strings. They enable code splitting and lazy loading for better performance.

Two approaches:

// Option 1 (recommended): Add to package.json
{ "type": "module" }
// Now all .js files are treated as ESM

// Option 2: Use .mjs extension
// Rename files to .mjs for per-file ESM
// math.mjs, utils.mjs, etc.

The "type": "module" approach is recommended for new projects. Node.js 16+ has stable ESM support; Node.js 24+ is the current LTS with full ESM maturity.

Yes! Starting with Node.js 22 (behind a flag) and enabled by default in Node.js 23+:

// In a CommonJS file (.cjs or no "type": "module")
const { add } = require('./math.mjs'); // Works in Node 23+!

// Limitation: Does NOT work if the ESM module
// uses top-level await. Use dynamic import() instead:
const mod = await import('./async-module.mjs');

This greatly simplifies the CJS/ESM interop story and makes gradual migration much easier.

Use import attributes (stable in Node.js 22+, standardized in ES2025):

// Recommended: Import attributes (ES2025)
import config from './config.json' with { type: 'json' };

// Workaround for older Node.js:
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const config = require('./config.json');

// Or read manually:
import { readFile } from 'node:fs/promises';
const config = JSON.parse(
  await readFile(new URL('./config.json', import.meta.url), 'utf8')
);

// Node.js 21.2+ (recommended)
console.log(import.meta.dirname);   // /path/to/directory
console.log(import.meta.filename);  // /path/to/file.js

// Older Node.js (manual derivation)
import { fileURLToPath } from 'node:url';
import { dirname } from 'node:path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

Choose based on your target environment:

• "bundler" (TS 5.0+) - For projects using Vite, webpack, esbuild, etc. Most lenient, extensions optional.
• "nodenext" - For pure Node.js projects. Requires .js extensions in imports. Understands package.json exports.
• "node" (legacy) - Avoid. Does not understand ESM resolution or package.json exports.

// tsconfig.json for most projects
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2022"
  }
}

When using "moduleResolution": "nodenext", TypeScript requires .js extensions in imports even for .ts source files:

// You write this in TypeScript:
import { foo } from './utils.js'; // .js, not .ts!

// TypeScript compiles the import specifier as-is
// Node.js ESM requires explicit extensions to resolve files
// The .js refers to the compiled output file

With "moduleResolution": "bundler", extensions are optional because bundlers handle resolution. This is the simpler option if you use a build tool.

Yes, multiple options exist:

# Node.js 24+ (built-in type stripping)
node script.ts

# Node.js 22-23 (experimental flag)
node --experimental-strip-types script.ts

# Deno (native TypeScript)
deno run script.ts

# Bun (native TypeScript)
bun run script.ts

# tsx (works on any Node.js version)
npx tsx script.ts

Note that Node.js type stripping only removes type annotations - it does not support TypeScript features that require transformation like enums or namespaces.

Not always. You can go bundler-free for:

• Small projects and prototypes
• Internal tools with modern browser requirements
• Projects using import maps with CDN-hosted dependencies

However, bundlers still provide significant value for production: tree-shaking removes unused code, code splitting creates optimal chunks, minification reduces file sizes, and fewer HTTP requests improve loading performance for large dependency trees. For most production applications, Vite is the recommended bundler.

Recommendations by use case:

• Vite - Best for most web apps. ESM dev server + Rollup production builds.
• Rollup / tsup - Best for library authors. Clean ESM output, excellent tree-shaking.
• Rspack - Best for large apps migrating from webpack. Rust-based, 10x faster.
• esbuild - Fastest raw bundling. Great for scripts and simple projects.

Avoid configuring webpack from scratch for new ESM projects - Vite or Rspack are better starting points.

Vitest is recommended for ESM projects:

• Native ES Module support - no configuration needed
• Built-in module mocking with vi.mock() (auto-hoisted)
• API-compatible with Jest (easy migration)
• Fast HMR-based watch mode via Vite

Jest's ESM support is still experimental and requires NODE_OPTIONS='--experimental-vm-modules'. Module mocking uses the unstable jest.unstable_mockModule() API. For existing Jest projects, migration to Vitest is typically straightforward.

Migrate when:

• Starting a new project (always use ESM)
• Your dependencies are mostly ESM-compatible
• You want tree-shaking for smaller bundles
• You are upgrading to Node.js 18+

Do not rush migration for stable production CJS codebases. Node.js 23+ require(esm) means CJS and ESM can coexist indefinitely. Migrate at your own pace.

Yes, several tools can help automate the conversion:

• cjs-to-esm - Codemod that transforms require() to import and module.exports to export
• jscodeshift - General-purpose codemod framework with ESM transform recipes
• Biome - Modern linter/formatter with ESM migration suggestions

Automated tools handle the common patterns well, but you will still need to manually address: dynamic require() calls, __dirname/__filename replacements, conditional require(), and package.json updates.

Yes, gradual migration is the recommended approach for large codebases:

• Per-file approach: Use .mjs extension for new ESM files while keeping existing .js files as CJS
• Dual exports: Publish packages with both ESM and CJS entry points using package.json conditional exports
• require(esm): Node.js 23+ lets CJS code consume your newly converted ESM modules directly via require()

// package.json - dual entry points
{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}