Zero Svelte

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

Usage

1. Follow ZERO DOCS to get started with Zero
2. Install npm install zero-svelte
3. Usage

Schema Setup

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;
	}
}

Create your Z instance

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 };

Disable SSR

Make sure your app has SSR turned off.

+page.ts or +layout.ts

export const ssr = false;

Basic Usage

+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>

Reactive Queries with $derived

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}

Local-only Filtering with Raw ZQL

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}

Connection State

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 });

Query with Enabled Flag

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>

Updating Queries with updateQuery

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>

API Reference

Z Class

• z.createQuery(query, enabled?) - Create a reactive query
• z.q(query, enabled?) - Alias for createQuery
• z.mutate(mutator) - Execute a mutation
• z.connectionState - Current connection state (reactive)
• z.connection - Connection API for manual control
• z.connection.connect(opts?) - Retry connection from error/needs-auth state
• z.online - (deprecated) Use connectionState instead
• z.build(options) - Rebuild the Zero instance (useful for auth changes)
• z.close() - Close the Zero instance

Query Class

• query.data - The query results (reactive)
• query.details - Query status details
• query.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.

Contributing

• Run pnpm install to install dependencies (Node 22+).
• Run pnpm run verify before pushing. It formats, lints, typechecks, builds, and packages.
• If a PR changes published code under src/lib/** or package.json, run pnpm changeset and commit the generated .changeset/*.md file.
• If a PR is docs/CI/dev-only and shouldn't trigger a release, apply the skip-release label.
• CI mirrors this flow and will gate PRs on missing changesets and uncommitted formatting.