Quickstart

Prerequisites

  • Docker
  • Node 20+
🤔Note

Run

In one terminal, install and start the database:

git clone https://github.com/rocicorp/hello-zero.git
cd hello-zero
npm install

npm run dev:db-up
Not using npm?

Zero's server component depends on @rocicorp/zero-sqlite3, which contains a binary that requires running a postinstall script. Most alternative package managers (non-npm) disable these scripts by default for security reasons. Here's how to enable installation for common alternatives:

pnpm

For pnpm, either:

  • Run pnpm approve-builds to approve all build scripts, or
  • Add the specific dependency to your package.json:
"pnpm": {
  "onlyBuiltDependencies": [
    "@rocicorp/zero-sqlite3"
  ]
}

Bun

For Bun, add the dependency to your trusted dependencies list:

"trustedDependencies": [
  "@rocicorp/zero-sqlite3"
],

In a second terminal, start zero-cache:

cd hello-zero
npm run dev:zero-cache

In a final terminal, start the UI:

cd hello-zero
npm run dev:ui

Quick Overview

hello-zero is a demo app that allows querying over a small dataset of fake messages between early Zero users.

Here are some things to try:

  • Press the Add Messages button to add messages to the UI. Any logged-in or anonymous users are allowed to add messages.
  • Press the Remove Messages button to remove messages. Only logged-in users are allowed to remove messages. You can hold shift to bypass the UI warning and see that write access control is being enforced server-side – the UI flickers as the optimistic write happens instantly and is then reverted by the server. Press login to login as a random user, then the remove button will work.
  • Open two different browsers and see how fast sync propagates changes.
  • Add a filter using the From and Contains controls. Notice that filters are fully dynamic and synced.
  • Edit a message by pressing the pencil icon. You can only edit messages from the user you’re logged in as. As before you can attempt to bypass by holding shift.
  • Check out the SQL schema for this database in seed.sql.
  • Login to the database with psql postgresql://user:password@127.0.0.1:5430/postgres (or any other pg viewer) and delete or alter a row. Observe that it deletes from UI automatically.

Detailed Walkthrough

Deployment

You can deploy Zero apps to most cloud providers that support Docker and Postgres. See Deployment for more information.