Add to Existing Project

Copy markdown

# Add to Existing Project Zero integrates easily into most JavaScript or TypeScript projects, whether you're using React, Vue, Svelte, Solid, or vanilla JavaScript. ## Prerequisites * A PostgreSQL database with Write-Ahead Logging (WAL) enabled. See [Connecting to Postgres](https://zero.rocicorp.dev/docs/connecting-to-postgres) for setup instructions. * If you are using [TypeScript](https://www.typescriptlang.org/) ensure that [`strictNullChecks`](https://www.typescriptlang.org/tsconfig/#strictNullChecks)is set to `true` in [tsconfig.json](https://www.typescriptlang.org/tsconfig/). If this is not set then the advanced types Zero uses do not work as expected. ## Installation Install the Zero package: ## Environment Variables Configure Zero by creating a `.env` file in your project root: ```bash ZERO_UPSTREAM_DB="postgresql://user:password@127.0.0.1/postgres" ZERO_REPLICA_FILE="/tmp/sync-replica.db" ``` Replace the placeholders with your database connection details. For more options, see [configuration options](https://zero.rocicorp.dev/docs/zero-cache-config). ## Starting the Server Start the Zero server using the CLI: ```bash npx zero-cache-dev ``` The server runs on port 4848 by default. To verify, open `http://localhost:4848`in your browser. If everything is configured correctly, you'll see "OK". > **Schema file location**: By default, `zero-cache` looks for a `schema.ts` file in the root of your project. You can change this by setting the `ZERO_SCHEMA_PATH` environment variable or by providing a `-p --schema-path` flag. ## Defining Your Schema Define your data model schema as described in the [Zero schema documentation](https://zero.rocicorp.dev/docs/zero-schema). Example: ```ts // schema.ts import {createSchema, table, string} from '@rocicorp/zero'; const message = table('message') .columns({ id: string(), body: string(), }) .primaryKey('id'); export const schema = createSchema({ tables: [message], }); export type Schema = typeof schema; ``` If you're using [Prisma](https://www.prisma.io/) or [Drizzle](https://orm.drizzle.team/), you can convert their schemas to Zero schemas using tools listed in the [community section](https://zero.rocicorp.dev/docs/community#database-tools). ### Permissions Update `schema.ts` to include permissions for your tables. For example, to allow all users to read and write to the `message` table, add the following: ```ts // schema.ts import {ANYONE_CAN_DO_ANYTHING, definePermissions} from '@rocicorp/zero'; export const permissions = definePermissions<unknown, Schema>(schema, () => ({ message: ANYONE_CAN_DO_ANYTHING, })); ``` For more details, see [permissions](https://zero.rocicorp.dev/docs/permissions). ## Creating a Zero Instance To create a Zero client instance: ```js import {Zero} from '@rocicorp/zero'; const z = new Zero({ userID: 'anon', server: 'http://localhost:4848', schema, }); ``` In production, avoid hardcoding the server URL. Use environment variables like `import.meta.env.VITE_PUBLIC_SERVER` or `process.env.NEXT_PUBLIC_SERVER`. ## Reading Data To read data, use the `materialize` method on a `Query` from the `Zero`instance. This creates a materialized view that listens for real-time updates to the data: ```js const view = z.query.message.materialize(); view.addListener(data => console.log('Data updated:', data)); ``` When the view is no longer needed, ensure you clean up by destroying it: ```js view.destroy(); ``` For more details, see [Reading Data with ZQL](https://zero.rocicorp.dev/docs/reading-data). ### React React developers can use the `useZero` hook for seamless integration. See [Integrations React](https://zero.rocicorp.dev/docs/react) for more details. ### SolidJS For SolidJS, use the `createZero` function instead of `new Zero`. Refer to [Integrations SolidJS](https://zero.rocicorp.dev/docs/solidjs) for additional information. ### Other Frameworks For other frameworks, see the [UI frameworks](https://zero.rocicorp.dev/docs/community#ui-frameworks)documentation. ## Writing Data Zero supports both simple and advanced data mutations. For basic use cases, use the [CRUD mutator](https://zero.rocicorp.dev/docs/writing-data): ```ts z.mutate.message.insert({id: nanoid(), body: 'Hello World!'}); ``` For more complex scenarios, such as custom business logic, use [custom mutators](https://zero.rocicorp.dev/docs/custom-mutators) to define tailored mutation behavior. ## Server-Side Rendering (SSR) Zero does not yet support SSR. See [SSR](https://zero.rocicorp.dev/docs/zql-on-the-server#ssr) for details on disabling SSR for your framework. ## Deployment Ensure all `.env` variables are set in the production environment. For Zero cache deployment, see [Deployment](https://zero.rocicorp.dev/docs/deployment). For frontend deployment, consult your framework's documentation.

