Zeroback

https://github.com/zerodeploy-dev/zeroback
Admin
Zeroback is an open-source real-time backend for Cloudflare that provides reactive queries,...
Tokens:93,795
Snippets:752
Trust Score:3.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example: run zeroback dev

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/cli.md

Example commands to start the development server with the default functions directory or a custom one.

```bash
npx @zeroback/cli dev
# or with a custom functions directory
npx @zeroback/cli dev ./src/zeroback
```

--------------------------------

### Initialize and run a Zeroback project

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/README.md

Initializes a new Zeroback project, installs the server package, and starts the development server. After running these commands, edit zeroback/schema.ts and zeroback/tasks.ts to define your backend.

```bash
npx @zeroback/cli init my-app
cd my-app
npm install @zeroback/server
zeroback dev
```

--------------------------------

### TanStack Start SSR example with preloadQuery and usePreloadedQuery

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/react.md

Complete TanStack Start example showing SSR with preloadQuery in a server function and usePreloadedQuery in the component. ZerobackClient should be constructed browser-side only; create the client and render ZerobackProvider in a client-only layout component. usePreloadedQuery handles the case where no provider is present during SSR.

```ts
// app/routes/tasks.tsx
import { createServerFn, createFileRoute } from "@tanstack/start"
import { preloadQuery } from "@zeroback/client"
import { usePreloadedQuery } from "@zeroback/react"
import { api } from "../zeroback/_generated/api"

const ZEROBACK_URL = process.env.ZEROBACK_URL!

const loadTasks = createServerFn().handler(async () => {
  return { preloaded: await preloadQuery(ZEROBACK_URL, api.tasks.recent, { limit: 20 }) }
})

export const Route = createFileRoute("/tasks")({
  loader: () => loadTasks(),
  component: TasksPage,
})

function TasksPage() {
  const { preloaded } = Route.useLoaderData()
  const tasks = usePreloadedQuery(preloaded)  // never undefined, real-time after hydration

  return (
    <ul>
      {tasks.map((task) => (
        <li key={task._id}>{task.title}</li>
      ))}
    </ul>
  )
}
```

--------------------------------

### Full HTTP router example with GET and POST routes

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/functions.md

Complete example of an HTTP router with two routes: a GET route that queries tasks by project and a POST route that creates a task. Both use `httpAction` and return JSON responses.

```ts
import { httpRouter, httpAction } from "@zeroback/server";

const http = httpRouter();

http.route({
  path: "/api/tasks",
  method: "GET",
  handler: httpAction(async (ctx, request) => {
    const url = new URL(request.url);
    const projectId = url.searchParams.get("projectId") ?? "";
    const tasks = await ctx.runQuery("tasks:listByProject", { projectId });
    return new Response(JSON.stringify(tasks), {
      headers: { "Content-Type": "application/json" },
    });
  }),
});

http.route({
  path: "/api/tasks",
  method: "POST",
  handler: httpAction(async (ctx, request) => {
    const body = await request.json();
    await ctx.runMutation("tasks:create", body);
    return new Response(JSON.stringify({ ok: true }), {
      headers: { "Content-Type": "application/json" },
    });
  }),
});

export default http;
```

--------------------------------

### Run Zeroback locally with bun and zeroback dev

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/README.md

Commands to install dependencies and run the backend and frontend locally. Requires Bun and Wrangler. The frontend example is in `examples/task-manager` and runs on http://localhost:5173.

```bash
# Install dependencies
bun install

# Start the backend (from your app directory)
zeroback dev

# In another terminal, start the frontend
cd examples/task-manager
bun run dev
```

--------------------------------

### Install @zeroback/client

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/client.md

Install the client package via npm.

```bash
npm install @zeroback/client
```

--------------------------------

### Full example server code (zeroback/files.ts)

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/storage.md

Complete server-side example for file storage. Defines mutations for generating upload URLs and saving file references, and a query for getting file URLs.

