Skip to content

TypeScript tooling: strict mode, modules, TS 7

A TypeScript project is configured once and lived with for years, and a few tsconfig.json settings decide most of the experience: how strict the checker is, how imports are resolved, whether files can be run without a build step, and how a large repository is split so it builds quickly. This hub covers those decisions. It assumes you have read the Modules and compilation tutorial, which introduces tsc and tsconfig.json.

The defaults changed a lot recently. TypeScript 6.0 (March 2026), the last compiler written in JavaScript, turned strict on by default, made module default to esnext and target to the newest ECMAScript edition, set types to [], and deprecated a long list of legacy options. TypeScript 7.0 (July 2026), the compiler rewritten in Go, removed those deprecated options. Everything on this page was checked with TypeScript 7.0.2 and Node.js 22.

Topic Since Decide this when
Strict mode strict 2.3; default since 6.0 Always: it decides how many bugs the compiler catches.
Module settings nodenext 4.7; bundler 5.0 You choose between Node.js, a bundler or another runtime.
Type-only imports and erasable syntax 3.8, 5.0 and 5.8 Other tools, or Node.js itself, strip your types instead of tsc.
Project references TypeScript 3.0 A repository grows into several packages or slow builds.
TypeScript 7 July 2026 You upgrade the compiler, or depend on its API.

The strict option arrived in TypeScript 2.3 and is true by default since TypeScript 6.0. It is a switch for a family of checks; in TypeScript 7.0 that family is noImplicitAny, noImplicitThis, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, strictBuiltinIteratorReturn and useUnknownInCatchVariables. (alwaysStrict, formerly part of the family, is now always on: setting it to false was deprecated in 6.0.) You can turn individual checks off, but each one you disable is a category of bug the compiler stops reporting. New TypeScript versions may add checks to the family, so an upgrade can surface new errors.

A few valuable checks are deliberately not in strict, because they require more code changes: noUncheckedIndexedAccess (index reads include undefined), exactOptionalPropertyTypes (? does not accept an explicit undefined), noImplicitOverride and noFallthroughCasesInSwitch. The tsconfig.json that tsc --init writes in TypeScript 7.0 turns on the first two along with strict. For a new project, keep them on; for an existing one, enable them one at a time.

This file compiles with "strict": false and fails four ways under the default:

interface Order {
id: string;
couponCode?: string;
total: number;
}
class PriceList {
currency: string;
prices = new Map<string, number>();
}
function applyCoupon(order: Order, rates) {
const code = order.couponCode.toUpperCase();
return order.total * (1 - rates[code]);
}
try {
applyCoupon({ id: "ORD-1", total: 40 }, { WELCOME10: 0.1 });
} catch (error) {
console.log(error.message);
}
pricing.ts(8,3): error TS2564: Property 'currency' has no initializer and is not definitely assigned in the constructor.
pricing.ts(12,36): error TS7006: Parameter 'rates' implicitly has an 'any' type.
pricing.ts(13,16): error TS18048: 'order.couponCode' is possibly 'undefined'.
pricing.ts(20,15): error TS18046: 'error' is of type 'unknown'.

Each error is a real bug: an unset field, an unchecked parameter, a crash when the order has no coupon, and a catch that assumes the thrown value is an Error. Compiled with "strict": false, it runs and the catch prints Cannot read properties of undefined (reading 'toUpperCase').

Pitfalls:

  • Migrating with strict: false forever. To adopt it in a large codebase, enable strict and add the remaining errors to a tracked list, or enable the checks one by one, starting with strictNullChecks and noImplicitAny.
  • Relying on the default. Write "strict": true explicitly; tools that read tsconfig.json with older assumptions, and readers, then see the intent.

The module option tells the compiler which module system the output and the runtime use, and moduleResolution how import specifiers are found. TypeScript 4.7 added node16 and nodenext, which model Node.js exactly, and 5.0 added bundler for code processed by Vite, esbuild, webpack and similar tools; module: "preserve" (TypeScript 5.4) pairs with it. TypeScript 6.0 deprecated the old node10 (formerly node) and classic resolution modes and the amd, umd and systemjs module formats, and 7.0 removed them, along with baseUrl.

The choice follows the runtime:

Code runs in Settings
Node.js, compiled by tsc or type stripping "module": "nodenext" (implies moduleResolution: nodenext)
A bundler or a framework’s build "module": "preserve" or "esnext" with "moduleResolution": "bundler"
A library published to npm "module": "nodenext", so it works for both Node.js and bundler consumers

