TypeScript API Client Compatibility Review Rules

Purpose

Use these rules when a TypeScript web app change can alter what frontend code, typed SDKs, or downstream packages see as the API client contract. The goal is to catch compile-time and runtime compatibility breaks before a rename, narrowed input, changed response shape, or stale generated declaration reaches users.

This is a TypeScript client-surface review policy. It is not an OpenAPI, JSON Schema, GraphQL, or Pact validation collection, and it does not replace a full API contract review gate. It tells reviewers how to decide whether a typed client surface is still safe for its consumers.

Review Inputs

Collect evidence for the client-visible surface before judging the patch.

1. Public surface. Exported functions, classes, hooks, route helpers, client factories, inferred router types, generated declarations, cache keys, auth header helpers, error types, and package entry points.
2. Consumer map. Frontend routes, apps, packages, examples, tests, SDKs, or external users that import the changed client or type.
3. Type evidence. API Extractor report, .d.ts diff, generated SDK diff, type tests, tsc --noEmit, package build, or downstream fixture compile.
4. Runtime evidence. Zod or other validator behavior, request examples, response fixtures, error mapping, cache invalidation, and end-to-end tests.
5. Release path. Deprecation period, adapter layer, feature flag, migration note, version boundary, and owner approval for breaking changes.

If the PR cannot name what downstream code imports, require that map before accepting type-check output from only the edited package.

Compatibility Rules

• Treat removed exports, renamed procedures, moved client paths, changed hook names, altered package entry points, and deleted generated declarations as breaking until consumers compile.
• Treat input changes as breaking when they remove accepted fields, require new fields, narrow unions, change enum values, alter date or decimal formats, or move values between path, query, header, and body shapes.
• Treat output changes as breaking when they remove fields, change nullability, widen optionality without consumer review, rename discriminants, or change the error union that callers branch on.
• Keep compatibility shims or deprecated aliases when consumers cannot migrate in the same release.
• Review route and procedure names as part of the contract in typed clients such as tRPC, even when no OpenAPI document exists.
• Require release notes or migration guidance when a consumer must update code, fixtures, generated clients, or cached data assumptions.

The reviewer should ask: would an existing consumer still compile and still handle the data shape at runtime after this change?

Type Surface Rules

Use TypeScript evidence that is readable to a reviewer.

• Prefer an API Extractor report, declaration diff, generated SDK diff, or type test that highlights changed exported signatures.
• Run type checks after generated clients, declaration files, routers, schema inference, and package exports have been refreshed.
• Do not approve changes that hide incompatibility with any, unknown casts, broad index signatures, weakened generics, disabled strictness, or skipped library checks.
• Keep exported declaration files aligned with the package entry points that consumers import.
• For inferred clients, review both the source router or schema and the inferred client type that consumers actually use.
• When a package publishes declaration files, inspect changes to public names, overloads, generic parameters, optional fields, discriminated unions, and documented release status.

Passing tsc in one package is useful, but it is not enough when the changed contract is consumed by another package, app, or SDK.

Runtime Validator Rules

Type changes and runtime validation changes must stay aligned.

• Update validators and inferred types together when a field is added, removed, renamed, narrowed, widened, made optional, or made nullable.
• Keep parse, transform, default, coercion, and refinement behavior visible in tests or fixtures when it affects request or response compatibility.
• Do not use a type-only edit to imply that runtime payloads changed, or a validator-only edit to imply that clients received an updated type.
• Re-run consumer flows that depend on validation errors, error codes, cache keys, retries, optimistic updates, or form field mapping.
• Confirm that generated clients and declarations reflect the reviewed source after validator, router, or schema changes.

Runtime validators are part of the contract when they decide what clients may send and what data the app accepts from the server.

Consumer Evidence Rules

Require evidence on the reviewed commit.

• Compile the packages or fixture apps that import the changed client surface.
• Run focused tests for changed request inputs, response mapping, errors, loading states, cache invalidation, retries, and form validation.
• Compare generated declaration or API report diffs with the intended change.
• Record exact commands, workspaces, commit SHA, generated artifacts, and any downstream consumers that were not checked.
• If compatibility is intentionally broken, require owner approval, migration notes, and a plan for stale clients.

