ESM & Module Resolution

ESM Semantics in TypeScript

ESM is statically analyzed: imports are hoisted, bindings are live, and this at module top level is undefined. TypeScript mirrors that with import/export and erases types at emit — but how it emits depends on module:

{
  "type": "module",
  "compilerOptions": { "module": "nodenext", "moduleResolution": "nodenext" }
}

With nodenext, Node decides the format from type and file extension: .ts beside "type": "module" emits ESM. Relative specifiers must carry .js (import { f } from "./f.js") because Node does not guess extensions — the file on disk is what gets loaded.

Resolution Options and Path Aliases

Match resolution to the loader:

{ "moduleResolution": "nodenext" }  // Node ESM/CJS, honors "exports"
{ "moduleResolution": "bundler" }   // Vite/webpack: extensionless, alias-driven
{ "moduleResolution": "node10" }    // legacy node_modules walking only

Bare specifiers resolve through the dependency's exports map under nodenext; a package that only ships main may fail there while working under bundler. Aliases come from paths:

{ "paths": { "@ui/*": ["./src/ui/*"] } }

Vite needs a matching resolve.alias, Jest needs moduleNameMapper, and Node needs an import map or a re-barrel — otherwise types compile while runtime resolution fails.

Pitfalls and Interview Angles

Extension-less imports compile under bundler and crash under Node ESM with ERR_MODULE_NOT_FOUND. Keep the strictest resolution the deployment uses.

Dual package hazard. Shipping both ESM and CJS builds can load two module instances — one for import, one for require — breaking instanceof and singletons. Exports maps with import/require conditions plus a shared state module (or ESM-only) avoid it.

CJS globals vanish. __dirname and require do not exist in ESM; use import.meta.url and dynamic import().

Interview: walk a specifier from source through exports conditions to a loaded module, then explain why createRequire is a symptom, not a fix.