Typescript Expert

TypeScript Expert

Overview

Use this skill to write TypeScript that is simple at runtime and precise at compile time. Prefer local repo conventions first, then apply the official TypeScript guidance summarized here.

Workflow

1. Read the nearest tsconfig.json, package package.json, and relevant existing source before choosing types.
2. Model the runtime contract first: inputs, outputs, failure modes, ownership boundaries, and public API shape.
3. Use TypeScript to make invalid states hard to represent, but keep the implementation readable JavaScript.
4. Validate unknown external data at the boundary; do not pretend unvalidated data already matches an internal type.
5. When adding or changing tests, use the write-tests skill for runner, fixture, assertion, dependency, and validation conventions.
6. Run the narrowest meaningful validation command before finishing: package typecheck/test for package changes, pnpm run typecheck:changed and pnpm run test:changed for broader changes, and pnpm run lint when practical.

Repo Rules

• Use import type { X } and export type { X } for type-only symbols.
• Include .ts extensions in relative imports and exports, matching this repo's allowImportingTsExtensions / rewriteRelativeImportExtensions setup.
• Follow public API boundaries: each package export maps to a top-level src/*.ts; src/lib is implementation-only.
• Do not re-export APIs or types from another package. Import from the package that owns the symbol.
• Prefer Web APIs and standards-aligned primitives over Node-specific APIs when either works.
• Use repo style: let for locals, module-scope const, regular functions by default, arrows for callbacks, object method shorthand, native class fields, and #private.
• Use descriptive lowercase generic names in this repo, such as source, pattern, or method, instead of single-letter names unless local code already uses that convention.

Package Structure

• Keep public barrels honest: top-level src/*.ts export files should re-export each public symbol directly from the module where it is defined, not through a src/lib pass-through barrel.
• Treat src/lib files as implementation owners. Split implementation by responsibility, but do not add thin re-export wrappers or indirect ownership inside src/lib.
• Export only APIs that a package consumer should rely on. Do not expose internal factories, data tables, or helper types just because they are useful across implementation modules.
• When moving functionality between modules, move the owning types with it or re-export them only from the package-level public entry point. Avoid making an implementation module look like a public API aggregator.
• Prefer internal factories or closures for configuration that should not leak into helper signatures. Public-facing helpers should not require callers to thread implementation booleans or mode flags through repeated calls.
• If a helper name implies a stronger semantic contract than the implementation provides, either narrow the name or keep it private until a package actually needs it. For example, terminal display width is different from code point length.
• Share constants from a single owning module when separate modules must agree on protocol values, escape sequences, sentinels, or discriminants. Avoid duplicating magic strings that can drift.
• Keep module dependency graphs one-way. When splitting modules, choose clear ownership so lower-level modules do not import from higher-level consumers, even for type-only imports.
• After public API changes, check the package barrel, README examples, tests, and change files together so documentation and exports match the actual supported surface.
• When test code changes, apply the write-tests skill rather than encoding detailed test-runner policy here.

API Documentation

• When adding or tightening public JSDoc, use the write-api-docs skill; it owns detailed JSDoc style, ESLint expectations, and API-docs workflow.
• Treat JSDoc as part of the public type contract. It should document behavior, defaults, units, and edge cases that TypeScript cannot express, not repeat type syntax.
• Use names and docs that do not over-promise. If an API only counts code points, do not describe it as terminal display width; if a helper is not ready as a supported contract, keep it internal.
• Keep package metadata, README examples, JSDoc, tests, and change files aligned with the same public API surface.

Type Design

• Let inference work for local variables and callback parameters when the initializer or context is obvious.
• Add explicit return types on exported functions, public methods, overloaded implementations, recursive functions, and functions where the return type is part of the contract.
• Use unknown for values that must be inspected before use. Avoid any; it disables useful type checking and spreads unsafety through every value it touches.
• Use primitive types string, number, boolean, symbol, and object; do not use boxed types like String, Number, Boolean, Symbol, or Object.
• Prefer interface for new public object shapes and option objects. Prefer type for unions, tuples, mapped types, conditional types, and aliases over non-object shapes.
• Represent states with discriminated unions when behavior depends on a mode, status, kind, or variant. Use exhaustive checks when adding or changing variants.
• For app, demo, and test code that runs through remix/node-tsx, do not require erasableSyntaxOnly; the runtime intentionally supports TypeScript syntax that needs transformation.
• Use satisfies when an object literal must conform to a broader type while preserving narrow property inference.
• Use as const for literal tables, discriminants, and tuples that should remain narrow and readonly. Do not use it to paper over mutable data flow.

Avoid Type Holes

• Do not fix TypeScript errors by adding any, as SomeType, !, @ts-ignore, or @ts-expect-error. First improve the type model, add control-flow narrowing, validate unknown input, or change the API shape.
• Treat explicit any as a last resort for migration or broken third-party types only. Prefer unknown at boundaries and narrow it before use.
• Do not put any in public APIs unless the API truly accepts and safely handles every JavaScript value. In almost all new code, unknown, a generic, or a union is a better contract.
• Avoid type assertions as routine casting. A TypeScript assertion is erased at runtime; it does not parse, validate, convert, or make an unsafe value safe.
• Use an assertion only when there is a real proof TypeScript cannot express, such as a checked DOM query, a validated schema result, or an external library invariant. Keep the assertion as close as possible to that proof.
• When adapting bad external types, isolate the unsafe assertion in one small helper with a precise return type. Do not let any leak through the rest of the package.
• Prefer reusable type guards or assertion functions over repeated casts when the same runtime check appears more than once.
• Avoid double assertions like value as unknown as Target; if one is unavoidable, wrap it at the boundary and document the invariant.
• Before accepting a cast, ask whether satisfies, as const, an explicit return type, a discriminated union, a generic constraint, or a local variable with a narrower type would express the intent without disabling checking.