Do not rely on source-code review alone when a typed client is shared across workspace boundaries.

Merge Blockers

Block merge until resolved when:

• the PR changes a typed client, router, package export, declaration, validator, generated SDK, or shared DTO without naming downstream consumers;
• type checks ran only in the edited package while known consumers were not compiled;
• generated declarations, API reports, or SDK clients are stale, missing, or inconsistent with source;
• compatibility is hidden with any, unsafe casts, disabled strictness, broad object types, or skipped checks;
• validators accept or reject a different runtime shape than the exported type describes;
• renamed fields, removed exports, changed nullability, or altered error unions lack an adapter, migration note, or owner-approved breaking-change path;
• logs, fixtures, API reports, request examples, or validation output expose private payloads or internal routes in public review comments.

Review Checklist

• {"task": "Surface mapped", "description": "Exported clients, types, routers, validators, generated declarations, and consumers are identified"}
• {"task": "Type diff reviewed", "description": "API report, declaration diff, generated client diff, or type-test evidence shows the public surface change"}
• {"task": "Consumers compile", "description": "Downstream packages, examples, or fixtures compile against the reviewed commit"}
• {"task": "Runtime aligned", "description": "Validators, examples, errors, and response mapping match the exported TypeScript types"}
• {"task": "Migration covered", "description": "Breaking changes have an adapter, deprecation path, migration note, or owner approval"}
• {"task": "Evidence safe", "description": "Logs, reports, examples, route names, and payloads avoid private data and unreleased details"}

AI Review Rules

AI assistants can help find compatibility risk, but they need to show evidence.

• Ask the assistant to list exported and inferred client surfaces before asking for a merge verdict.
• Require file paths, package names, import paths, and commands for every compatibility claim.
• Have the assistant separate confirmed consumer breaks from possible breaks it could not compile.
• Do not let the assistant conclude compatibility from server code alone when consumers import generated or inferred client types.
• Re-run review after generated files, declaration output, validators, router definitions, or package exports change.

Troubleshooting

• Only the server package compiles: add a fixture or workspace check that imports the published client surface the same way consumers do.
• The API report changed unexpectedly: inspect the exported signature diff, decide whether the change is intentional, and regenerate the report from the reviewed source.
• The type got looser to avoid compile errors: restore a precise type and fix consumers or provide a migration path instead of hiding the breakage.
• Runtime accepts data the type rejects: align the validator and exported type, then add a fixture that proves the intended behavior.
• A tRPC procedure moved: treat the procedure path, input, output, and error shape as the client contract; keep an alias or migration note when consumers cannot update immediately.

Duplicate And History Check

Checked existing rules, collections, commands, hooks, skills, open PRs, closed PR history, and issue #736 for API contract review, OpenAPI drift, JSON Schema, GraphQL schema validation, Pact checks, API-first architecture, tRPC skills, TypeScript strict mode, generated clients, and typed web app compatibility.

PR #1139 was closed because it repeated the existing api-contract-review-gate collection with the same OpenAPI, JSON Schema, Pact, Spectral, and SemVer-centered release gate. This entry intentionally avoids that lane. It focuses on TypeScript client compatibility: exported declaration surfaces, API Extractor reports, inferred router inputs and outputs, runtime validator alignment, downstream compilation, and privacy-safe review evidence for typed web app consumers.

Declaration Publishing Reference

{
  "name": "package-name",
  "version": "1.0.0",
  "types": "./index.d.ts",
  "typesVersions": {
    ">=3.1": { "*": ["ts3.1/*"] }
  }
}

Sources

• TypeScript declaration publishing: https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html
• TypeScript declaration file do's and don'ts: https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html
• API Extractor overview: https://api-extractor.com/pages/overview/intro/
• API Extractor API report workflow: https://api-extractor.com/pages/overview/demo_api_report/
• tRPC inferred types: https://trpc.io/docs/client/vanilla/infer-types
• tRPC routers: https://trpc.io/docs/server/routers
• Zod basics: https://zod.dev/basics

• Source repositorygithub.com 2026-07-19T11:20:19-07:00
• Documentationtypescriptlang.org
• Submitted by MkDev112026-06-04