Modules, tsconfig and the build

Who does what

A common setup lets the bundler produce the JavaScript and runs tsc --noEmit as a separate step in CI (and often in a pre-push hook). The bundler stays fast, and the build still fails on type errors.

Writing code a per-file tool can compile

A tool that sees one file at a time can't know whether an imported name is a type or a value, or what value a const enum from another file has. Two settings report code it would get wrong:

• isolatedModules errors on constructs that need information from other files, such as re-exporting a type without export type.
• verbatimModuleSyntax (TypeScript 5.0) goes further: imports and exports are kept exactly as written unless marked type, so you write what you mean.

1import type { User } from "./types.js" // removed entirely from the output2import { formatName } from "./format.js" // kept: it's a value

erasableSyntaxOnly (5.8) adds the last piece for type-stripping tools: no enum, no namespace with values, no parameter properties, so removing types is all that is left to do.

module, moduleResolution and imports

These options don't change your code much; they tell the checker how the real host will find files, so that it accepts the imports that will work and rejects the ones that won't.

• "module": "nodenext", for code that Node runs directly. It follows Node's rules: a .js file is ESM or CommonJS according to package.json "type", and relative ES module imports need a file extension. You write the extension of the file that will exist at runtime (./util.js), and TypeScript maps it back to util.ts.
• "moduleResolution": "bundler" (with "module": "esnext"), for code that a bundler resolves. Extensionless imports and index files are fine, because the bundler allows them.

Other settings that commonly matter:

• target sets which JavaScript syntax the output may use; lib sets which built-in APIs the checker assumes exist (DOM for browsers). They are separate: a modern target does not add a polyfill for an API the browser lacks.
• outDir and rootDir decide where emitted files go; declaration emits .d.ts files for libraries.
• noEmit is for projects where another tool produces the JavaScript.

One tsconfig.json describes one environment. A repository with browser code, server code and tests usually needs several, connected with extends or project references, so that window isn't available in server code and process isn't assumed in the browser.