typescript-knowledge-patch

TypeScript Knowledge Patch

Use this guide when upgrading compiler configuration, choosing module settings, adopting the native compiler, or repairing newly exposed type and JavaScript checking errors. Follow the linked references when a migration needs all edge cases and compatibility details.

Reference index

Reference	Topics
Configuration, modules, and project migration	Generated configs, changed defaults, module modes, resolution, removed options, syntax migrations, and explicit-file compilation
JavaScript and JSDoc migration	Parameter checking, removed JSDoc forms, constructor functions, variadics, overloads, expandos, CommonJS, and declaration emit
Native compiler and tooling	Stable and preview packages, compiler API compatibility, editor support, emit/watch limits, worker controls, build concurrency, and hover tooling
Types and standard libraries	Buffer typing, inference changes, ES2025, Temporal, collection upserts, iterable DOM declarations, and Unicode template inference

Migration-first quick reference

Re-pin configuration that relied on old defaults

Compiler defaults now favor modern, strict projects. Audit every inherited or omitted option before accepting an upgrade:

Setting	New behavior	Typical migration action
`strict`	Defaults to `true`	Fix strictness errors or explicitly preserve the old value temporarily
`module`	Defaults to `esnext`	Choose a runtime-appropriate mode explicitly
`target`	Floats with the current year and is currently `es2025`	Pin a target when reproducible output matters
`noUncheckedSideEffectImports`	Defaults to `true`	Add declarations for intentional side-effect-only imports
`libReplacement`	Defaults to `false`	Set `true` only when replacement library packages are required
`rootDir`	Defaults to the `tsconfig.json` directory	Set the previous source root explicitly to preserve output paths
`types`	Omission behaves like `[]`	List global packages such as `node` or `jest` explicitly

Imported declarations still work when types is empty. Use types: ["*"] only as a temporary compatibility bridge for automatic global @types discovery.

Replace retired resolution and emit choices

Old choice	Replacement or action
`moduleResolution: "node"` or `"node10"`	Use `bundler`, `nodenext`, or `node20`
Classic module resolution	Migrate; it is removed
`module: "amd"`, `"umd"`, `"systemjs"`, or `"none"`	Move to a supported ESM or CommonJS strategy
`outFile`	Use per-module output and a bundler when one artifact is needed
`target: "es5"`	Target at least ES2015
Explicit `downlevelIteration`	Remove the deprecated setting and validate emitted iteration behavior
`baseUrl` as a bare-import search root	Remove it and put config-relative prefixes directly in `paths`

ignoreDeprecations: "6.0" is only a temporary bridge for options that are still deprecated rather than removed. Do not build a long-term configuration around it.

Update syntax whose legacy form now errors

namespace Utilities {
  export const ready = true;
}

import data from "./data.json" with { type: "json" };
const lazyData = import("./data.json", { with: { type: "json" } });

Replace module Foo {} with namespace Foo {}. Ambient declare module "name" declarations remain supported.
Replace static and dynamic import assertions with with attributes.
Replace /// <reference no-default-lib="true"/> with noLib or libReplacement configuration.
Remove attempts to disable esModuleInterop, allowSyntheticDefaultImports, or strict-mode semantics.

Preserve project layout and config intent

An omitted rootDir in a project config now means the config directory, not the inferred common source directory. Pin it when using outDir:

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["./src"]
}

Running tsc file.ts beside a tsconfig.json reports TS5112 because named files would otherwise bypass the config. Use the project normally, or use tsc --ignoreConfig file.ts when default compilation is intentional.

Repair typed-array and backing-buffer errors

Do not assume that a typed array or Node.js Buffer is an ArrayBuffer. Update @types/node first for Buffer failures, then make the backing type or conversion explicit:

declare function consume(value: ArrayBuffer): void;

const bytes: Uint8Array<ArrayBuffer> = new Uint8Array([1, 2, 3]);
consume(bytes.buffer);

Review APIs mentioning ArrayBufferLike, BufferSource, or Uint8Array<ArrayBufferLike> rather than hiding the error with a cast.

Keep API-dependent tools on a compatible compiler

The native compiler does not implement the JavaScript typescript compiler API. Type-check with the native compiler, but keep the compatibility package for linters, formatters, or extensions that import that API:

{
  "devDependencies": {
    "@typescript/native": "npm:typescript@^7.0.2",
    "typescript": "npm:@typescript/typescript6@^6.0.2"
  }
}

This alias gives API-dependent tools the package name they expect while the native compiler remains separately addressable.

Module selection

Project shape	Recommended settings
Node.js 20 with pinned semantics	`module: "node20"`; the implied target is `es2023` unless overridden
Node.js tracking current behavior	`module: "nodenext"`; its implied target floats at `esnext`
Bundled ESM	Prefer `module: "preserve"` with `moduleResolution: "bundler"`
CommonJS during a resolver migration	`module: "commonjs"` with `moduleResolution: "bundler"` is supported

Both nodenext and bundler resolution understand package imports entries beginning with #/:

{
  "imports": { "#/*": "./dist/*" }
}

Deferred module evaluation

import defer loads a module graph but postpones evaluation until code first reads an export. It accepts only a namespace import and is emitted unchanged:

import defer * as feature from "./feature.js";

feature.start(); // first export access triggers evaluation

Use module: "preserve" or "esnext", and confirm that the runtime or bundler supports the emitted syntax.

Standard-library additions

target and lib accept es2025; the target adds no syntax transforms, while its library contains APIs including RegExp.escape.
Temporal declarations are available through an esnext target, the esnext library, or the granular esnext.temporal library.
Map and WeakMap expose getOrInsert and getOrInsertComputed in esnext; the computed callback runs only for a missing key.
lib.dom.d.ts now contains iterable and async-iterable DOM declarations, so listing dom.iterable or dom.asynciterable is unnecessary.

Inference checks

If an upgrade changes a generic result, first add explicit type arguments or annotations. Inference now prevents type variables from escaping their scope, and methods that do not use this can contribute to inference earlier.

For migration comparisons, tsc --stableTypeOrdering aligns type and property ordering with the native checker. It can slow checking substantially, so use it diagnostically and repair order-sensitive inference rather than enabling it by default.

Native build controls

--checkers N sets experimental checker workers; the default is 4. Use a fixed count for reproducibility or --checkers 1 to serialize checking.
--builders N sets concurrent project builds under --build. Its concurrency multiplies with --checkers, so budget memory for the product.
--singleThreaded disables parallel parsing, checking, and emit.

Use Native compiler and tooling for package selection, preview limitations, nightly installs, and editor settings.

JavaScript migration checkpoint

JavaScript checking now follows TypeScript-shaped rules more closely. Treat any, unknown, and undefined parameters as required unless the source makes them optional; use typeof when a JSDoc type refers to a value; replace legacy constructor functions with classes; and use real rest parameters for variadic functions. See JavaScript and JSDoc migration before switching a JavaScript-heavy project to the native checker.