Zero is the local first platform for building incredible, super fast apps.
To use Zero Svelte, you need to follow the Zero docs to get started.
Watch this Zero Sync Makes Local First Easy
- Follow ZERO DOCS to get started with Zero
- Install
npm install zero-svelte - Usage
Define your schema with defineQueries for type-safe, reusable queries:
src/schema.ts
import {
boolean,
createBuilder,
createSchema,
defineQueries,
defineQuery,
relationships,
string,
table
} from '@rocicorp/zero';
import { type } from 'arktype'; // or use zod
const types = table('type').columns({ id: string(), name: string() }).primaryKey('id');
const todos = table('todo')
.columns({
id: string(),
title: string(),
completed: boolean(),
type_id: string()
})
.primaryKey('id');
const todoRelationship = relationships(todos, ({ one }) => ({
type: one({
sourceField: ['type_id'],
destField: ['id'],
destSchema: types
})
}));
export const schema = createSchema({
tables: [types, todos],
relationships: [todoRelationship]
});
export type Schema = typeof schema;
// Create a typed ZQL builder for raw queries
export const zql = createBuilder(schema);
// Define reusable queries with validators
export const queries = defineQueries({
todo: {
all: defineQuery(() => zql.todo.related('type')),
byCompleted: defineQuery(type({ completed: 'boolean' }), ({ args: { completed } }) =>
zql.todo.where('completed', '=', completed).related('type')
)
},
type: {
all: defineQuery(() => zql.type)
}
});
// Register schema as default type for Zero (removes need for explicit generics)
declare module '@rocicorp/zero' {
interface DefaultTypes {
schema: Schema;
}
}src/lib/zero.svelte.ts
import { PUBLIC_SERVER } from '$env/static/public';
import { Z } from 'zero-svelte';
import { mutators } from '../mutators.js';
import { schema } from '../schema.js';
// No need for explicit Schema generic when using DefaultTypes
export const z = new Z({
cacheURL: PUBLIC_SERVER,
schema,
mutators,
userID: 'anon',
kvStore: 'mem'
});
export { mutators };Make sure your app has SSR turned off.
+page.ts or +layout.ts
export const ssr = false;+page.svelte
<script lang="ts">
import { z, mutators } from '$lib/zero.svelte';
import { queries } from '../schema.js';
// Create a query using defineQuery
const todos = z.createQuery(queries.todo.all());
const randID = () => Math.random().toString(36).slice(2);
function onsubmit(event: Event) {
event.preventDefault();
const formData = new FormData(event.target as HTMLFormElement);
const title = formData.get('title') as string;
if (title) {
// Mutations use the mutators pattern
z.mutate(mutators.todo.insert({ id: randID(), title, completed: false, type_id: '' }));
(event.target as HTMLFormElement).reset();
}
}
function toggleTodo(id: string, completed: boolean) {
z.mutate(mutators.todo.update({ id, completed }));
}
</script>
<form {onsubmit}>
<input type="text" name="title" />
<button type="submit">Add</button>
</form>
<ul>
{#each todos.data as todo (todo.id)}
<li>
<input
type="checkbox"
checked={todo.completed}
oninput={() => toggleTodo(todo.id, !todo.completed)}
/>
{todo.title} - {todo.type?.name}
</li>
{/each}
</ul>Use $derived to create queries that react to state changes:
<script lang="ts">
import { z } from '$lib/zero.svelte';
import { queries } from '../schema.js';
let showCompleted = $state(false);
// Query recreates when showCompleted changes
const filtered = $derived(z.createQuery(queries.todo.byCompleted({ completed: showCompleted })));
</script>
<label>
<input type="checkbox" bind:checked={showCompleted} />
Show completed only
</label>
{#each filtered.data as todo (todo.id)}
<div>{todo.title}</div>
{/each}For client-side filtering without server round-trips (great for search):
<script lang="ts">
import { z } from '$lib/zero.svelte';
import { zql } from '../schema.js';
let searchText = $state('');
// Filters data already synced - no server round-trip per keystroke
const searchResults = $derived.by(() => {
let q = zql.todo.related('type');
if (searchText) {
q = q.where('title', 'ILIKE', `%${searchText}%`);
}
return z.createQuery(q);
});
</script>
<input type="text" placeholder="Search..." bind:value={searchText} />
{#each searchResults.data as todo (todo.id)}
<div>{todo.title}</div>
{/each}Monitor connection status with connectionState (analogous to React's useConnectionState hook):
<script lang="ts">
import { z } from '$lib/zero.svelte';
</script>
<!-- States: connecting | connected | disconnected | needs-auth | error | closed -->
{#if z.connectionState.name === 'connected'}
<span>Connected</span>
{:else if z.connectionState.name === 'connecting'}
<span>Connecting...</span>
{:else if z.connectionState.name === 'disconnected'}
<span>Disconnected: {z.connectionState.reason}</span>
{:else if z.connectionState.name === 'needs-auth'}
<span>
Auth Required
<button onclick={() => z.connection.connect()}>Retry</button>
</span>
{:else if z.connectionState.name === 'error'}
<span>
Error: {z.connectionState.reason}
<button onclick={() => z.connection.connect()}>Retry</button>
</span>
{:else if z.connectionState.name === 'closed'}
<span>Closed</span>
{/if}Use z.connection.connect() to manually retry connections, optionally with a new auth token:
// Retry connection
await z.connection.connect();
// Retry with new auth token
await z.connection.connect({ auth: newToken });Gate query materialization using the enabled parameter:
<script lang="ts">
import { z } from '$lib/zero.svelte';
import { queries } from '../schema.js';
let enabled = $state(true);
// Query won't materialize until enabled is true
const todos = $derived(z.createQuery(queries.todo.all(), enabled));
</script>
<label>
<input type="checkbox" bind:checked={enabled} />
Enable query
</label>For stable query instances that update in place:
<script lang="ts">
import { z } from '$lib/zero.svelte';
import { zql } from '../schema.js';
const todos = z.createQuery(zql.todo.related('type'));
function applyFilter(typeId: string | undefined) {
const q = typeId
? zql.todo.where('type_id', '=', typeId).related('type')
: zql.todo.related('type');
todos.updateQuery(q);
}
</script>z.createQuery(query, enabled?)- Create a reactive queryz.q(query, enabled?)- Alias for createQueryz.mutate(mutator)- Execute a mutationz.connectionState- Current connection state (reactive)z.connection- Connection API for manual controlz.connection.connect(opts?)- Retry connection from error/needs-auth statez.online- (deprecated) UseconnectionStateinsteadz.build(options)- Rebuild the Zero instance (useful for auth changes)z.close()- Close the Zero instance
query.data- The query results (reactive)query.details- Query status detailsquery.updateQuery(newQuery, enabled?)- Update the query in place
See demo for real working code.
See Zero docs for more info.
Listen to Syntax for tasty web development treats.
- Run
pnpm installto install dependencies (Node 22+). - Run
pnpm run verifybefore pushing. It formats, lints, typechecks, builds, and packages. - If a PR changes published code under
src/lib/**orpackage.json, runpnpm changesetand commit the generated.changeset/*.mdfile. - If a PR is docs/CI/dev-only and shouldn't trigger a release, apply the
skip-releaselabel. - CI mirrors this flow and will gate PRs on missing changesets and uncommitted formatting.