Under nodenext, TypeScript follows Node.js rules: a file is an ES module or CommonJS according to its extension (.mts, .cts) or the nearest package.json "type", and relative imports in ES modules need a file extension. You write the extension of the output file, ./money.js, even though the source is money.ts, because the import is emitted unchanged. Writing import { formatMoney } from "./money"; fails:

error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './money.js'?

A starting tsconfig.json for a Node.js service in 2026 (JSON with comments, which tsc accepts):

{
"compilerOptions": {
"target": "es2024",
"module": "nodenext",
"rootDir": "src",
"outDir": "dist",
"types": ["node"],
"strict": true,
"noUncheckedIndexedAccess": true,
"verbatimModuleSyntax": true,
"skipLibCheck": true
},
"include": ["src"]
}

Pitfalls:

  • bundler resolution for Node.js code. It accepts extensionless imports that Node.js cannot load, so the build passes and the service fails at start-up.
  • Path aliases are types only. paths tells the compiler where @orders/domain lives; the runtime or bundler needs the same mapping (Node.js imports with # specifiers, or bundler aliases).
  • Upgrading to 7.0 with removed options. "moduleResolution": "node" or "baseUrl" now stops the build with error TS5108 or error TS5102; migrate on 6.0 first, where they are only deprecation warnings.

Most TypeScript syntax is erased at compile time, but a few features generate code: enum, namespace with values, parameter properties and import =. Fast tools such as esbuild, SWC and Node.js compile one file at a time without type information, which makes two things matter: knowing whether an import is only a type, and avoiding syntax that cannot simply be erased.

import type { Order } from "./order.js" (TypeScript 3.8) is always removed from the output; TypeScript 4.5 added the inline form import { type Order, createOrder }. verbatimModuleSyntax (TypeScript 5.0) makes the rule simple: imports without type are kept exactly as written, imports with type are dropped, and the compiler reports an error when a type is imported without type. That is what single-file tools assume.

erasableSyntaxOnly (TypeScript 5.8) reports every construct that is not just erasable. It exists for Node.js type stripping: Node.js runs .ts files directly by removing type annotations, enabled by default since Node.js 23.6 and 22.18. It does not type-check and does not support enums or parameter properties, so you still run tsc --noEmit in CI.

// app.ts: runs directly with `node app.ts` on Node.js 22.18 or later
import type { IncomingMessage } from "node:http";
type OrderStatus = "pending" | "paid"; // a union instead of an enum
const STATUS = { Pending: "pending", Paid: "paid" } as const satisfies Record<string, OrderStatus>;
function label(status: OrderStatus, req?: IncomingMessage): string {
return `${status.toUpperCase()}${req ? ` for ${req.url}` : ""}`;
}
console.log(label(STATUS.Paid), Object.values(STATUS).length);

Output of node app.ts (and of node app.js after tsc):

PAID 2

An enum Status { Paid } in the same file fails in both places: tsc --erasableSyntaxOnly reports error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled., and node app.ts throws SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode.

Pitfalls:

  • Type stripping does not rewrite imports. Under Node.js type stripping you import ./order.ts, not ./order.js; enable rewriteRelativeImportExtensions (TypeScript 5.7) if the same code is also compiled with tsc.
  • Side-effect imports. With verbatimModuleSyntax, import { Order } from "./order.js" for a type is an error rather than silently dropped; fix it with import type.

Project references arrived in TypeScript 3.0. A large repository is split into several projects, each with its own tsconfig.json; a project marked "composite": true can be referenced by others with "references". Running tsc -b (build mode) builds the projects in dependency order and, using .tsbuildinfo files, skips any project whose inputs have not changed since the last build. Editors also load only the declaration output of referenced projects, which keeps large monorepos responsive.

References also enforce architecture: a project can import only from projects it references, so a domain package cannot accidentally depend on the web layer. In a workspace (npm, pnpm or Yarn), packages usually import each other by package name; the paths below use relative imports to stay self-contained.

packages/domain/tsconfig.json
{
"compilerOptions": {
"composite": true,
"rootDir": "src",
"outDir": "dist",
"module": "nodenext",
"strict": true
},
"include": ["src"]
}
packages/api/tsconfig.json
{
"compilerOptions": { "rootDir": "src", "outDir": "dist", "module": "nodenext", "strict": true },
"include": ["src"],
"references": [{ "path": "../domain" }]
}
// tsconfig.json at the repository root: builds everything with `tsc -b`
{
"files": [],
"references": [{ "path": "packages/domain" }, { "path": "packages/api" }]
}

With packages/domain/src/order.ts exporting Order and orderTotal, and packages/api/src/report.ts importing them from ../../domain/dist/order.js, tsc -b builds domain first, then api; node packages/api/dist/report.js prints 2 orders, total 55.50 EUR. A second tsc -b with no changes reports Project 'packages/domain/tsconfig.json' is up to date and does no work.

Pitfalls:

  • composite requires declarations. It turns on declaration, and every file must be matched by include or files.
  • Use tsc -b at the root. Without -b, tsc does not build referenced projects first or skip up-to-date ones.

TypeScript 7.0, released in July 2026 (7.0.2 is the current release as of November 2026, with 7.1 in beta), is the native port of the compiler and language service to Go, developed as “Project Corsa”. It is installed and run as before, npm install -D typescript and tsc, and it was built to report the same type errors as TypeScript 6.0 while running as native code instead of JavaScript, for much faster builds and editor responses.

Three things change for a project. First, every option deprecated in TypeScript 6.0 is gone; using one is an error (error TS5108: Option 'target=ES5' has been removed.). Second, the programmatic compiler API of the JavaScript compiler, import ts from "typescript", is not available in the same form: the 7.0 package exposes only experimental entry points under typescript/unstable/*, so tools built on the old API, such as some linters, code generators and bundler plugins, may need to stay on 6.0 for now. Third, the editor experience comes from the new native language server.

The upgrade path is therefore: move to TypeScript 6.0 first, fix every deprecation warning, then switch to 7.0. TypeScript 6.0.3 is the last 6.x release and can be installed side by side for tools that need the old API.

Terminal window
npm view typescript version # 7.0.2 at the time of writing
npm install -D typescript@6 # step 1: migrate and fix deprecations on 6.0
npx tsc --noEmit
npm install -D typescript@7 # step 2: switch to the native compiler
npx tsc --noEmit

Pitfalls:

  • ignoreDeprecations: "6.0" only postpones. It silences 6.0 warnings, but 7.0 rejects the options regardless.
  • Check tools, not just tsc. Anything that imports the typescript package API can break on 7.0 even when tsc succeeds.
  • Keep strict on, add noUncheckedIndexedAccess and noImplicitOverride for new code.
  • Pick nodenext for Node.js and libraries, bundler with preserve for bundled front ends.
  • Turn on verbatimModuleSyntax everywhere, and erasableSyntaxOnly if any tool or Node.js strips types.
  • Split into referenced projects once a single tsc run is slow or the dependency rules between parts matter.
  • Upgrade to TypeScript 7 through 6.0, and check every tool that uses the compiler API.

What does "strict": true enable, and what does it leave out? The strict family: noImplicitAny, noImplicitThis, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, strictBuiltinIteratorReturn and useUnknownInCatchVariables. It leaves out stricter options that need more code changes, such as noUncheckedIndexedAccess, exactOptionalPropertyTypes and noImplicitOverride. Since TypeScript 6.0, strict is on by default.

Why do you write ./money.js when importing money.ts under nodenext? TypeScript does not rewrite import specifiers when it emits JavaScript, and Node.js ES modules require full relative paths. The specifier must therefore name the output file. The compiler maps ./money.js back to money.ts for type checking.

What problem does verbatimModuleSyntax solve? It makes import elision predictable: imports marked type are removed, all others are kept as written. Single-file compilers such as esbuild, SWC and Node.js type stripping cannot know whether an import is a type, so this rule lets them produce the same output as tsc.

Which TypeScript features cannot run under Node.js type stripping? Features that generate JavaScript rather than being erased: enum, namespaces with runtime code, parameter properties, import = and export =, and angle-bracket type assertions. erasableSyntaxOnly reports them at compile time.

What are project references for? Splitting a codebase into separately built projects with explicit dependencies. tsc -b builds them in order and skips unchanged ones, editors load referenced projects’ declarations instead of their sources, and a project cannot import from one it does not reference.

Senior scenario: OrdersPortal’s monorepo has 400,000 lines of TypeScript on 5.9, a 9-minute type-check in CI, moduleResolution: node and baseUrl path aliases, and a code generator built on the compiler API. How would you plan the move to TypeScript 7? First upgrade to 6.0 and work through the deprecations: replace node resolution with nodenext or bundler, convert baseUrl aliases to paths with explicit prefixes or package.json imports, set types and rootDir explicitly, and resolve the new default errors. Split the repository into referenced projects if it is not already, so CI builds incrementally. Then switch type-checking to 7.0 while pinning 6.0.3 for the code generator, since the 7.0 API is still unstable, and plan to move the generator when a stable API ships. Measure CI before and after so the team sees the result.