Or, for AI assistants

ALWAYS readllms.txtfor curated documentation pages and examples.

Zero integrates easily into most JavaScript or TypeScript projects, whether you're using React, Vue, Svelte, Solid, or vanilla JavaScript.

Prerequisites

• A PostgreSQL database with Write-Ahead Logging (WAL) enabled. See Connecting to Postgres for setup instructions.
• If you are using TypeScript ensure that strictNullChecks is set to true in tsconfig.json. If this is not set then the advanced types Zero uses do not work as expected.

Installation

Install the Zero package:

Copynpm install @rocicorp/zero

Copypnpm install @rocicorp/zero

# Note: pnpm disables postinstall scripts by default for security.
# Either approve the build:
pnpm approve-builds

# Or add to package.json:
# "pnpm": {
#   "onlyBuiltDependencies": ["@rocicorp/zero-sqlite3"]
# }

Copybun install @rocicorp/zero

# Note: Bun disables postinstall scripts by default for security.
# Add to package.json:
# "trustedDependencies": ["@rocicorp/zero-sqlite3"]

Copyyarn add @rocicorp/zero

Environment Variables

Configure Zero by creating a .env file in your project root:

CopyZERO_UPSTREAM_DB="postgresql://user:password@127.0.0.1/postgres"
ZERO_REPLICA_FILE="/tmp/sync-replica.db"

Replace the placeholders with your database connection details. For more options, see configuration options.

Starting the Server

Start the Zero server using the CLI:

Copynpx zero-cache-dev

The server runs on port 4848 by default. To verify, open http://localhost:4848 in your browser. If everything is configured correctly, you'll see "OK".

Defining Your Schema

Define your data model schema as described in the Zero schema documentation.

Example:

Copy// schema.ts
import {createSchema, table, string} from '@rocicorp/zero';

const message = table('message')
  .columns({
    id: string(),
    body: string(),
  })
  .primaryKey('id');

export const schema = createSchema({
  tables: [message],
});

export type Schema = typeof schema;

If you're using Prisma or Drizzle, you can convert their schemas to Zero schemas using tools listed in the community section.

Permissions

Update schema.ts to include permissions for your tables. For example, to allow all users to read and write to the message table, add the following:

Copy// schema.ts
import {ANYONE_CAN_DO_ANYTHING, definePermissions} from '@rocicorp/zero';

export const permissions = definePermissions<unknown, Schema>(schema, () => ({
  message: ANYONE_CAN_DO_ANYTHING,
}));

For more details, see permissions.

Creating a Zero Instance

To create a Zero client instance:

Copyimport {Zero} from '@rocicorp/zero';

const z = new Zero({
  userID: 'anon',
  server: 'http://localhost:4848',
  schema,
});

In production, avoid hardcoding the server URL. Use environment variables like import.meta.env.VITE_PUBLIC_SERVER or process.env.NEXT_PUBLIC_SERVER.

Reading Data

To read data, use the materialize method on a Query from the Zero instance. This creates a materialized view that listens for real-time updates to the data:

Copyconst view = z.query.message.materialize();
view.addListener(data => console.log('Data updated:', data));

When the view is no longer needed, ensure you clean up by destroying it:

Copyview.destroy();

For more details, see Reading Data with ZQL.

React

React developers can use the useZero hook for seamless integration. See Integrations React for more details.

SolidJS

For SolidJS, use the createZero function instead of new Zero.

Refer to Integrations SolidJS for additional information.

Other Frameworks

For other frameworks, see the UI frameworks documentation.

Writing Data

Zero supports both simple and advanced data mutations. For basic use cases, use the CRUD mutator:

Copyz.mutate.message.insert({id: nanoid(), body: 'Hello World!'});

For more complex scenarios, such as custom business logic, use custom mutators to define tailored mutation behavior.

Server-Side Rendering (SSR)

Zero does not yet support SSR. See SSR for details on disabling SSR for your framework.

Deployment

Ensure all .env variables are set in the production environment. For Zero cache deployment, see Deployment. For frontend deployment, consult your framework's documentation.