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

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:

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

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

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.