Elysia
@hyper-fetch/elysia converts the type of an Elysia app into a schema for
createSdk. The frontend then calls the backend through a typed SDK whose responses, errors,
payloads, query params and URL params come from your Elysia routes and schemas. The package exports a single type and
adds no code to your bundle.
- One source of truth: Elysia route definitions type the frontend, with no codegen step and no hand-written schema.
- Typed inputs:
bodyandqueryschemas typesetPayload()andsetQueryParams(), and:paramsegments typesetParams(). - Typed errors: Bodies returned with a 2xx status type
data. Every other status, including the422Elysia sends when a schema rejects the input, typeserror. - Full HyperFetch features: Every route is a regular
Requestwith cache, retries, deduplication and React hooks.
Installation
- npm
- yarn
- pnpm
npm install @hyper-fetch/core @hyper-fetch/elysia
yarn add @hyper-fetch/core @hyper-fetch/elysia
pnpm add @hyper-fetch/core @hyper-fetch/elysia
elysia 1.3 or newer is a peer dependency. Install the package where you export the schema type, usually the backend.
The schema is a type, so it works the same whether the backend runs on Bun, Node.js or any other runtime Elysia
supports.
Getting Started
- Chain your routes and export the schema type from the backend. Elysia only types routes defined in one chain, the same rule as its own Eden client.
import { Elysia, t } from "elysia";
import type { ElysiaAppToHyperFetch } from "@hyper-fetch/elysia";
const users = new Elysia({ prefix: "/users" })
.get("/", () => [{ id: "1", name: "Ann" }])
.get("/:userId", ({ params }) => ({ id: params.userId, name: "Ann" }))
.post("/", ({ body, status }) => status(201, { id: "2", name: body.name }), {
body: t.Object({ name: t.String() }),
});
export const app = new Elysia().use(users);
export type AppSchema = ElysiaAppToHyperFetch<typeof app>;
- Pass the schema to
createSdkon the frontend. Useimport typeso no backend code reaches the client bundle.
import { createClient, createSdk } from "@hyper-fetch/core";
import type { AppSchema } from "@my-app/backend";
export const client = createClient({ url: "https://api.example.com" });
export const sdk = createSdk<typeof client, AppSchema>(client);
- Send requests. Types follow the Elysia route definitions.
const { data } = await sdk.users.$get.send();
const { data: user } = await sdk.users.$userId.$get.setParams({ userId: "1" }).send();
const { data: created } = await sdk.users.$post.setPayload({ name: "Bob" }).send();
How routes map to the SDK
| Elysia route | SDK accessor | Endpoint |
|---|---|---|
app.get("/", ...) | sdk.$get | / |
new Elysia({ prefix: "/users" }) + / | sdk.users.$get | /users |
.get("/:userId", ...) | sdk.users.$userId.$get | /users/:userId |
.get("/:userId/posts", ...) | sdk.users.$userId.posts.$get | /users/:userId/posts |
.get("/google-login", ...) | sdk.auth.googleLogin.$get | /auth/google-login |
.get("/files/:fileId?", ...) | sdk.files.$get and sdk.files.$fileId.$get | /files and /files/:fileId |
.group("/v1", (app) => app.use(users)) | sdk.v1.users.$get | /v1/users |
- Each path segment becomes a nested property.
:paramsegments become$paramproperties, and the param is typed onsetParams().- Routes below an optional
:param?segment appear twice: without the param, and under$paramwith it. HyperFetch params are always required, so each variant is its own request. - kebab-case segments become camelCase.
createSdkturns them back into kebab-case when it builds the URL. - Methods become lowercase keys:
$get,$post,$put,$patch,$delete, and custom methods registered with.route(), such as$propfind. - The endpoint is the full Elysia path, including
prefixand.group()prefixes.
- WebSocket routes registered with
.ws(). Use@hyper-fetch/socketsfor them. .all()routes, because they do not map to a single HTTP method.- Wildcard
*segments, because HyperFetch has no way to fill them. - Handlers attached with
.mount(), because Elysia does not type them. - Paths with ten or more segments. Up to eight segments get the full request types and the SDK client. At nine,
createSdkstops injecting the client into the request.
How request types are read
Each route becomes a Request with these generics:
- Response: the union of the bodies the handler returns with a 2xx status. A route that only returns other statuses
gets
undefined. - Local error: the union of the bodies of every other status, for example
status(404, { message })and the422validation error of a route with a schema. It isundefinedwhen every status is a success. - Payload: the route's
bodyschema, orundefinedwithout one. A body with at.File()ort.Files()field is typed asFormData, because files can only be sent as multipart form data. - Query params: the route's
queryschema, orundefinedwithout one. - Endpoint: the full Elysia path, which types
setParams().
const { data, error } = await sdk.users.$userId.$get.setParams({ userId: "missing" }).send();
if (error) {
// error is the 404 body or the 422 validation error
} else {
// data is the 2xx body
}
headersschemas. HyperFetch requests do not type headers, so pass them withsetHeaders().paramsschemas such ast.Numeric(). Params are typed from the path, as strings or numbers.
What arrives over HTTP
Elysia types the value a handler returns, but the client receives that value after it went over HTTP. The response and error types follow what HyperFetch actually reads:
| Handler returns | Typed as | Why |
|---|---|---|
A Date, also inside objects and arrays | string | JSON sends dates as ISO strings |
null or undefined | "" | Elysia sends an empty body |
Nothing, or any | unknown | Elysia types both the same way |
A generator, sse(), a ReadableStream, a Response or form() | unknown | The body is not JSON |
| An error the handler throws | global error | Elysia does not type it, the status is 500 |
Read a streamed route with setOptions({ streaming: true }) and parse the stream yourself.
HyperFetch encodes arrays as tags[]=a&tags[]=b by default, which Elysia rejects with a 422. Send repeated keys
instead:
client.adapter.setQueryParamsMapperConfig({ arrayFormat: "none" });
To upload files, build the FormData yourself. HyperFetch sends it as it is:
const form = new FormData();
form.append("title", "report");
form.append("file", file);
await sdk.upload.$post.setPayload(form).send();
Global errors
createSdk injects your client into every request, so the client's global error type applies to every Elysia route next
to the local error of the route.
import { createClient, createSdk } from "@hyper-fetch/core";
import type { AppSchema } from "@my-app/backend";
type ApiError = { message: string; code: string };
const client = createClient<{ error: ApiError }>({ url: "https://api.example.com" });
const sdk = createSdk<typeof client, AppSchema>(client);
const { error } = await sdk.users.$get.send();
// error is typed with ApiError
Summary
ElysiaAppToHyperFetch<typeof app>turns a chained Elysia app into a schema forcreateSdk.- Paths, params, optional params, kebab-case segments, prefixes and groups all map to nested SDK properties.
- 2xx bodies type the response, and every other status types the local error.
- Response types follow the wire: dates are strings, empty bodies are
"", and streams areunknown. bodyandqueryschemas type the payload and query params of each request.- The package ships types only, so import it with
import typeon the frontend.

