typescript 5.x

Complete instructions

TypeScript 5 development workflow

Use the project's installed compiler and scripts. This skill targets TypeScript 5.9.3; it does not imply compatibility with every 5.x release or the separate native-preview compiler.

Choose options for the host

Read the nearest package.json, the complete tsconfig extends chain, and the existing emitter before changing configuration. Preserve the package manager, supported runtimes, module format, and strictness policy.

NodeNext ESM source imports use the emitted extension, such as ./math.js, even when the source is math.ts. Bundler resolution permits extensionless relative imports; do not transfer that assumption into unbundled Node.js output.

TypeScript paths describes resolution for the compiler. It does not rewrite emitted imports or create runtime aliases. Configure the actual runtime/bundler when the application needs aliases.

These decisions follow the compiler-option guide and module-resolution reference.

Make a bounded change

Reproduce the diagnostic with the local compiler and the owning project's configuration. Use the existing typecheck script, or tsc -p <config> --noEmit when the project uses tsc directly. Passing source filenames directly to tsc bypasses normal tsconfig discovery.

Keep runtime data validation separate from TypeScript's compile-time guarantees. Use narrowing, discriminated unions, or type-only imports to express an existing contract. Do not hide a resolution or declaration defect behind any, an assertion, skipLibCheck, or a dependency upgrade.

When resolution is unclear, use tsc -p <config> --traceResolution for the failing import and inspect its selected package exports condition. Change the narrowest incorrect option or export, then repeat the owning check.

Check published declarations through exports

For a single ESM entrypoint, the package may expose:

{
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  }
}

Build first and ensure both files exist. A consumer must import the package by its public name, not by a source path that bypasses exports. Check the packaged files under the supported consumer resolution modes and execute the public JavaScript entrypoint in its advertised runtime.

Ship declaration dependencies required by consumers, rather than leaving them available only through a developer's local installation. The declaration-publishing guide describes how declarations and their dependencies travel with a package.

Declaration files must describe the corresponding JavaScript module format. Use matching .d.mts/.d.cts when those formats require separate declaration entrypoints. Dual ESM/CJS output needs checks of both exposed formats; one NodeNext consumer does not establish CJS compatibility.

For libraries bundled with external dependencies, check imports retained in declarations and JavaScript. Bundler-only source resolution can accept imports that break in Node.js consumers.

Referenced projects

Use the existing reference graph rather than replacing it with one broad source glob. Referenced projects normally use composite and emit declarations; a solution tsconfig can contain files: [] and references to the buildable projects. Run tsc -b <solution> for dependency-order builds. Use noEmit on a separate consumer check when appropriate, rather than removing outputs that downstream references require.

Inspect include, rootDir, outDir, declaration outputs, and build-info paths when a reference is stale or incomplete. Keep generated outputs separate from source. The project-reference guide explains the build contract.

Completion evidence

Report the compiler version, project configuration checked, and actual commands. For a library, include declaration consumption through exports and public runtime imports. Distinguish passing checks, expected negative diagnostics, and unchecked formats. Do not describe a successful build as proof of all supported platforms.