```ts
import { query, mutation, action } from "./_generated/server";
import { v } from "@zeroback/server";

export const generateUploadUrl = mutation({
  args: {},
  handler: async (ctx) => {
    return await ctx.storage.generateUploadUrl();
  },
});

export const saveFile = mutation({
  args: { storageId: v.string(), name: v.string() },
  handler: async (ctx, args) => {
    return await ctx.db.insert("files", {
      storageId: args.storageId,
      name: args.name,
    });
  },
});

export const getFileUrl = query({
  args: { storageId: v.string() },
  handler: async (ctx, args) => {
    return await ctx.storage.getUrl(args.storageId);
  },
});
```

--------------------------------

### Install @zeroback/react

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/README.md

Installs the React client package for Zeroback.

```bash
npm install @zeroback/react
```

--------------------------------

### Example: deploy with zeroback deploy

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/cli.md

Examples covering first-time login, deployment, dry-run, passing arguments to wrangler, and using an API token for CI/CD.

```bash
# First-time setup: log in to Cloudflare
npx wrangler login

# Deploy
npx @zeroback/cli deploy

# Dry run (codegen only)
npx @zeroback/cli deploy --dry-run

# Pass args to wrangler
npx @zeroback/cli deploy -- --env production

# CI/CD: use an API token instead of interactive login
CLOUDFLARE_API_TOKEN=your-token npx @zeroback/cli deploy
```

--------------------------------

### Example: scaffold a new project with zeroback init

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/cli.md

Example commands to create a new directory, initialize npm, and run the zeroback init CLI to scaffold a project.

```bash
mkdir my-app && cd my-app
npm init -y
npx @zeroback/cli init
```

--------------------------------

### Example: run zeroback reset

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/cli.md

Example command to reset the local development database by deleting the .wrangler/state directory.

```bash
npx @zeroback/cli reset
```

--------------------------------

### Install @zeroback/server and @zeroback/react (npm, bun, pnpm, yarn)

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/quickstart-react.mdx

Install the required Zeroback packages using your preferred package manager.

```bash
npm install @zeroback/server @zeroback/react
```

```bash
bun add @zeroback/server @zeroback/react
```

```bash
pnpm add @zeroback/server @zeroback/react
```

```bash
yarn add @zeroback/server @zeroback/react
```

--------------------------------

### Install @zeroback/solid

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/solid.md

Installs the @zeroback/solid package for Solid.js primitives.

```bash
npm install @zeroback/solid
```

--------------------------------

### Full example client component (FileUpload)

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/storage.md

Complete client-side example for uploading a file. Uses useMutation to get an upload URL, uploads the file to R2 via PUT, then saves the reference in the database.

```tsx
function FileUpload() {
  const generateUploadUrl = useMutation(api.files.generateUploadUrl);
  const saveFile = useMutation(api.files.saveFile);

  const handleUpload = async (file: File) => {
    // 1. Get upload URL
    const uploadUrl = await generateUploadUrl({});

    // 2. Upload file to R2
    const response = await fetch(uploadUrl, {
      method: "PUT",
      body: file,
      headers: { "Content-Type": file.type },
    });
    const { storageId } = await response.json();

    // 3. Save reference in database
    await saveFile({ storageId, name: file.name });
  };

  return <input type="file" onChange={(e) => handleUpload(e.target.files![0])} />;
}
```

--------------------------------

### Start development with zeroback dev

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/README.md

Starts the development server. It analyzes the zeroback/ directory, generates type-safe code, starts a local Cloudflare Worker with Durable Objects, and watches for changes.

```bash
zeroback dev
```

--------------------------------

### Verify installation with bun install

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/superpowers/plans/2026-04-02-typeid-migration.md

Verify the installation by running bun install. Expected: clean install, no errors.

```bash
bun install
```

--------------------------------

### Example: run zeroback codegen

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/cli.md

Example command to run code generation, useful for CI or pre-commit hooks.

```bash
npx @zeroback/cli codegen
```

--------------------------------

### zeroback run examples

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/cli.md

Examples of running queries, mutations, internal functions, and targeting a deployed server. Each command sends a POST to /__admin/run and prints the JSON result.

