module и moduleResolution: как строка импорта становится файлом

Две настройки, две задачи

Когда видишь ERR_MODULE_NOT_FOUND в production на коде, который прошёл проверку типов, виновник почти всегда здесь: две настройки, которые выглядят связанными, но управляют совершенно разными вещами.

module решает, какой синтаксис генерирует TypeScript (require/exports для CommonJS, import/export для ES2020+). moduleResolution решает, по какому алгоритму спецификатор импорта превращается в файл на диске. Это раздельные вещи, и современный совет — задать module, а moduleResolution пусть следует из него:

{
  "compilerOptions": {
    "module": "nodenext",          // генерирует ESM или CJS по package.json "type"
    "moduleResolution": "nodenext" // разрешает так, как реально делает Node 16+
  }
}

Доступные режимы разрешения, от старых к новым:

Как идёт разрешение: bare-спецификаторы и exports

Для относительного импорта (./parser) резолвер пробует файлы рядом с импортирующим. Для bare-спецификатора (lodash, @scope/pkg) он поднимается по каталогам node_modules, затем смотрит в package.json пакета. При node16/nodenext/bundler он читает поле exports и выбирает цель, сопоставляя условия — import vs require, types, node, default:

// node_modules/@acme/sdk/package.json
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",   // выбран для ESM `import`
      "require": "./dist/index.cjs"   // выбран для CJS `require`
    }
  }
}

exports — это граница инкапсуляции: если путь не перечислен, его нельзя импортировать, даже если файл существует. import "@acme/sdk/internal/util" падает, если ./internal/util нет в exports. Старый режим node полностью игнорирует exports — именно поэтому пакет разрешается при node, но ломается при nodenext (или наоборот).

Неожиданное правило: .js-расширения в импортах TS

При node16/nodenext в ESM-файле импорт надо писать с расширением .js, хотя исходный файл — parser.ts:

// src/index.ts — ESM (package.json "type": "module")
import { parse } from "./parser.js"; // ✅ разрешает parser.ts, генерирует import "./parser.js"
import { parse } from "./parser";    // ❌ TS2835: относительный импорт требует расширения ".js"
import { parse } from "./parser.ts"; // ❌ TS5097: путь импорта не может оканчиваться на ".ts"

Ты пишешь расширение результата (.js), TypeScript проверяет по исходнику (.ts), а emit оставляет нетронутым, чтобы Node нашёл реальный файл в рантайме. Режим bundler отключает это требование, потому что бандлеры сами разрешают импорты без расширений.

Алиасы paths: tsc их проверяет, но не генерирует

baseUrl/paths позволяют писать import { db } from "@/db" вместо ../../../db. Критически важно: tsc разрешает их для проверки типов, но не переписывает в генерируемом JS — литеральная "@/db" остаётся в выводе. В рантайме Node понятия не имеет, что такое @/db.

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

Поэтому paths работает, только если что-то ещё переписывает алиас: бандлер (Vite, esbuild, webpack с подходящим resolve.alias) или загрузчик в рантайме (tsconfig-paths или поле imports в package.json). Классический сбой: проверки типов и сборка через dev-сервер проходят, а голый node dist/index.js бросает Cannot find module '@/db'.

Интероп: esModuleInterop и verbatimModuleSyntax

У CommonJS нет настоящего default-экспорта; module.exports = x — это присваивание всего пространства имён. esModuleInterop: true синтезирует default, чтобы import express from "express" работал против CJS-модуля, и генерирует хелперы __importDefault. Без него понадобилось бы import express = require("express") или import * as express.

verbatimModuleSyntax (TS 5.0, заменивший importsNotUsedAsValues и emit-половину забот isolatedModules) делает emit буквальным: обычный import/export генерируется как есть, а стираются только import type / export type. Это вынуждает явно указывать, что является type-only импортом — именно это нужно однофайловым транспиляторам:

import { type User, createUser } from "./user.js";
// emit: import { createUser } from "./user.js";  — `User` стёрт, `createUser` сохранён дословно