# @spacefast/zero
> Author-facing client and server helpers for Spacefast Zero apps.
Latest version **0.5.0** (published 2026-09-29) · MIT license · 0 weekly downloads
## Install
```sh
npm install @spacefast/zero
pnpm add @spacefast/zero
yarn add @spacefast/zero
bun add @spacefast/zero
```
## Health
**Score 60/100 (C)** — status: active.
Positive: esm support; no vulnerabilities; recently updated; high maintenance score.
Warnings: low downloads; no types; pre 1.0.
## Facts
| | |
|---|---|
| Version | 0.5.0 |
| Published | 2026-09-29 |
| First published | 2026-06-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=20 |
| Dependencies | 4 |
| Unpacked size | 557.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | bi |
## Links
- npm: https://www.npmjs.com/package/@spacefast/zero
- Repository: https://github.com/spacefast/monorepo
- Homepage: https://github.com/spacefast/monorepo#readme
- Issues: https://github.com/spacefast/monorepo/issues
- npm.io page: https://npm.io/package/@spacefast/zero
## Dependencies (4)
- [zod](https://npm.io/package/zod.md) 4.3.6
- [preact](https://npm.io/package/preact.md) ^10.29.7
- [lucide-preact](https://npm.io/package/lucide-preact.md) ^0.575.0
- [@spacefast/common](https://npm.io/package/@spacefast/common.md) 0.5.0
## Recent versions
- 0.5.0 (latest) — 2026-09-29
- 0.4.1 — 2026-09-10
- 0.2.2 — 2026-08-28
- 0.0.26 — 2026-08-22
- 0.0.24 — 2026-08-12
- 0.0.23 — 2026-08-06
- 0.0.21 — 2026-08-05
- 0.0.20 — 2026-08-05
- 0.0.19 — 2026-08-05
- 0.0.18 — 2026-08-05
- 0.0.17 — 2026-08-05
- 0.0.13 — 2026-07-31
- 0.0.12 — 2026-07-27
- 0.0.11 — 2026-07-19
- 0.0.10 — 2026-07-19
- … 7 more at https://npm.io/package/@spacefast/zero/versions
## README
# Zero
A Zero capsule can use an authored page tree or a standalone browser app. Put addressable pages in `pages/`, collection data in `content/`, and reusable browser components in `client/`.
```text
pages/
index.md
about.tsx
docs/getting-started.html
projects/[id].tsx
client/
index.tsx
components/counter.tsx
content/
posts/hello.md
server/
index.ts
```
## Documents and interactive pages
Markdown and HTML are editable documents. TSX is a document by default: the compiler turns its JSX into Gutenberg block markup. Import a component from `client/` to add an island without turning the whole document into a browser application.
```tsx
// pages/about.tsx
import { Counter } from "../client/components/counter";
export default function About() {
return (
<>
About
);
}
```
An interactive page declares its browser execution boundary explicitly:
```tsx
// pages/projects/[id].tsx
"use client";
export default function Project({ params }: { params: { id: string } }) {
return Project {params.id};
}
```
`index` names the containing route. `[id]` names one path segment; `[...rest]` names a nonempty remaining path. Parameterized routes require client rendering. Document pages have literal URLs, including `/` and nested paths.
When the capsule has authored pages, the optional `client/index.tsx` module may export a named `Layout` for interactive pages. Its default export or an `App` export does not own `/` in this mode; write `pages/index.tsx` for that page.
Without authored pages, `client/index.tsx` can instead export a default component or a named `App`. Zero mounts that component as a standalone browser application, which owns its client routes. The component can use `Router`, `Routes`, and `Route` from `@spacefast/zero/client`.
## One owner per route
Both renderers appear in the same compiled inventory. Literal routes take precedence over parameters, and parameters over catchalls. Equivalent page patterns, endpoint collisions, and authored static files that would shadow a page are build errors.
Public native posts bound to the `content` field also get document routes in this inventory, at their bare slug (`content/posts/hello.md` becomes `/hello`). Private collections do not gain public routes. A post and an authored page cannot both own the same URL. Editor-created documents acquire their routes through the ordinary source commit, build, and publish path, not an undeclared WordPress fallback.
The browser uses the same ownership rules as a hard reload. Navigation between client pages stays in the browser router. Document and unknown destinations use normal document navigation; they are never swallowed by a generic SPA fallback. Client shells live under the platform asset namespace, not at a generated root `index.html`.
## Editing documents
A page's identity comes from its canonical route, not its source extension. Editing a document authored in TSX creates canonical HTML beside the TSX source. The HTML owns the same page; subsequent builds do not execute the superseded TSX. This is an ownership change, not a claim that arbitrary TypeScript can roundtrip through Gutenberg.
Client pages remain code-owned. Put content those pages edit or display in a collection or document binding.
Publication seals each document's exact Markdown/HTML source or compiled TSX markup into the content-model release. Activation verifies those bytes and reconciles the WordPress document before advancing the active model. A request never seeds or mutates content just because someone viewed a page. Immutable version URLs render the sealed document under that version's model; dynamic blocks may still query live data through the pinned model and code.
## Local development
The local Zero dev server serves declared client routes and returns 404 for unknown routes. Full document rendering requires WordPress. Without it, document routes return `501 zero_dev_document_rendering_unsupported`; append `?spacefast_view=1` for an explicit compiled-markup preview. That preview does not execute WordPress dynamic blocks or hydrate islands and is not a production-rendering check.
`_pages/` is separate because its files are platform response templates, such as an access gate or a 404 response. They are not independently addressable application pages.
## Data and server handlers
The server entry exports one capsule. Queries expose reads, mutations perform database writes, and actions run without a database transaction. Handler arguments become the browser client's argument types.
```ts
// server/index.ts
import {
action,
boolean,
capsule,
endpoint,
json,
mutation,
number,
query,
string,
table,
userId,
} from "@spacefast/zero/server";
export default capsule({
name: "Task board",
schema: {
tasks: table({
owner: userId(),
title: string(),
estimate: number().default(0),
note: string().optional(),
done: boolean().default(false),
}).index("by_owner", ["owner"]),
},
auth: {
onGuestUpgrade(ctx, { guestUserId, userId }) {
ctx.log.info("Guest signed in", { guestUserId, userId });
},
},
queries: {
tasks: query(async (ctx) => {
const { userId } = ctx.auth.requireIdentity();
return ctx.db.tasks.withIndex("by_owner", (range) => range.eq("owner", userId)).collect();
}),
taskCount: query(async (ctx) => {
const { userId } = ctx.auth.requireIdentity();
return ctx.db.tasks.withIndex("by_owner", (range) => range.eq("owner", userId)).count();
}),
},
mutations: {
addTask: mutation(async (ctx, title: string) => {
const { userId } = ctx.auth.requireIdentity();
if (!title.trim()) throw new Error("Enter a task title.");
const task = await ctx.db.tasks.insert({ owner: userId, title });
ctx.invalidate("tasks", "taskCount");
return task;
}),
},
actions: {
notify: action(async (ctx, message: string) => {
ctx.auth.requireSignedIn();
const url = ctx.env.NOTIFY_URL;
if (!url) throw new Error("Set NOTIFY_URL before sending notifications.");
const response = await fetch(url, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ message }),
});
if (!response.ok) throw new Error("The notification service rejected the request.");
return { sent: true };
}),
},
endpoints: {
health: endpoint({ method: "GET", path: "/api/health" }, () => json({ ok: true })),
},
});
```
`userId()` stores an identity reference. It does not fill the field or restrict reads automatically. The example assigns the caller's identity and filters every read by that identity. Handlers must also check ownership before updating or deleting a caller-supplied row ID.
| Field | Stored value |
| ------------- | ---------------------------------------------------- |
| `string()` | String |
| `boolean()` | Boolean |
| `number()` | Finite number, including decimals |
| `id("tasks")` | Reference to a row in the named table |
| `userId()` | Nonempty identity string, included in guest upgrades |
Required fields must be supplied on insert. `.default(value)` supplies an omitted field. `.optional()` permits omission and permits `null` on insert or update to clear the field; reads return an absent property rather than `null`. When an optional field also has a default, absence or `null` resolves to that default.
Rows include `id`, `createdAt`, and `updatedAt`. `insert()` returns the row; `get()` and `update()` return a row or `null`; `delete()` returns a boolean. Named indexes use `.index("name", ["field"])`. Every table also has `by_creation`.
An indexed read supports `eq`, `gt`, `gte`, `lt`, and `lte` range bounds, followed by `collect()`, `first()`, `take(n)`, `paginate({ cursor, numItems })`, or `count()`. `count()` counts the selected range without collecting its rows.
## Browser calls and loading
The browser imports the capsule as a type, so server code and environment variables stay out of the browser bundle. This example uses standalone mode with no `pages/` directory. With authored pages, put the component in `pages/index.tsx` and add `"use client"` at the top.
```tsx
// client/index.tsx
import { createClient, SignInWithGoogle, useAuth } from "@spacefast/zero/client";
import type app from "../server/index";
const api = createClient();
export default function App() {
const auth = useAuth();
const tasks = api.useQuery("tasks");
const count = api.useQuery("taskCount");
const addTask = api.useMutation("addTask");
const notify = api.useAction("notify");
if (auth.error) return
);
}
```
`useQuery()` returns `undefined` while its initial result is loading. A query returning a number, object, or `null` keeps that result shape; an empty array means the query actually returned an empty array. Handle loading before reading properties or calling array methods.
Mutation and action hooks return promise-returning functions. Mutations refresh live queries after a successful write. `ctx.invalidate(...queryNames)` narrows the refresh; omitting it refreshes every live query. Actions neither refresh subscriptions automatically nor replay as subscriptions. Display rejected calls through your app's error handling.
An action runs without a database transaction and has read-only database access. It can send mail through `ctx.email`, but cannot insert, update, or delete rows. It has no `ctx.query`, `ctx.mutate`, or `ctx.runQuery` helper. Action arguments are limited to 16 KiB, serialized results to 48 KiB, and execution to five seconds. Use mutations or write endpoints for database writes.
Global `fetch()` is available in queries, mutations, actions, and endpoints. Outbound requests follow the Space's egress permissions and runtime limits.
## Using React
Building your front end outside the capsule, say an Astro site with React islands? Import the hooks from `@spacefast/zero/react`. They talk to the same client, cache, and realtime socket as `@spacefast/zero/client`, and `createClient()` infers the same way.
```tsx
import { createClient, useAuth, useQuery } from "@spacefast/zero/react";
import type app from "../server/index";
const api = createClient();
export function Tasks() {
const auth = useAuth();
const tasks = useQuery(api.tasks());
const addTask = api.useMutation("addTask");
if (auth.isLoading || tasks === undefined) return
Loading tasks...
;
return (
<>
{tasks.map((task) => (
{task.title}
))}
);
}
```
You get `useQuery`, `useMutation`, `useAction`, `usePaginatedQuery`, and `useAuth`, plus `storage` and the `signIn*`/`signOut` functions. React 18 and 19 both work; `react` is an optional peer dependency. A server render shows the loading state (`undefined` queries, `isLoading` auth) and the browser takes over on hydration.
There's no React router or `` components. Your framework owns routing, and a sign-in button is `