```bash
# Run a query
npx @zeroback/cli run tasks:list

# Run a mutation with arguments
npx @zeroback/cli run tasks:create '{"title": "Buy groceries", "projectId": "proj:abc", "status": "todo"}'

# Run an internal function
npx @zeroback/cli run tasks:countInternal '{"projectId": "proj:abc"}'

# Target a deployed server
npx @zeroback/cli run tasks:list --url https://my-worker.example.com
```

--------------------------------

### take usage example

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/database.md

Example of using .take() with .order() to fetch the 10 most recent tasks.

```ts
const recent = await ctx.db.query("tasks").order("desc").take(10);
```

--------------------------------

### TanStack Start usage with preloadQuery and usePreloadedQuery

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/superpowers/specs/2026-04-01-ssr-fetch-design.md

Usage example for TanStack Start: the server-side loader calls preloadQuery and the component consumes the preloaded data with usePreloadedQuery, ensuring the value is never undefined and becomes real-time after hydration.

```ts
// route (server-side loader)
export const loader = createServerFn().handler(async () => {
  return { preloaded: await preloadQuery(ZEROBACK_URL, api.tasks.list, {}) }
})

// component
const { preloaded } = useLoaderData()
const tasks = usePreloadedQuery(preloaded)  // never undefined, real-time after hydration
```

--------------------------------

### Setup with Persistence

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/solid.md

Configures the client with persistence enabled and calls init() before rendering.

```tsx
const client = new ZerobackClient("wss://example.com/ws", {
  persistence: true,
  schemaVersion: "v1",
});

// Must call init() before rendering when persistence is enabled
await client.init();

function App() {
  return (
    <ZerobackProvider client={client}>
      <MyApp />
    </ZerobackProvider>
  );
}
```

--------------------------------

### Setup ZerobackProvider

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/solid.md

Sets up the ZerobackProvider with a ZerobackClient instance for real-time queries.

```tsx
import { ZerobackClient, ZerobackProvider } from "@zeroback/solid";

const client = new ZerobackClient("ws://localhost:8788/ws");

function App() {
  return (
    <ZerobackProvider client={client}>
      <MyApp />
    </ZerobackProvider>
  );
}
```

--------------------------------

### Start Zeroback dev server with npx @zeroback/cli dev

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/quickstart-react.mdx

Starts a local Cloudflare Worker and generates typed APIs into zeroback/_generated/. Keep this running.

```bash
npx @zeroback/cli dev
```

--------------------------------

### Commit example adjustments

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/superpowers/plans/2026-04-02-typeid-migration.md

Stages and commits changes to the example app for TypeID compatibility.

```bash
git add examples/
git commit -m "chore: update example app for TypeID compatibility"
```

--------------------------------

### Full Example: HTTP Actions

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/functions.md

Complete example showing how to expose functions as REST endpoints using the HTTP router.

```APIDOC
## Full Example: HTTP Actions

### Description
Complete example showing how to expose functions as REST endpoints using the HTTP router.

### Method
GET and POST

### Endpoint
`/api/tasks`

### Parameters
#### GET /api/tasks
- **projectId** (string) - Optional - Query parameter to filter tasks by project.

#### POST /api/tasks
- **Request body** (object) - Required - JSON body containing task data (e.g., `{ projectId: string, ... }`).

### Request Example
#### GET /api/tasks
```
GET /api/tasks?projectId=123
```

#### POST /api/tasks
```json
{
  "projectId": "123",
  "title": "New task"
}
```

### Response
#### Success Response (200)
- **GET**: JSON array of tasks.
- **POST**: JSON object `{ "ok": true }`.

#### Response Example
#### GET /api/tasks
```json
[
  {
    "_id": "task123",
    "projectId": "123",
    "title": "New task"
  }
]
```

#### POST /api/tasks
```json
{
  "ok": true
}
```
```

--------------------------------

### useQuery example with TaskList component

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/react.md

Example of using useQuery to fetch and display tasks, handling the loading state when the result is undefined.

```tsx
import { api } from "../zeroback/_generated/api";
import { useQuery } from "@zeroback/react";

function TaskList({ projectId }: { projectId: string }) {
  const tasks = useQuery(api.tasks.listByProject, { projectId });

  if (tasks === undefined) return <div>Loading...</div>;

  return (
    <ul>
      {tasks.map((task) => (
        <li key={task._id}>{task.title}</li>
      ))}
    </ul>
  );
}
```

