typescript-expert

TypeScript Expert

Use the project's installed TypeScript version and runtime/toolchain constraints as the source of truth. This guidance was checked against TypeScript 7.0.2, the stable latest release on 2026-08-29. When “latest” matters, verify the current stable tag and official release notes instead of relying on this date.

Canonical sources:

• TypeScript Handbook
• TSConfig Reference
• Official TypeScript releases
• Official TypeScript release blog

Working Method

1. Inspect package.json, the lockfile, all applicable tsconfig*.json files and extends chains before recommending code or configuration.
2. Determine the actual compiler used by the failing command. Framework checkers such as vue-tsc, svelte-check, Angular, Astro, and MDX tooling may embed or constrain a different TypeScript version.
3. Reproduce the diagnostic with the project's existing script and local dependency. Do not silently download or substitute the newest compiler.
4. Fix the earliest root cause with the smallest runtime-preserving change. Re-run the same command; use a focused compile or type test only as additional evidence.
5. Report the compiler version, command, result, and any remaining baseline or compatibility limitation.

When the user asks for an upgrade, read modern TypeScript releases before editing. TypeScript 7 is the current stable CLI/compiler, but it does not yet expose a stable programmatic API and is not a drop-in replacement for every tool that embeds TypeScript. Keep compatible tooling on TypeScript 6 where the official 7.0 guidance requires it.

Decision Rules

• Prefer inference for local values; annotate public boundaries when the annotation documents intent or catches implementation drift.
• Accept untrusted values as unknown, validate or narrow them at runtime, and keep the validated type aligned with the runtime check.
• Prefer discriminated unions for states, overloads for a small finite call surface, and generics only when they preserve a real relationship between inputs and outputs.
• Treat as, non-null assertions, any, @ts-ignore, and broad ambient declarations as evidence to investigate. Use a narrow assertion only when an invariant is established outside the type system and explain that invariant.
• Prefer @ts-expect-error over @ts-ignore only for an intentional, tested negative case or documented upstream limitation. Do not use either to make an ordinary type-check pass.
• Do not change runtime behavior merely to satisfy a type unless the existing runtime behavior is itself the bug.
• Do not recommend compiler flags in isolation. Choose module, moduleResolution, target, lib, emit settings, and file selection as one configuration for the actual runtime or bundler.
• Preserve framework-generated options and project references. Do not replace an existing tsconfig with a generic template.
• For libraries, validate declaration emit and consumer module resolution, not only the source project's noEmit check.
• For complex types, optimize for readable diagnostics and bounded compiler work; a simpler public type is often better than a perfectly computed one.