TypeScript library

A library's types are its API. The caller writes plain values and the library infers everything else, so the call site carries no generic arguments, casts or annotations, and every wrong call is a compile error at the line that is wrong. TanStack Router and Query are the bar: types "flow through the entire routing experience" and "you write less types as a developer".

This skill covers the published surface: what consumers import and call. For types inside the implementation, call the Skill tool with "typescript-best-practices". For the module's shape (what it hides, where the seam goes), call the Skill tool with "codebase-design".

Steps

1. Write the call sites first. Before any signature, write the code a consumer will write, in a type test file next to the source (src/<feature>.test-d.ts), importing from the package's public entry (set that up before the first build per Type tests). Cover the common case, the advanced case, and every mistake class in the mistake checklist that applies. Done when every call site reads as plain values with no generic arguments, casts or annotations, and each applicable mistake class has a line that must fail.
2. Shape the signatures so those call sites compile, applying every rule in API shape. Then remove the @ts-expect-error from each mistake line one at a time, compile, and read the message. Done when the implementation contains no cast that a looser implementation signature could remove, each rule in that file has been checked against every new or changed export, and every mistake's error lands on the caller's wrong value and names what it expected.
3. Turn the call sites into type tests per Type tests: exact-type assertions for what infers, @ts-expect-error for every mistake from step 1, an error-text test where the message is the contract, plus runtime tests for runtime guards. Done when the type test target runs red if any inferred type widens to any, unknown or a broader union, and every mistake has a failing-compile line.
4. Check what you publish per Publishing: lint the package, pack it, run attw on that tarball, and compile a consumer fixture against it under each supported module resolution and TypeScript version. Done when all of them pass on the packed output, not on the source tree.
5. Measure type cost when the change adds recursion, a union over registered entries (routes, keys, events), or inference across more than one call. Follow Type performance. Done when you have baseline and candidate numbers from tsc --extendedDiagnostics on a realistic consumer fixture and check time does not regress without a stated reason.
6. Classify the change for semver with the table in Publishing, and write the classification in the changeset or PR body.

Rules that apply to every export

These are the rules a reviewer checks first. API shape holds the full set with TanStack examples.