({ baseUrl: "http://localhost:3000/api" });
// Path, params, body, and response all typed from the spec
const { data } = await client.GET("/users/{id}", {
params: { path: { id: "123" } },
});
const { data: user } = await client.POST("/users", {
body: { name: "Alice", email: "alice@example.com" },
});
```
### Roll your own client
If you prefer not to add `openapi-fetch`, use the generated types directly with standard `fetch`:
```ts
import type { paths } from "./api";
type Body<
P extends keyof paths,
M extends keyof paths[P],
> = paths[P][M] extends {
requestBody?: { content: { "application/json": infer B } };
}
? B
: never;
type Res<
P extends keyof paths,
M extends keyof paths[P],
> = paths[P][M] extends {
responses: { 200: { content: { "application/json": infer R } } };
}
? R
: unknown;
async function apiFetch(
path: P,
options: {
method: M;
data?: Body;
params?: {
path?: Record;
query?: Record;
};
},
): Promise> {
const url = new URL(
String(path).replace(/\{([^}]+)\}/g, (_, key) =>
encodeURIComponent(String(options.params?.path?.[key] ?? "")),
),
"/api",
);
for (const [k, v] of Object.entries(options.params?.query ?? {})) {
url.searchParams.set(k, String(v));
}
const res = await fetch(url, {
method: String(options.method).toUpperCase(),
headers: options.data ? { "Content-Type": "application/json" } : undefined,
body: options.data ? JSON.stringify(options.data) : undefined,
});
return res.json();
}
// Path, method, body, and params all typed from the spec
await apiFetch("/users/{id}", {
method: "get",
params: { path: { id: "123" } },
});
await apiFetch("/users", {
method: "post",
data: { name: "Alice", email: "alice@example.com" },
});
await apiFetch("/search", { method: "get", params: { query: { q: "hello" } } });
```
The same type utilities work with axios — swap `fetch` for `axios.request`.
---
## Common patterns
### Migrate an existing Express app
No rewrite required. Add typed routes alongside existing ones.
```diff
const app = express();
+ const typedRouter = createTypedRouter();
+ typedRouter.get("/users/:id", (req, res) => {
+ res.json({ id: req.params.id }); // typed
+ });
app.get("/health", (_req, res) => res.json({ ok: true })); // untouched
+ app.use("/api", typedRouter.getRouter());
+ app.use("/docs", typedRouter.docs());
```
### Middleware on a group of routes
```ts
// All admin routes share auth middleware and its types
const adminRouter = createTypedRouter()
.useMiddleware(requireAuth)
.get("/users", listUsersHandler)
.delete("/users/:id", deleteUserHandler);
app.use("/admin", adminRouter.getRouter());
```
### Per-feature routers, one doc endpoint
```ts
import {usersRouter} from "./v1/usersRouter"
....
const api = createTypedRouter()
.use("/users", usersRouter)
.use("/orders", ordersRouter)
.use("/auth", authRouter);
app.use("/api/v1", api.getRouter());
app.use("/docs", api.docs({ title: "My API", version: "1.0.0" }));
```
---
## API surface
| | |
| ---------------------------------------- | ------------------------------------------------ |
| `createTypedRouter()` | Create a router |
| `createTypedRouterWithMiddleware(...mw)` | Create a router pre-configured with middleware |
| `createTypedRouterWithConfig(config)` | Create a router with custom error handling |
| `router.useMiddleware(mw)` | Add typed global middleware (returns new router) |
| `router.use(prefix, subRouter)` | Mount a sub-router |
| `router.getRouter()` | Get the underlying Express router |
| `router.docs(options)` | Get the docs + OpenAPI spec router |
| `TypedMiddleware` | Type helper for middleware that extends `req` |
---
## Development
```bash
pnpm install
pnpm build
pnpm type-check
pnpm build:watch
```
---
## License
ISC