CLAUDE.md · pubkey/rxdb

Sections

1. Build Commands
2. Test Commands
3. Development Scripts
4. Docs Hosting
5. Code Style & Patterns
6. Development Workflow
7. Changelog Rule
8. Example Schema Rule
9. Article Internal Linking Rule
10. Documentation Style
11. Documentation Writing Style Guide

First lines (shown under the repo's Apache-2.0 license)

# CLAUDE.md

## Build Commands
- **Build All**: `npm run build`
- **Documentation Build**: `npm run docs:build`

## Test Commands
- **Run All Tests**: `npm run test`
- **Fast Tests (Parallel)**: `npm run test:fast`
- **Fast Memory Tests**: `npm run test:fast:memory`
- **Node Tests**: `npm run test:node`
- **Browser Tests**: `npm run test:browser`
- **Performance Tests**: `npm run test:performance`
- **Lint**: `npm run lint`
- **Lint Fix**: `npm run lint:fix`
- **Check Types**: `npm run check-types`
- **Bundle Size Check**: `npm run test:bundle-size` (after `npm run build`). If a size change is intended, run `npm run bundle-size:update` and commit `config/bundle-size/limits.json`.

## Development Scripts
- **Unwatch Tests**: `npm run dev`
- **Watch Example**: `npm run dev:example`
- **Generate Error Messages**: `npm run generate:error-messages`
- **Start Docs Server**: `npm run docs:serve`

## Docs Hosting
- The docs at rxdb.info are deployed via GitHub Pages from the `docs` branch. They are NOT hosted on Cloudflare Pages; the deploy step in `.github/workflows/cloudflare-pages.yml` is commented out and inactive.
- GitHub Pages serves static files only: there are no server-side functions and no access to request logs. Any feature that needs server-side logic or log analysis requires an external endpoint.

## Code Style & Patterns
- **Language**: TypeScript
- **Database**: RxDB (local-first, NoSQL)
- **State Management**: Reactive (RxJS Observables)
- **Formatting**: Uses ESLint. Run `npm run lint` to check and `npm run lint:fix` to auto-fix.
- **Imports**: Uses ES modules (import/export).
- **Paths**: Source code in `src/`, tests in `test/`, documentation in `docs-src/`.
- **TypeScript**: Do not use enums. Prefer types instead of interfaces.
- **Errors**: Do not use `throw new Error()`. Use `throw newRxError()` or `throw newRxTypeError()` instead to reduce build size and do not include full error messages in production builds. Use the error codes from `src/rx-error.ts` and add new error codes if needed like `PL1`, `PL2`. Example: `throw newRxError('PL1', { plugin });`
- **Comments**: Do NOT write comments that explain why code was changed, replaced, or removed. Nobody reading the code later cares that an API used to be something else or that it was deprecated. Examples of comments that must NOT be added: `// fs.rmdirSync() is deprecated, fs.rmSync() is the replacement`, `// this used to be a forwardRef`, `// renamed from oldName`. That kind of reasoning belongs in the commit message, the pull request, or the changelog entry under `orga/changelog/`. Comments in the code must only explain what the current code does or why the current code has to be this way.
## Development Workflow

```sh
# 1. Make changes

# 2. Build
npm run build

# 3. Run tests
npm run test:fast:memory

# 4. Run lint
npm run lint

# 5. Check TypeScript types
npm run check-types
```

## Changelog Rule
- Whenever you add a testcase or implement a FIX, add a changelog entry file under `orga/changelog/`.
- Changelog entries are JSON files that must match `orga/changelog/schema.json` with the fields `text`, `links` (`url` and `linkText`) and `priority` (1 to 10). See `orga/changelog/README.md`.
- Prefer including a link to the root issue or pull request in the `links` of that changelog entry.
- Do NOT add a changelog entry for changes that are neither a testcase nor a FIX. For example, adding a SEM landingpage under `docs-src/src/pages/sem/` must not produce a changelog entry.

## Example Schema Rule
- Whenever a docs page needs an example schema, example documents, or example queries, use the shared `todos` example schema from the "Example Schema" section of `docs-src/docs/rx-schema.md`. Do NOT invent a new schema (heroes, humans, users, etc.).
- Use the same names everywhere: database variable `myDatabase`, collection `todos`, schema `todoSchema`, document type `TodoDocType`.
- Whenever a page needs example documents, use these (`todo3` and `todo4` leave out `done` and `tags` to show the defaults), so that query results shown as `// > ...` comments are consistent across pages:

```ts
await myDatabase.todos.bulkInsert([
    {
        id: 'todo1',
        name: 'Learn RxDB',
        done: false,
        dueAt: '2026-01-01T10:00:00.000Z',
        priority: 8,
        tags: ['learning', 'rxdb'],
        assignee: { name: 'Alice', email: 'alice@example.com' },
        subtasks: ['todo3']
    },
    {
        id: 'todo2',
        name: 'Buy groceries',
        done: true,
        dueAt: '2026-01-02T09:30:00.000Z',
        priority: 3,
        tags: ['home'],
        assignee: { name: 'Bob' },
        note: 'Milk, eggs, bread'
    },
    {
        id: 'todo3',
        name: 'Set up replication',
        dueAt: '2026-01-03T14:15:00.000Z',
        priority: 10,
        tags: ['rxdb', 'backend']
    },
    {
        id: 'todo4',
        name: 'Clean the kitchen',
        dueAt: '2026-01-04T18:00:00.000Z',
        priority: 1
    }
]);
```

- Do NOT rename or remove fields. A page may only extend the schema when its feature requires it, for example adding `note` to `encrypted`, adding `attachments: {}`, bumping `version` for migrations, or adding a numeric `updatedAt` for replication checkpoints.
- Pages may show a shorter schema with only the fields the example needs, but those fields must keep the names and types of the shared schema.
- Only use a different schema when the feature cannot be shown with the `todos` schema, for example composite primary keys or vector embeddings.
- When the shared schema in `rx-schema.md` changes, update the pages that use it.

## Article Internal Linking Rule
- Whenever you CREATE a new article under `docs-src/docs/` (for example a page under `docs-src/docs/articles/`), internal links MUST go in both directions.
- Inbound: you MUST add internal links to the new article from existing related articles in the same topic cluster. A new article that nothing links to does not rank.
- Outbound: the new article itself MUST link to existing related articles and reference pages in the same cluster. Nearly every first mention of an RxDB concept should link to its page (for example `[RxStorage](./rx-storage.md)`, `[replication](../replication.md)`, the quickstart), and it should link to its sibling articles.
- All these links MUST be in-text links inside prose, placed on a relevant keyword phrase where the topic already comes up. Search the related pages for the concept (for example `grep` for "encrypt", "sensitive data", "plain text") and link from that sentence.
- Do NOT just append a bullet to a `## Follow Up` list. Dumping the link into a Follow Up list is lazy and does not count as satisfying this rule. Find real in-text opportunities.
- Use a descriptive keyword phrase as the anchor text, never "click here". Do this in the same change that creates the article, not as a follow-up.

## Documentation Style
- SHOULD use clear, simple language.
- SHOULD use data and examples to support claims when possible.
- SHOULD be informative.
- SHOULD focus on practical, actionable insights.
- AVOID using em dashes (–) anywhere.
- AVOID constructions like "not just this, but also this".
- AVOID metaphors and cliches.
- AVOID generalizations.
- AVOID upfront warnings or notes, just the output requested.
- AVOID rhetorical questions.
- AVOID specific words like: very, really, literally, actually, certainly, probably, basically, delve, embark, enlightening, esteemed, shed light, craft, creative, imagine, realm, game-changer, unlock, discover, skyrocket, abyss, not alone, in a world where, revolutionize, disruptive, utilize, utilizing, dive deep, tapestry, illuminate, unveil, pivotal, intricate, elucidate, hence, furthermore, realm, however, harness, exciting, groundbreaking, cutting-edge, remarkable, it remains to be seen, glimpse into, navigating, landscape, stark, testament, in summary, in conclusion, moreover, boost, skyrocket, opened up, powerful, inquiries, ever-evolving.
- Review your response and ensure no em dashes.
- MUST format FAQ sections using HTML `<details>` and `<summary>` tags. Ensure there is an empty line before and after the inner markdown content so it parses correctly.
- SHOULD try to use components from the `docs-src/src/components` folder when writing docs.

## Documentation Writing Style Guide

This guide is derived from an analysis of all existing pages in `docs-src/docs/`. Older pages (2023-era) contain hype vocabulary that is now banned; when patterns conflict, follow this guide and the rules above, not legacy pages. Good style models: `articles/realm-to-rxdb-migration.md`, `webmcp.md`, `testing.md`, `rx-storage-localstorage.md`, the newer `articles/alternatives/*.md` pages.

### Frontmatter
- Exactly four fields, always in this order: `title`, `slug`, `description`, `image`. No other fields.
- `slug`: kebab-case filename plus `.html`, for example `slug: partial-sync.html`.
- `image`: `/headers/<slug-basename>.jpg`. Alternative articles use `/headers/alternatives/<slug-basename>.jpg`.
- `title`: Title Case, 40 to 80 chars, keyword first. Use a plain hyphen `-` as separator, never an em dash or `|`. Two modes: plain feature name for reference pages ("Key Compression", "RxQuery") or keyword phrase for articles ("RxDB as a Dexie.js Alternative with Mango Queries and Replication"). The H1 may differ slightly from the title.
- `description`: 1 to 2 sentences, about 120 to 160 chars, contains the primary keyword. Openers like "Compare X with RxDB." or "Learn how ...". Do not use the banned words even though older descriptions contain them.

### Page structure
- MDX component imports go between the frontmatter and the H1.
- One H1 per page. Integration and feature landing pages may use `<HeadlineWithIcon h1 icon={...}>` with an optional `subtitle`.
- Opening paragraph: define the topic in 1 to 4 sentences, bold the primary keyword on first mention, link `[RxDB](https://rxdb.info/)` on first mention in articles, and include 2 to 6 internal links. Articles add a roadmap sentence: "This page explains what X is, where it falls short, and how RxDB ...".
- Place `<RxdbLogo alt="<keyword phrase>" />` after the intro paragraph in articles. It is globally registered, no import needed.
- Article flow: What is X → why X matters or its limits → What RxDB adds (numbered `### 1. ...` subsections) → code samples → FAQ → `## Follow Up` link list.
- Alternative-article flow (`articles/alternatives/`): competitor-first intro that credits the competitor honestly → `## A Short History of X` (with `### A Brief Timeline` bold-year bullets) → `## What is RxDB?` → `## Where X Falls Short` → what RxDB adds → `## Code Sample: ...` sections → a concession section ("When X Still Makes Sense") → `## FAQ` → `## Comparison Table` with header `| Feature | X | RxDB |` (competitor column before RxDB) → `## Follow Up` paragraph plus a `More resources:` bullet list of internal links.
- Plugin and storage page flow: intro ("With the `plugin-name` plugin you can ..." or "The X [RxStorage](./rx-storage.md) is ...") → key features as bold-label bullets → `<PremiumBlock />` or `<BetaBlock since="X.0.0" />` if applicable → usage steps wrapped in `<Steps>` → options → limitations or known problems → FAQ.
- API method headings are the literal API name: `## putAttachment()`, `### awaitInitialReplication()`.
- Headings: Title Case for H2/H3. Question headings ("What is a Vector Database?") and how-to gerund headings ("Using the sharding plugin") are fine.
- End articles with `## Follow Up`: a bullet list of internal links, usually the Quickstart (`../quickstart.md`), the GitHub repo as `/code/`, the chat as `/chat/`, and related articles. A star CTA "leave a star ⭐" is allowed. Reference pages may simply end after the last technical section.

### Voice and tone: the author fingerprint

The docs have one dominant authorial voice: the maintainer, a German native speaker who writes direct, pragmatic, evidence-driven English. New pages must sound like this voice. The fingerprint below was measured on his most personally written pages (release notes, slow-indexeddb.md, why-nosql.md, downsides-of-offline-first.md, offline-first.md, leader-election.md, transactions-conflicts-revisions.md, replication.md, contribute.md, the websockets and localstorage-indexeddb articles).