Skip to main content
This guide will help you install Zero and set up your development environment for building real-time sync applications.

​
Requirements

Zero requires Node.js 22 or higher and a PostgreSQL database (version 15+).
Before you begin, ensure you have:
  • Node.js 22+ installed (download)
  • PostgreSQL 15+ running locally or remotely
  • Docker (optional, for local PostgreSQL development)

​
Install Zero

1

Install the package

Install Zero using npm, pnpm, or yarn:
npm install @rocicorp/zero
The @rocicorp/zero package includes everything you need:
  • Client-side library for queries and mutations
  • Server-side sync engine (zero-cache)
  • Schema builder and type definitions
  • CLI tools for running the sync server
2

Install React bindings (optional)

If you’re using React, the React hooks are included in the main package:
import { useQuery, useZero, ZeroProvider } from '@rocicorp/zero/react';
For other frameworks:
# Solid bindings are included
import { useQuery } from '@rocicorp/zero/solid';
3

Set up PostgreSQL

Zero requires a PostgreSQL database as the source of truth.Create a docker-compose.yml file:
docker-compose.yml
version: '3.8'
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: myapp
    ports:
      - '5432:5432'
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
Start PostgreSQL:
docker compose up -d

​
Option 2: Local PostgreSQL

If you have PostgreSQL installed locally, ensure it’s running and create a database:
createdb myapp

​
Option 3: Cloud PostgreSQL

You can use any PostgreSQL provider:
4

Configure environment variables

Create a .env file in your project root:
.env
# PostgreSQL connection
ZERO_UPSTREAM_DB=postgresql://postgres:postgres@localhost:5432/myapp

# Zero cache configuration
ZERO_REPLICA_FILE=/tmp/zero-replica.db
ZERO_CVR_STORE_FILE=/tmp/zero-cvr.db

# Server port (optional, defaults to 4848)
ZERO_PORT=4848
Never commit .env files to version control. Add .env to your .gitignore.

​
Verify Installation

Create a simple test file to verify Zero is installed correctly:
test-zero.ts
import { createSchema, table, string } from '@rocicorp/zero';

const testTable = table('test')
  .columns({
    id: string(),
    name: string(),
  })
  .primaryKey('id');

const schema = createSchema({
  tables: [testTable],
  relationships: [],
});

console.log('Zero installed successfully!');
console.log('Schema:', schema.tables);
Run it: 
npx tsx test-zero.ts
You should see output confirming Zero is working.

​
Development Setup

For a complete development workflow, you’ll typically run three processes:

​
1. PostgreSQL Database

# Using Docker
docker compose up -d

# Or ensure your local PostgreSQL is running

​
2. Zero Cache Server

The zero-cache server syncs data between PostgreSQL and clients: 
npx zero-cache
For development with hot-reload: 
npx zero-cache-dev
This watches your schema file and automatically restarts when it changes.

​
3. Your Application

Run your web application: 
npm run dev

​
Package Scripts

Add these convenience scripts to your package.json:
package.json
{
  "scripts": {
    "db:up": "docker compose up -d",
    "db:down": "docker compose down",
    "zero-cache": "zero-cache",
    "zero-cache:dev": "zero-cache-dev",
    "dev": "vite",
    "dev:all": "npm run db:up && npm run zero-cache:dev & npm run dev"
  }
}

​
Building from Source

Most users should use the npm package. Only build from source if you’re contributing to Zero or need unreleased features.
To build Zero from the monorepo: 
git clone https://github.com/rocicorp/mono.git
cd mono
npm install
npm run build

# Create a local package
cd packages/zero
npm pack

# Install in your project
npm install /path/to/rocicorp-zero-<VERSION>.tgz

​
Troubleshooting

​
Port Conflicts

If port 4848 is already in use: 
# Find the process
lsof -i :4848

# Kill it
kill <PID>

# Or use a different port
ZERO_PORT=4849 npx zero-cache

​
PostgreSQL Connection Issues

Verify your connection string: 
# Test connection with psql
psql postgresql://postgres:postgres@localhost:5432/myapp
Common issues:
  • Wrong password or username
  • PostgreSQL not running
  • Firewall blocking port 5432
  • Wrong database name

​
SQLite Replica Issues

If you see stale data or corruption: 
# Clear the replica databases
rm /tmp/zero-replica.db*
rm /tmp/zero-cvr.db*

# Restart zero-cache
npx zero-cache

​
Next Steps

Quick Start

Build your first Zero application

Schema Definition

Learn how to define your data schema

Build docs developers (and LLMs) love

Get started for freeTalk to us