https://github.com/a-poor/zero-todo
https://github.com/a-poor/zero-todo
Last synced: 7 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/a-poor/zero-todo
- Owner: a-poor
- Created: 2025-02-13T00:30:07.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-13T00:30:09.000Z (over 1 year ago)
- Last Synced: 2025-03-08T03:26:11.208Z (over 1 year ago)
- Language: TypeScript
- Size: 60.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Hello Zero
## Option 1: Run this repo
First, install dependencies:
```sh
npm i
```
Next, run docker:
```sh
npm run dev:db-up
```
**In a second terminal**, run the zero cache server:
```sh
npm run dev:zero-cache
```
**In a third terminal**, run the Vite dev server:
```sh
npm run dev:ui
```
## Option 2: Install Zero in your own project
This guide explains how to set up Zero in your React application, using this
repository as a reference implementation.
### Prerequisites
**1. PostgreSQL database with Write-Ahead Logging (WAL) enabled**
See [Connecting to Postgres](https://zero.rocicorp.dev/docs/connecting-to-postgres)
**2. Environment Variables**
Set the following environment variables. `ZSTART_UPSTREAM_DB` is the URL to your Postgres
database.
```ini
# Your application's data
ZERO_UPSTREAM_DB="postgresql://user:password@127.0.0.1/mydb"
# A Postgres database Zero can use for storing Client View Records (information
# about what has been synced to which clients). Can be same as above db, but
# nice to keep separate for cleanliness and so that it can scale separately
# when needed.
ZERO_CVR_DB="postgresql://user:password@127.0.0.1/mydb_cvr"
# A Postgres database Zero can use for storing its own replication log. Can be
# same as either of above, but nice to keep separate for same reason as cvr db.
ZERO_CHANGE_DB="postgresql://user:password@127.0.0.1/mydb_cdb"
# Secret to decode auth token.
ZERO_AUTH_SECRET="secretkey"
# Place to store sqlite replica file.
ZERO_REPLICA_FILE="/tmp/zstart_replica.db"
# Where UI will connect to zero-cache.
VITE_PUBLIC_SERVER=http://localhost:4848
```
### Setup
1. **Install Zero**
```bash
npm install @rocicorp/zero
```
2. **Create Schema** Define your database schema using Zero's schema builder.
See [schema.ts](src/schema.ts) for example:
```typescript
import { createSchema, createTableSchema } from "@rocicorp/zero";
const userSchema = createTableSchema({
tableName: "user",
columns: {
id: { type: "string" },
name: { type: "string" },
},
primaryKey: ["id"],
});
export const schema = createSchema({
version: 1,
tables: {
user: userSchema,
},
});
export type Schema = typeof schema;
```
3. **Initialize Zero Client-Side** Set up the Zero provider in your app entry
point. See [main.tsx](src/main.tsx):
```tsx
import { Zero } from "@rocicorp/zero";
import { ZeroProvider } from "@rocicorp/zero/react";
import { schema } from "./schema";
// In a real app, you might initialize this inside of useMemo
// and use a real auth token
const z = new Zero({
userID: "your-user-id",
auth: "your-auth-token",
server: import.meta.env.VITE_PUBLIC_SERVER,
schema,
kvStore: "mem", // or "idb" for IndexedDB persistence
});
createRoot(document.getElementById("root")!).render(
);
```
4. **Using Zero in Components** Example usage in React components. See
[App.tsx](src/App.tsx):
```typescript
import { useQuery, useZero } from "@rocicorp/zero/react";
import { Schema } from "./schema";
// You may want to put this in its own file
const useZ = useZero;
export function UsersPage() {
const z = useZ();
const users = useQuery(z.query.user);
if (!users) {
return null;
}
// Use the data...
return (
{users.map((user) => (
{user.name}
))}
);
}
```
For more examples of queries, mutations, and relationships, explore the
[App.tsx](src/App.tsx) file in this repository.
### Optional: Authentication
This example includes JWT-based authentication. See [api/index.ts](api/index.ts)
for an example implementation using Hono.
### Development
**1. Start the PostgreSQL database:**
If you are using Docker (referencing the example in
[docker](docker/docker-compose.yml)), run:
```bash
npm run docker-up
```
**2. Start the zero cache server (in a separate terminal):**
```bash
npx zero-cache
```
**3. Start your React dev server**
```bash
npm run dev # this depends on your react app setup
```