--------------------------------

### collect usage example

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/database.md

Example of using .collect() to fetch all matching documents.

```ts
const allTasks = await ctx.db.query("tasks").collect();
```

--------------------------------

### Install typeid-js in values and server packages

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/superpowers/plans/2026-04-02-typeid-migration.md

Install the typeid-js dependency in both the values and server packages using bun.

```bash
cd /Users/ranyefet/Code/zeroback
bun add typeid-js --cwd packages/values
bun add typeid-js --cwd packages/server
```

--------------------------------

### count usage examples

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/database.md

Examples of using .count() alone, with filters, and with an index.

```ts
const total = await ctx.db.query("tasks").count();

// With filters
const active = await ctx.db.query("tasks")
  .filter((q) => q.eq(q.field("status"), "active"))
  .count();

// With index
const projectTasks = await ctx.db.query("tasks")
  .withIndex("by_project", (q) => q.eq("projectId", "proj123"))
  .count();
```

--------------------------------

### Build, Test, and Lint Commands

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/AGENTS.md

Common build, test, and lint commands for the Zeroback monorepo. Install dependencies with bun install, run all tests with bun test, target a specific test file or pattern with bun vitest run, use watch mode, type-check, and build all or a specific package.

```bash
# Install dependencies (run once)
bun install

# Run all tests (includes e2e + unit)
bun test

# Run specific test file
bun vitest run e2e/zeroback.test.ts

# Run single test by pattern
bun vitest run --testNamePattern="should insert a document"

# Watch mode for development
bun test:watch

# Type check all packages
bun run typecheck

# Build all packages
bun run build

# Build specific package
bun run --filter '@zeroback/server' build
```

--------------------------------

### first usage example

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/database.md

Example of using .first() with a filter to fetch the first matching user.

```ts
const user = await ctx.db.query("users")
  .filter((q) => q.eq(q.field("email"), "alice@example.com"))
  .first();
```

--------------------------------

### Check example schema table names

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/superpowers/plans/2026-04-02-typeid-migration.md

Searches for defineTable or defineSchema in the example app to verify table names are valid TypeID prefixes.

```bash
grep -n "defineTable\|defineSchema" examples/task-manager/zeroback/ -r
```

--------------------------------

### Cron example with multiple schedules

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/functions.md

Complete example showing how to register interval, daily, weekly, monthly, and custom cron jobs. Uses cronJobs() and exports the crons instance.

```ts
import { cronJobs } from "@zeroback/server";

const crons = cronJobs();

// Every 5 seconds
crons.interval("cleanup", { seconds: 5 }, "tasks:cleanupDone", {});

// Every day at 9:00 UTC
crons.daily("digest", { hourUTC: 9 }, "email:sendDigest");

// Every Monday at 8:00 UTC
crons.weekly("report", { dayOfWeek: 1, hourUTC: 8 }, "reports:weekly");

// 1st of every month at midnight
crons.monthly("billing", { dayOfMonth: 1 }, "billing:charge");

// Custom cron expression (weekdays at 3:00 AM UTC)
crons.cron("nightly", "0 3 * * 1-5", "jobs:nightly");

export default crons;
```

--------------------------------

### Cron jobs quick example

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/scheduling.md

Quick example of defining cron jobs in zeroback/crons.ts. It creates interval, daily, and cron schedules for various functions.

```ts
// zeroback/crons.ts
import { cronJobs } from "@zeroback/server";

const crons = cronJobs();

crons.interval("cleanup", { minutes: 30 }, "tasks:cleanupDone");
crons.daily("digest", { hourUTC: 9 }, "email:sendDigest");
crons.cron("nightly", "0 3 * * *", "jobs:nightly");

export default crons;
```

--------------------------------

### Start frontend dev server with npm run dev

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/quickstart-react.mdx

Runs the Vite development server. Open http://localhost:5173 to use the app.

```bash
npm run dev
```

--------------------------------

### Client setup with JWT authentication

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/auth-design.md

Basic client initialization and authentication using ZerobackClient, passing a JWT token and clearing it on logout.

