How to Type Fetch Responses in TypeScript
You call fetch, then res.json(), and TypeScript hands you any. Whatever you write next, the compiler believes it. Typing fetch responses in TypeScript properly means two things: getting a real type onto the data, and making sure the data actually matches that type at runtime. Most code only does the first one.
This post walks through the usual approaches, from the one that lies to the one that checks, and ends with a small getJson helper you can drop into a project.
Why res.json() returns any
Open lib.dom.d.ts in TypeScript 5.9 and you will find this on the Body interface:
The browser typings cannot know what your server sends, so they give up. Node's fetch typings (from undici-types, pulled in by @types/node) are stricter and return Promise. Which one you get depends on your lib setting. A Next.js or Vite project includes dom, so you get any. A plain Node service without the DOM lib gets unknown.
That difference matters. any lets you assign the result to anything without complaint. unknown forces you to narrow it first, which is the behaviour you actually want.
The three ways people "type" it (and why two of them lie)
Here is the code you will see in most codebases:
This compiles. It also checks nothing. If the API starts returning id as a string, user.id.toFixed() throws in production and the compiler never warned you. The as version is the same thing with different syntax:
Then there is the generic wrapper, which feels more rigorous than it is:
The any from res.json() is silently accepted as T. The type parameter is a cast with nicer syntax. Libraries like axios do the same thing with axios.get: the generic types the result, it does not validate it.
| Approach | Compiles | Checks the data | Cost |
|---|---|---|---|
const user: User = await res.json() | yes, with DOM lib | no | none |
as User | yes | no | none |
getJson | yes | no | none |
| Hand-written type guard | yes | yes | grows with the shape |
| Schema validation (Zod) | yes | yes | one dependency |
Option 1: a type guard
Treat the response as unknown and prove its shape before you use it:
No dependency, and TypeScript narrows data to User after the check. The problem is that the guard and the interface are two separate things that can drift. Add a field to User, forget the guard, and you are back to trusting the server. For one or two small shapes this is fine. For a real API surface it gets tedious fast.
Option 2: validate with a schema
A schema library gives you the runtime check and the static type from one definition. With Zod 4:
Now the type can't drift from the check, because the type is derived from it. Writing these by hand for a 40-field response is the boring part. Paste a real response into the JSON to Zod converter and it generates the schema, merging every element of every array so optional and nullable fields come out right. If you only need the static types and plan to validate elsewhere, the JSON to TypeScript converter gives you the interfaces from the same sample.
A getJson helper that checks what it returns
Put the status check, the parse and the validation in one place:
You never pass T by hand. TypeScript infers it from the schema:
The res.ok check runs first on purpose. fetch resolves on a 404 or 500, and calling res.json() on an HTML error page gives you Unexpected token '<' instead of the real status. The JSON parse errors guide covers that one in detail.
When the payload is wrong, schema.parse throws a ZodError that says exactly where. For { "id": "42", "name": "Ada" }, z.prettifyError prints:
Compare that with Cannot read properties of undefined three components away from the fetch.
Pagination envelopes and error shapes
Real APIs wrap data. Write the envelope once as a function that takes the item schema:
Some APIs return 200 for both success and failure and put the outcome in a field. Model that as a discriminated union, and TypeScript narrows on the tag:
Strict or lenient?
parse throws on any mismatch. That is right for a payment response, and too harsh for a feed where one odd item shouldn't blank the page. Use safeParse where you'd rather log and degrade:
By default z.object strips keys it doesn't know about rather than failing, so an API adding a field won't break you. Removing or retyping one will, and that is exactly the break you want to hear about.
If you share contracts with a backend in another language, a JSON Schema is the neutral format both sides can read. The JSON Schema generator builds one from a sample, and the JSON validator is the quick way to confirm a captured response is valid JSON before you blame the schema.
One last gotcha: z.infer gives you the output type. If a schema uses .transform() or .default(), the type you get back from getJson is the transformed one, not the raw JSON shape. Use z.input when you need the wire format, for example to type a mock response in a test.