module & moduleResolution: how an import string becomes a file

Two settings, two jobs

When you see ERR_MODULE_NOT_FOUND in production on code that type-checked fine, the culprit is almost always here: two settings that look related but control completely different things.

module decides the syntax TypeScript emits (require/exports for CommonJS, import/export for ES2020+). moduleResolution decides the algorithm that turns an import specifier into a file on disk. They are separate, and the modern advice is to set module and let moduleResolution follow from it:

{
  "compilerOptions": {
    "module": "nodenext",          // emit ESM or CJS per package.json "type"
    "moduleResolution": "nodenext" // resolve the way Node 16+ actually does
  }
}

The available resolution modes, oldest to newest:

How resolution walks: bare specifiers and exports

For a relative import (./parser) the resolver tries files next to the importer. For a bare specifier (lodash, @scope/pkg) it walks up node_modules directories, then consults the package’s package.json. Under node16/nodenext/bundler it reads the exports field and picks a target by matching conditions — import vs require, types, node, default:

// node_modules/@acme/sdk/package.json
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",   // chosen for ESM `import`
      "require": "./dist/index.cjs"   // chosen for CJS `require`
    }
  }
}

exports is an encapsulation boundary: if a path isn’t listed, it can’t be imported, even if the file exists. import "@acme/sdk/internal/util" fails unless ./internal/util is in exports. The old node mode ignores exports entirely, which is exactly why a package resolves under node but breaks under nodenext (or vice-versa).

The surprising rule: .js extensions on TS imports

Under node16/nodenext, in an ESM file you must write the import with a .js extension even though the source file is parser.ts:

// src/index.ts — ESM (package.json "type": "module")
import { parse } from "./parser.js"; // ✅ resolves parser.ts, emits import "./parser.js"
import { parse } from "./parser";    // ❌ TS2835: relative import needs ".js" extension
import { parse } from "./parser.ts"; // ❌ TS5097: an import path can't end with ".ts"

You write the output extension (.js), TypeScript checks against the source (.ts), and the emit is left untouched so Node finds the real file at runtime. bundler mode turns this requirement off because bundlers resolve extensionless imports themselves.

paths aliases: tsc checks them, doesn’t emit them

baseUrl/paths let you write import { db } from "@/db" instead of ../../../db. Critically, tsc resolves these for type-checking but does not rewrite them in emitted JS — the literal "@/db" is left in the output. At runtime, Node has no idea what @/db is.

{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["src/*"] } } }

So paths only works if something else rewrites the alias: a bundler (Vite, esbuild, webpack with a matching resolve.alias), or a runtime loader (tsconfig-paths, or a package.json imports field). The classic failure: type-checks and bundles fine via the dev server, then a plain node dist/index.js throws Cannot find module '@/db'.

Interop: esModuleInterop and verbatimModuleSyntax

CommonJS has no real default export; module.exports = x is a whole-namespace assignment. esModuleInterop: true synthesises a default so import express from "express" works against a CJS module, and emits __importDefault helpers. Without it you’d need import express = require("express") or import * as express.

verbatimModuleSyntax (TS 5.0, replacing importsNotUsedAsValues and the emit half of isolatedModules concerns) makes emit literal: a regular import/export is emitted as-is, and only import type / export type are erased. This forces you to be explicit about what’s a type-only import, which is exactly what single-file transpilers need:

import { type User, createUser } from "./user.js";
// emit: import { createUser } from "./user.js";  — `User` erased, `createUser` kept verbatim