```typescript
import { ZerobackClient } from "@zeroback/client"

const client = new ZerobackClient("ws://localhost:8788/ws")

// Pass the JWT from your auth provider
client.setAuth(tokenFromClerk)

// Clear on logout
client.clearAuth()
```

--------------------------------

### paginate usage example

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/database.md

Example of cursor-based pagination: first page with cursor null, then next page using the returned continueCursor.

```ts
// First page
const { page, continueCursor, isDone } = await ctx.db
  .query("messages")
  .withIndex("by_channel", (q) => q.eq("channel", "general"))
  .order("desc")
  .paginate({ cursor: null, numItems: 20 });

// Next page
const page2 = await ctx.db
  .query("messages")
  .withIndex("by_channel", (q) => q.eq("channel", "general"))
  .order("desc")
  .paginate({ cursor: continueCursor, numItems: 20 });
```

--------------------------------

### Project Structure

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/AGENTS.md

Directory layout of the Zeroback monorepo, showing the packages, examples, and e2e test directories.

```text
packages/
  values/     - Validators and core types (v.string(), etc.)
  server/     - Schema, functions, database APIs
  client/     - ZerobackClient with WebSocket, optimistic updates
  react/      - React hooks: useQuery, useMutation
  cli/        - zeroback init/dev/deploy/codegen
  solid/      - SolidJS bindings (experimental)
examples/
  task-manager/ - E2E test project
e2e/          - Vitest e2e tests
```

--------------------------------

### Example: defining a table with compound indexes

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/schema.md

Shows how to add two indexes to a table: by_project on projectId and by_project_status on projectId and status.

```ts
defineTable({
  title: v.string(),
  projectId: v.string(),
  status: v.string(),
})
  .index("by_project", ["projectId"])
  .index("by_project_status", ["projectId", "status"])
```

--------------------------------

### useAction usage example

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/react.md

Example of using useAction to get an action executor and calling it with arguments. The action reference is from api.* and the returned function is async.

```tsx
const doAction = useAction(api.tasks.createViaAction);

const result = await doAction({
  title: "New task",
  status: "todo",
  priority: "medium",
  projectId: "proj123",
});
```

--------------------------------

### GET /auth/sign-in/social?provider=google

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/authentication.md

Starts OAuth sign-in with the specified provider.

```APIDOC
## GET /auth/sign-in/social?provider=google

### Description
Starts OAuth sign-in with the specified provider.

### Method
GET

### Endpoint
/auth/sign-in/social?provider=google

### Parameters
#### Query Parameters
- provider (string) - Required - The OAuth provider (e.g., google).

### Response
#### Success Response (302)
Redirects to the OAuth provider.
```

--------------------------------

### Initialize Zeroback with npx @zeroback/cli init

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/quickstart-react.mdx

Scaffolds a zeroback/ directory with a starter schema and todo functions.

```bash
npx @zeroback/cli init
```

--------------------------------

### Scaffold a new project with npx @zeroback/cli init

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/README.md

Scaffolds a new project with the Zeroback CLI, changes into the project directory, and installs the server package.

```bash
npx @zeroback/cli init my-app
cd my-app
npm install @zeroback/server
```

--------------------------------

### Add SSR section to react.md

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/superpowers/plans/2026-04-01-ssr-fetch.md

Markdown section to append to docs/src/content/docs/react.md after `## useZerobackClient()`. It documents the SSR API with code examples for `preloadQuery` and `usePreloadedQuery`, including a TanStack Start example. The note warns that `ZerobackClient` should be constructed browser-side only.

```markdown
## SSR / Server-Side Rendering

Zeroback supports server-side rendering with `preloadQuery` and `usePreloadedQuery`. Call `preloadQuery` in your server-side loader to fetch data over HTTP (no WebSocket required), pass the result as a prop, and use `usePreloadedQuery` in the component to receive the preloaded data and subscribe to live updates after hydration.

Components that don't need SSR keep using `useQuery` unchanged. Adoption is opt-in per component.

### `preloadQuery(deploymentUrl, ref, args?)`

Fetches a query result over HTTP. Import from `@zeroback/client`. Safe to call in Node.js, Edge runtime, or any server environment.

```ts
import { preloadQuery } from "@zeroback/client"
import { api } from "../zeroback/_generated/api"

