Typed endpoints and live React hooks, powered by server-side Zero.
Define queries, mutations, input schemas, and business errors. Import your router's type into the browser and call useQuery and useMutation. The framework manages live subscriptions, connections, error serialization, and cleanup. Synced data stays on the server; the browser holds only the current query results in memory.
Configure your schema, authentication, and access scope once in app.ts. Each feature can define its own router; the root router composes them:
// src/routers/todos.ts
import { z } from "zod";
import { app } from "../app.ts";
import { canSeeList } from "../permissions.ts";
export const todosRouter = app.router({
toggle: app.mutation
.input(z.object({ id: z.string(), done: z.boolean() }))
.errors({ NOT_FOUND: { message: "Todo not found" } })
.handler(async ({ tx, zql, input, user, errors }) => {
const todo = await tx.run(
zql.todo
.where("id", input.id)
.whereExists("list", (list) => list.where(canSeeList(user)))
.one(),
);
if (!todo) throw errors.NOT_FOUND();
await tx.mutate.todo.update(input);
}),
});// src/routers/index.ts
import { app } from "../app.ts";
import { listsRouter } from "./lists.ts";
import { todosRouter } from "./todos.ts";
export const router = app.router({ lists: listsRouter, todos: todosRouter });
export type Router = typeof router;The listsRouter module follows the same pattern. Nest routers as objects to produce paths such as lists.get and todos.toggle; the browser infers both from Router. See the complete example. Composition needs no merge helper or registration step. Unlike oRPC, app.router() currently does not add router-wide middleware or lazy routes; attach guards and middleware to procedures.
Optional inputs and schema defaults work normally: .input(z.object({ done: z.boolean() }).optional()) lets callers omit the argument. A declared error can also include a data schema; the framework validates and transforms its data before sending it, and the client infers the schema's output type.
Create the client once for the signed-in session:
// web/api.ts
import { createClient } from "zero-relay/client";
import type { Router } from "../routers/index.ts";
export const api = createClient<Router>();Components work with typed data, loading state, and errors:
import { useQuery, useMutation } from "zero-relay/react";
import { api } from "./api.ts";
export function Todos({ listID }: { listID: string }) {
const [list, { status, error }] = useQuery(api.lists.get, { id: listID });
const { mutate: toggle, pending, error: saveError } = useMutation(api.todos.toggle);
if (error) return <p role="alert">{error.message}</p>;
if (!list) return <p>{status === "complete" ? "List not found" : "Loading…"}</p>;
return (
<section>
<h1>{list.name}</h1>
{saveError && <p role="alert">{saveError.message}</p>}
{list.todos.map((todo) => (
<button
key={todo.id}
disabled={pending}
onClick={() => toggle({ id: todo.id, done: !todo.done })}
>
{todo.done ? "Undo" : "Complete"}: {todo.title}
</button>
))}
</section>
);
}Queries update live after mutations. mutate(input) returns { data, error } and updates the hook's pending and error state. Components can display error.message or branch on declared business error codes. Errors whose data fails validation become a generic INTERNAL error.
Call api.$close() in your logout handler; create a fresh client for the next session. If a mutation's result is lost, its error explains that the write may have committed and current data should be checked before retrying.
Cloudflare is currently the only recommended hosting platform. For every other host, the planned path is Node.js + Rivet. The Cloudflare adapter supplies the endpoints and Durable Object implementation, with one Durable Object owning each relay partition. See hosting for implementation status and requirements.
Hosting is configured separately in worker.ts. Feature routers and React components stay independent of the adapter. The Node.js + Rivet adapter is next and is not implemented yet.
See examples/todo for the complete app, examples/todo-alchemy for local infrastructure setup, and docs/design.md for internals and advanced configuration.
Pre-release. The framework core, relay runtime, endpoints, Cloudflare adapter, and browser client are implemented and tested locally. A production deployment is still pending. The current priority is validating the Cloudflare deployment; the Node.js + Rivet adapter for non-Cloudflare hosts is next.
See the source map for module responsibilities and internal boundaries.
vp install
vp check # format, lint, and typecheck
vp test # unit tests
vp pack # buildBoth examples use Postgres on your local machine.
Browser app (examples/todo-alchemy). Alchemy starts Postgres, zero-cache, and the Worker. Then open the app signed in as Alice:
node_modules/.bin/alchemy dev examples/todo-alchemy/alchemy.run.ts
# http://localhost:8799/dev/login?as=alicePostgres is on port 5444 (postgres / postgres, database todo). ?as=bob signs in as Bob. The container is zero-relay-alchemy-pg; remove it to reseed from dev/seed.sql.
Worker only (examples/todo). Postgres and zero-cache come from Docker Compose, and the Worker from wrangler. This is what the end-to-end script drives. It does not serve the React app.
docker compose -f examples/todo/dev/docker-compose.yml up -d --wait
node_modules/.bin/wrangler dev -c examples/todo/wrangler.jsonc
node examples/todo/dev/e2e.ts