JSON to TypeScript: types that match reality

Why hand-written types drift

Interfaces written from documentation or from memory tend to be optimistic. They mark everything present, assume a nullable field is always there, and quietly miss the nested object that only appears on premium accounts. TypeScript then enforces a shape the server never promised, and the first `undefined` surfaces in production rather than at compile time. Generating from real responses inverts the process: the compiler is checking an observed shape instead of a hoped-for one.

Reading the generated file

A useful conversion names nested objects after their keys, keeps array element types intact, and expresses uncertainty explicitly. Watch for the three markers that carry all the meaning:

                export interface Order {
  id: string;
  total: number;
  coupon?: string;            // absent in some responses
  shippedAt: string | null;   // present but null until shipped
  items: Array<OrderItem>;
}
              

The difference between `coupon?: string` and `shippedAt: string | null` is not cosmetic. Optional means the key can be missing; null means the key is there with no value. APIs do both, often in the same payload, and conflating them pushes a null check into code that assumed a string.

Use more than one sample

A single response marks everything required. Paste two or three responses — ideally one from an empty account and one from a full one — and the optional keys reveal themselves: a field missing from any sample becomes `?`, and a field that is sometimes null becomes a union with `null`. This is the cheapest correctness upgrade available, and it is the reason generated types should be regenerated when the API changes rather than written once.

Never let a generated interface be the only description of your API. Keep a schema or contract test alongside it, so a server change fails a build rather than a user session.

Where the types belong

• A dedicated `types/` or `api/` folder, not scattered through components.
• One file per endpoint or per resource, with a comment naming the endpoint and the date it was captured.
• A regeneration note: which call produced the payload, so the next person can repeat it.
• An export consumed by both the fetch layer and the components, so a change breaks exactly one place.

Turn on strict mode

Generated types only pay off with `strict` enabled, because that is what makes an optional key an actual error when accessed directly. Pair generated interfaces with `unknown` at the fetch boundary and narrow before use: `JSON.parse` returns `any`, so a cast to the generated interface should be the point where you have validated, not where you hope.

Generate from payloads you would not upload

API responses are the most sensitive JSON most developers handle — account data, orders, tokens. Running the JSON to TypeScript conversion in the browser means the payload is parsed locally and never transmitted, so you can paste a real response without redacting it first, and the tool keeps working offline.