const preloaded = await preloadQuery(
  process.env.ZEROBACK_URL!,  // same URL you pass to ZerobackClient
  api.tasks.recent,
  { limit: 20 }
)
```

| Parameter | Type | Description |
|---|---|---|
| `deploymentUrl` | `string` | Your Zeroback WebSocket URL (same as `ZerobackClient`) |
| `ref` | `FunctionReference<"query">` | A query reference from `api.*` |
| `args` | `Ref["_args"]` | Query arguments. Defaults to `{}`. |

**Returns:** `Promise<Preloaded<Ref>>` — a serializable object to pass as a prop to `usePreloadedQuery`.

**Throws** if the function is not found, is internal, is not a query type, or if the server returns an error.

### `usePreloadedQuery(preloaded)`

Client hook that starts with the preloaded data (no loading state, no `undefined`) and subscribes to real-time WebSocket updates after hydration. Import from `@zeroback/react`.

```ts
function usePreloadedQuery<Ref extends FunctionReference<"query">>(
  preloaded: Preloaded<Ref>
): Ref["_returns"]
```

**Returns:** The query result — always defined, never `undefined`.

Must be used inside a `ZerobackProvider` for real-time updates after hydration.

### TanStack Start example

```ts
// app/routes/tasks.tsx
import { createServerFn, createFileRoute } from "@tanstack/start"
import { preloadQuery } from "@zeroback/client"
import { usePreloadedQuery } from "@zeroback/react"
import { api } from "../zeroback/_generated/api"

const ZEROBACK_URL = process.env.ZEROBACK_URL!

const loadTasks = createServerFn().handler(async () => {
  return { preloaded: await preloadQuery(ZEROBACK_URL, api.tasks.recent, { limit: 20 }) }
})

export const Route = createFileRoute("/tasks")({
  loader: () => loadTasks(),
  component: TasksPage,
})

function TasksPage() {
  const { preloaded } = Route.useLoaderData()
  const tasks = usePreloadedQuery(preloaded)  // never undefined, real-time after hydration

  return (
    <ul>
      {tasks.map((task) => (
        <li key={task._id}>{task.title}</li>
      ))}
    </ul>
  )
}
```

> **Note:** `ZerobackClient` should be constructed browser-side only. For TanStack Start, create the client and render `ZerobackProvider` in a client-only layout component. The `usePreloadedQuery` hook handles the case where no provider is present during SSR rendering.
```

--------------------------------

### db.query(table) signature and usage

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/database.md

Starts a query on a table and returns a QueryBuilder for chaining. The example collects all documents from the 'tasks' table.

```ts
db.query<T extends keyof DataModel>(table: T): QueryBuilder<DataModel[T]>
```

```ts
const tasks = await ctx.db.query("tasks").collect();
```

--------------------------------

### Mutation to generate upload URL

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/storage.md

Example mutation that calls ctx.storage.generateUploadUrl() and returns the URL. This is the first step in the typical workflow: client gets an upload URL, uploads the file directly to R2, then calls another mutation with the storage ID.

```ts
export const generateUploadUrl = mutation({
  args: {},
  handler: async (ctx) => {
    return await ctx.storage.generateUploadUrl();
  },
});
```

--------------------------------

### zeroback init command usage

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/cli.md

Shows the syntax for the zeroback init command, which scaffolds a new Zeroback project. The dir argument defaults to ".".

```bash
zeroback init [dir]
```

--------------------------------

### Scaffold project with zeroback init

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/authentication.md

Scaffold a new Zeroback project with the default auth setup, or skip auth entirely using the --no-auth flag.

```bash
zeroback init my-app
```

```bash
zeroback init my-app --no-auth
```

--------------------------------

### Import and instantiate ZerobackClient

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/client.md

Shows how to import ZerobackClient and create a new instance with a WebSocket URL and optional options.

```ts
import { ZerobackClient } from "@zeroback/client";

const client = new ZerobackClient(url: string, options?: ZerobackClientOptions);
```

--------------------------------

