Style Guide

Copy as MarkdownOpen in...

❌ Complex: The facilitation of real-time synchronization is accomplished through WebSocket protocols.

✅ Clear: Real-time synchronization works through WebSocket connections.

❌ Wordy: In order to get started with using zero-sources, you will need to first install dependencies.

✅ Concise: To start using zero-sources, install the dependencies.

❌ Tell only: You can filter queries using comparison operators.

✅ Show: Filter queries with comparison operators:
```typescript
query.where('age', '>', 18)

## Voice and Tone

### Our Voice

- **Professional** but approachable
- **Helpful** but not condescending
- **Technical** but clear
- **Direct** but friendly

### Tone by Context

**Guides**: Encouraging and supportive

```markdown
✅ Great! You've successfully configured your change source.

✅ Returns a Promise that resolves to an array of Message objects.

✅ Connection failed. Verify that MONGODB_URI is set in your environment.

❌ Passive: The schema is defined by the developer.
✅ Active: Define the schema in your configuration.

❌ Passive: Changes are streamed by the change source.
✅ Active: The change source streams changes to clients.

❌ Third person: Developers should configure environment variables.
✅ Second person: Configure your environment variables.

❌ Impersonal: One must ensure the connection is established.
✅ Direct: Ensure the database connection is established.

❌ Future: The client will connect to the server.
✅ Present: The client connects to the server.

❌ Past: This function returned a promise.
✅ Present: This function returns a promise.

✅ Guide: You'll need to install dependencies first.
✅ Reference: The function returns null if no user is found.

❌ Title Case: How To Configure Your Change Source
✅ Sentence case: How to configure your change source

❌ Wrong case: getting started with Zero
✅ Correct: Getting started with Zero

✅ Correct:
# Page Title (H1)
## Main Section (H2)
### Subsection (H3)
#### Detail (H4)

❌ Don't skip levels:
# Page Title (H1)
### Subsection (H3) ← skipped H2

The library provides:
- Real-time synchronization
- Offline support
- Type-safe queries

To deploy:
1. Build the bundle
2. Configure variables
3. Start services

❌ Mixed:
- Configure the schema
- Starting the server
- You should test the connection

✅ Parallel:
- Configure the schema
- Start the server
- Test the connection

❌ Click [here](./guide.md) for more info.
❌ See https://github.com/cbnsndwch/zero-sources

✅ See the [deployment guide](./guide.md) for details.
✅ View the [zero-sources repository](https://github.com/cbnsndwch/zero-sources).

Click the **Save** button.
The **primary key** must be unique.

This is also called a *discriminated union*.

// ✅ Good - includes types and imports
import { Zero } from '@rocicorp/zero';
import type { Message } from './schema';

async function fetchMessages(roomId: string): Promise<Message[]> {
  const zero = new Zero({ /* config */ });
  return zero.query.message
    .where('roomId', '=', roomId)
    .run();
}

// ❌ Bad - no types, incomplete
function fetchMessages(roomId) {
  return zero.query.message.where('roomId', '=', roomId).run();
}

```typescript
// TypeScript code
```

```bash
# Shell commands
```

```json
// JSON config
```

Use the `createTableSchema()` function to define your schema.

const schema = createTableSchema({
  tableName: 'user',
  columns: { id: { type: 'string' } },
});

pnpm install

npm install

yarn install

pnpm install

pnpm dev

## `functionName(param: Type): ReturnType`

Brief description.

**Parameters:**

- `param` (`Type`) - Parameter description

**Returns:**

`ReturnType` - Return value description

**Example:**

```typescript
const result = functionName('value');

### Configuration Format

```markdown
### `optionName`

- **Type**: `string | number`
- **Required**: Yes/No
- **Default**: `'default-value'`

Description of the option.

**Example:**

```typescript
{
  optionName: 'value'
}

### Error Documentation

```markdown
### Error: ERROR_CODE

**Message**: "Error message text"

**Cause:** Why this error occurs

**Solution:** How to fix it

**Example:**

```typescript
try {
  // code
} catch (error) {
  // handle error
}

## Content Organization

### Frontmatter

Required for every page:

```yaml
---
title: Page Title
description: Brief description for SEO
icon: IconName          # Optional
---

✅ getting-started.mdx
✅ custom-change-sources.mdx

❌ GettingStarted.mdx
❌ custom_change_sources.mdx

guides/
  ├── index.mdx          # Overview
  ├── quick-start.mdx
  └── advanced.mdx

A *discriminated union* (also called a tagged union) allows...

MongoDB Change Data Capture (CDC) enables...

✅ ![Architecture diagram showing three containers](./diagram.png)
❌ ![diagram](./diagram.png)

✅ See the [MongoDB change source documentation](/change-sources/mongodb)
❌ See the documentation [here](/change-sources/mongodb)

✅ # → ## → ### (proper hierarchy)
❌ # → ### (skipped level)

---
title: Getting started with Zero
description: Set up your first Zero application in 5 minutes
---

# Getting started with Zero

This guide walks you through creating your first Zero application.

<Callout type="info">
  **Prerequisites**: Node.js v22+ and pnpm v8+
</Callout>

<Steps>

### Install dependencies

```bash
pnpm add @rocicorp/zero
```

### Create your schema

Define your data structure:

```typescript
import { createTableSchema } from '@rocicorp/zero';

export const userSchema = createTableSchema({
  tableName: 'user',
  columns: {
    id: { type: 'string' },
    name: { type: 'string' },
  },
  primaryKey: ['id'],
});
```

</Steps>

<Callout type="success">
  You've created your first Zero schema!
</Callout>