Typed SDK
A list of posts, a details panel and a form that adds a post. Instead of declaring each request with createRequest,
the app describes the API as one schema type and reads its requests from an SDK object.
beginnercreateSdkuseFetchuseSubmittypescript
Opens the example in StackBlitz in a new tab. The first start installs packages and takes a few seconds.
import { useFetch, useSubmit } from "@hyper-fetch/react";
import type { FormEvent } from "react";
import { useState } from "react";
import { sdk } from "./api";
const PostList = ({ selected, onSelect }: { selected: number | null; onSelect: (id: number) => void }) => {
// `sdk.posts.$get` is a regular Request, so every request method and hook works with it.
// `select` is a dummyjson query param: the API returns only these fields.
const { data, error, loading } = useFetch(sdk.posts.$get.setQueryParams({ limit: 8, select: "title" }));
if (loading && !data) return <p aria-busy="true">Loading posts...</p>;
if (error) return <p>Could not load posts: {error.message}</p>;
return (
<ul className="list">
{data?.posts.map((post) => (
<li key={post.id}>
<button
type="button"
className={post.id === selected ? undefined : "outline secondary"}
onClick={() => onSelect(post.id)}
>
{post.title}
</button>
</li>
))}
</ul>
);
};
const PostDetails = ({ postId }: { postId: number }) => {
// `$postId` in the schema becomes a typed `:postId` param.
const { data, error, loading } = useFetch(sdk.posts.$postId.$get.setParams({ postId }));
if (loading && !data) return <article aria-busy="true">Loading post...</article>;
if (error) return <article>Could not load the post: {error.message}</article>;
if (!data) return null;
return (
<article>
<header>
<h3>{data.title}</h3>
<small className="muted">
{data.reactions.likes} likes · {data.reactions.dislikes} dislikes
</small>
</header>
<p>{data.body}</p>
</article>
);
};
const NewPostForm = () => {
const { submit, submitting, data, error } = useSubmit(sdk.posts.add.$post);
const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
event.preventDefault();
const form = new FormData(event.currentTarget);
// The payload type comes from the schema: a missing `userId` is a compile error.
submit({ payload: { title: String(form.get("title")), body: String(form.get("body")), userId: 1 } });
};
return (
<article>
<form onSubmit={handleSubmit}>
<input name="title" placeholder="Title" aria-label="Title" required />
<textarea name="body" placeholder="What is on your mind?" aria-label="Body" rows={3} required />
<button type="submit" aria-busy={submitting} disabled={submitting}>
Add post
</button>
</form>
{error && <p>Could not add the post: {error.message}</p>}
{data && (
<p>
Created post <mark>#{data.id}</mark> "{data.title}". dummyjson simulates writes, so it does not show up in the
list.
</p>
)}
</article>
);
};
export const App = () => {
const [selected, setSelected] = useState<number | null>(null);
return (
<main className="container">
<hgroup>
<h1>Posts SDK</h1>
<p>
Every request below comes from one typed object: <code>sdk.posts.$get</code>,{" "}
<code>sdk.posts.$postId.$get</code> and <code>sdk.posts.add.$post</code>.
</p>
</hgroup>
<div className="grid-2">
<section>
<h2>Posts</h2>
<PostList selected={selected} onSelect={setSelected} />
</section>
<section>
<h2>Details</h2>
{selected ? <PostDetails postId={selected} /> : <p className="muted">No post selected.</p>}
<h2>New post</h2>
<NewPostForm />
</section>
</div>
</main>
);
};
Run locally
npx tiged BetterTyped/hyper-fetch/examples/react/sdk hyper-fetch-react-sdk && cd hyper-fetch-react-sdk && npm install && npm run devWhat it shows
- One schema type that mirrors the URL tree of the API, with
RequestModelon each endpoint. createSdk(client)turns the schema into an object:sdk.posts.$postId.$getisGET /posts/:postId.- Regular requests. SDK leaves are
Requestinstances, sosetParams,setQueryParams,useFetchanduseSubmitwork as usual. - Types from the schema. Params, query params, payload and response are checked at compile time.
How it works
api.tsdeclaresDummyJsonSchema. Plain keys (posts,add) are path segments, a$key that is not a method ($postId) is a:postIdparam, and$getor$postis the HTTP method of that path.createSdk<typeof client, DummyJsonSchema>(client)returns a proxy. It creates a request only when you read a leaf, so a large schema costs nothing at startup. The client's URL, cache and global error type apply to every leaf.PostListandPostDetailspass SDK requests touseFetch, withsetQueryParamsandsetParamstyped from the schema.NewPostFormpassessdk.posts.add.$posttouseSubmitand callssubmit({ payload }). Leaving outuserIdis a type error, because the payload type isNewPost.
const { data } = useFetch(sdk.posts.$postId.$get.setParams({ postId }));
Each property read creates a new request instance. Cache keys come from the endpoint and params, so two reads of the
same leaf still share one cache entry. Keep a reference only when you call per-instance setters such as setMock.
When to use it
- APIs with many endpoints, where one schema is easier to keep in sync than many
createRequestcalls. - Schemas generated from an OpenAPI file or a server type, for example with the HyperFetch CLI or
@hyper-fetch/hono.
Related
Summary
You typed the API as one schema, created the SDK with createSdk(client) and used its requests with useFetch and
useSubmit. The schema is the single source of types for params, payloads and responses.