### createQuery Usage Example

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/solid.md

Example of using createQuery with a reactive accessor for dynamic arguments.

```tsx
import { api } from "../zeroback/_generated/api";
import { createQuery } from "@zeroback/solid";

function TaskList(props: { projectId: string }) {
  const tasks = createQuery(api.tasks.listByProject, () => ({
    projectId: props.projectId,
  }));

  return (
    <ul>
      <For each={tasks()}>{(task) => <li>{task.title}</li>}</For>
    </ul>
  );
}
```

--------------------------------

### Create a React app with Vite (npm, bun, pnpm, yarn)

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/quickstart-react.mdx

Use the package manager of your choice to scaffold a new React TypeScript project named my-todo and navigate into it.

```bash
npm create vite@latest my-todo -- --template react-ts
cd my-todo
```

```bash
bun create vite my-todo --template react-ts
cd my-todo
```

```bash
pnpm create vite my-todo --template react-ts
cd my-todo
```

```bash
yarn create vite my-todo --template react-ts
cd my-todo
```

--------------------------------

### filter usage example

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/database.md

Example of using .filter() with q.and, q.eq, and q.gte operators. See FilterBuilder for available operators.

```ts
ctx.db.query("tasks")
  .filter((q) => q.and(
    q.eq(q.field("status"), "active"),
    q.gte(q.field("score"), 100)
  ))
  .collect();
```

--------------------------------

### client.init()

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/client.md

Initializes the client with persistence, hydrating cached data from IndexedDB, connecting the WebSocket, and replaying offline mutations. Only needed when persistence is enabled.

```APIDOC
## client.init()

### Description
Initializes the client with persistence. Hydrates cached data from IndexedDB, connects the WebSocket, and replays any offline mutations. Only needed when persistence is enabled; without persistence, the client connects automatically on construction.

### Method
init

### Signature
```ts
await client.init(): Promise<void>
```

### Parameters
None.

### Returns
Promise<void>

### Example
```ts
const client = new ZerobackClient(url, { persistence: true });
await client.init(); // hydrate cache, connect, replay offline mutations
```
```

--------------------------------

### useMutation Usage Example

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/react.md

Example component using useMutation to create a task. Imports the api and useMutation, then calls the mutation with task details.

```tsx
import { api } from "../zeroback/_generated/api";
import { useMutation } from "@zeroback/react";

function CreateTask({ projectId }: { projectId: string }) {
  const createTask = useMutation(api.tasks.create);

  const handleCreate = async () => {
    await createTask({
      title: "New task",
      status: "todo",
      priority: "medium",
      projectId,
    });
  };

  return <button onClick={handleCreate}>Create Task</button>;
}
```

--------------------------------

### Create HTTP router with `httpRouter()`

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/functions.md

Creates a new HTTP router instance. The example imports `httpRouter` and `httpAction` from `@zeroback/server`, creates a router, and exports it as default.

```ts
import { httpRouter, httpAction } from "@zeroback/server";

const http = httpRouter();
// ... register routes ...
export default http;
```

--------------------------------

### useQueryWithStatus Usage Example

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/react.md

Example component using useQueryWithStatus to display a task list. Shows loading state and a stale indicator when data is from cache.

```tsx
function TaskList({ projectId }: { projectId: string }) {
  const { data: tasks, isLoading, isStale } = useQueryWithStatus(
    api.tasks.listByProject,
    { projectId }
  );

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      {isStale && <span>Updating...</span>}
      <ul>
        {tasks.map((task) => (
          <li key={task._id}>{task.title}</li>
        ))}
      </ul>
    </div>
  );
}
```

--------------------------------

### Initialize Zeroback without built-in auth (--no-auth)

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/authentication.md

Scaffolds a new Zeroback project without built-in authentication. No zeroback/auth.ts is created, no auth routes are mounted, and ctx.auth is not available in functions. Use this when you want to authenticate users before they reach Zeroback, such as with a Cloudflare Access policy or a JWT verified in your Worker.

```bash
zeroback init my-app --no-auth
```

--------------------------------

### Project structure for a Zeroback app

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/README.md

Shows the recommended project layout for a Zeroback app. The `zeroback/` directory holds backend code (schema, tasks, and auto-generated files), while `src/` holds frontend code. `wrangler.toml` and `.zeroback/entry.ts` are scaffolded by `zeroback init` and can be customized.

```text
your-project/
├── zeroback/                      # Your backend code
│   ├── schema.ts             # Table definitions
│   ├── tasks.ts              # Query & mutation functions
│   └── _generated/           # Auto-generated (don't edit)
│       ├── api.ts            # Typed API references
│       ├── server.ts         # Typed query/mutation factories
│       └── dataModel.ts      # TypeScript types for tables
├── src/                      # Your frontend code
│   └── App.tsx
├── wrangler.toml             # Scaffolded by zeroback init, user can customize
├── package.json
└── .zeroback/
    └── entry.ts              # Scaffolded by zeroback init, user can customize
```

--------------------------------

### client.auth.signUp

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/authentication.md

Creates a new user account using the client SDK.

```APIDOC
## client.auth.signUp

### Description
Creates a new user account using the client SDK.

### Method
SDK Method

### Parameters
- email (string) - Required - The user's email address.
- password (string) - Required - The user's password.
- name (string) - Required - The user's display name.

### Request Example
await client.auth.signUp({
  email: "user@example.com",
  password: "password123",
  name: "Alice",
})

### Response
Returns the created user object.
```

--------------------------------

### withIndex usage examples

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/database.md

Examples of using .withIndex() with no constraints, equality, compound, and range queries. The callback uses IndexRangeBuilder methods eq, gte, and lt.

```ts
// Use index without constraints (scan in index order)
ctx.db.query("tasks").withIndex("by_id").order("desc").take(50);

// Equality match
ctx.db.query("tasks")
  .withIndex("by_project", (q) => q.eq("projectId", "proj123"))
  .collect();

// Compound index
ctx.db.query("tasks")
  .withIndex("by_project_status", (q) =>
    q.eq("projectId", "proj123").eq("status", "active")
  )
  .collect();

// Range query
ctx.db.query("events")
  .withIndex("by_date", (q) =>
    q.gte("date", startDate).lt("date", endDate)
  )
  .collect();
```

--------------------------------

### Enable auth namespace and use email/password methods

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/authentication.md

Enable the auth namespace by passing `auth: true` to the `ZerobackClient` constructor. Then use `client.auth.signUp`, `client.auth.signIn`, `client.auth.getSession`, and `client.auth.signOut` to manage email/password authentication. `getSession` returns a user object or `null`.

```typescript
import { ZerobackClient } from "@zeroback/client"

const client = new ZerobackClient("wss://your-worker.workers.dev/ws", {
  auth: true,
})

// Sign up
await client.auth.signUp({
  email: "user@example.com",
  password: "password123",
  name: "Alice",
})

// Sign in
await client.auth.signIn({
  email: "user@example.com",
  password: "password123",
})

// Get the current session
const session = await client.auth.getSession()
// { user: { id, email, name, image } } or null

// Sign out
await client.auth.signOut()
```

--------------------------------

### createAction usage example

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/solid.md

Example of calling createAction with api.tasks.createViaAction and awaiting the returned function with an object containing task fields like title, status, priority, and projectId.

```tsx
const doAction = createAction(api.tasks.createViaAction);

const result = await doAction({
  title: "New task",
  status: "todo",
  priority: "medium",
  projectId: "proj123",
});
```

--------------------------------

### zeroback deploy command usage

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/src/content/docs/cli.md

Shows the syntax for the zeroback deploy command, which builds and deploys to Cloudflare. Includes options for dry-run and passing extra arguments to wrangler.

```bash
zeroback deploy [functionsDir] [--dry-run] [-- wranglerArgs...]
```

--------------------------------

### Run preloadQuery tests (expected fail)

Source: https://github.com/zerodeploy-dev/zeroback/blob/main/docs/superpowers/plans/2026-04-01-ssr-fetch.md

Command to run the preloadQuery test suite with bun, expected to fail initially because the module does not exist yet.

```Bash
bun test packages/client/src/preloadQuery.test.ts
```
Tokens:
Raw