CLAUDE.md · requarks/wiki

Sections

1. Layout
2. Commands
3. TypeScript (backend)
4. Conventions

First lines (shown under the repo's AGPL-3.0 license)

# Wiki.js 3.x

Next-generation open source wiki. This is the **3.x development branch** — incomplete, unstable, and
with no upgrade path from 2.x. AGPL-3.0.

**A database created by committed code has to be brought forward by a migration.** Anything that
has been committed may be running somewhere, so when a change alters what is stored — a column, the
format of a value, the meaning of a setting — an installation on an earlier commit must reach the new
shape through a migration under `backend/db/migrations/`. That includes rewriting data, not only
schema: a format change gets a migration that converts the existing rows. Converting the data is the
point — the code is not to carry fallbacks for the old format alongside the new one; once the
migration has run there is one shape, and the code reads only that.

**Nothing has to stay compatible with code that was never committed.** A shape introduced in
uncommitted work, which only a developer's own dev database can hold, can be changed freely: change
the shape, change the callers, and delete the old path, with no migration shim, legacy-value
fallback, deprecated alias or "old data may still contain X" handling — a fallback for a case that
cannot occur is dead code that still has to be read, tested and reasoned about. This applies to db
columns, API payloads, stored settings and config keys alike.

The one sanctioned exception is a value an existing installation **cannot** have and no static
default can stand in for — a secret generated per installation, say. That goes in a **startup check**
(`core/startupChecks.ts`), which every boot runs once to fill in what is missing; it is the only place
such a value is made, and nothing that reads it falls back on its own. A new setting with a fixed
default needs no check: put the default in `base.yml`, which is merged under the stored settings on
every boot.

Three independently-installed workspaces (each has its own `package.json` / `node_modules`, there is
no root package or monorepo tooling):

| Path        | What it is                                                    |
| ----------- | ------------------------------------------------------------- |
| `backend/`  | Fastify REST API server + job scheduler, Drizzle on PostgreSQL |
| `frontend/` | Vue 3 / Vite SPA, Tailwind CSS + an in-repo component library  |
| `blocks/`   | Lit web components users embed into wiki pages                 |

Requires Node.js **26+** and PostgreSQL **17+**. All three workspaces are ESM (`"type": "module"`).

The backend is **TypeScript 7**; `frontend/` and `blocks/` are JavaScript. See
[TypeScript (backend)](./backend/CLAUDE.md#typescript-backend).

## Layout

### Root

- `config.yml` — instance config (copy of `config.sample.yml`). Read by the backend at boot *and* by
  `frontend/vite.config.js` in dev mode to learn the proxy target port.
- `assets/` — **build output** of the frontend (`vite build` writes here), plus static assets under
  `assets/_assets/`. Served by the backend. Don't hand-edit.
- `dev/` — deployment/packaging artifacts: `dev/build/Dockerfile` (production image), `dev/chart/`
  (the 3.x Helm chart, published as an OCI artifact — its `README.md` is the reference), `dev/packer/`.
  `dev/helm/` is the 2.x chart and nothing for 3.x should be built on it.
- `.devcontainer/` — VS Code dev container (app + postgres + pgAdmin + mailpit via docker-compose).
  Mailpit is the mail server for development: it accepts everything and delivers nothing, so a
  confirmation link or a password reset lands in a web inbox at `http://localhost:8025` rather than a
  real mailbox. Point the wiki at it under **Admin → Mail** — host `localhost`, port 1025, TLS off,
  no credentials.
- Locale strings live in `backend/locales/`.

### Where the rest is documented

This file holds what applies everywhere. The rest is loaded only when it is relevant, so look there
before working in an area — and add to it there, not here:

- **Per workspace** — `backend/CLAUDE.md` (layout, the TypeScript rules, backend patterns),
  `frontend/CLAUDE.md` (layout, frontend patterns) and `blocks/CLAUDE.md` (layout, shadow DOM and
  dark mode), each loaded when a file under that directory is read.
- **Per subsystem** — `.claude/rules/*.md`, each loaded when a file matching its `paths:` is read:
  `storage` (storage targets, delivery, the git sync), `comments`, `app-shell-seo`,
  `distributing-blocks` (the `.wkblock` package), `emails`, `excalidraw`, `analytics`,
  `live-notes`, `audit-log`, `notifications`, `mcp`, `page-lifecycle`, `glossary`,
  `feedback-boards`, `metrics`, `icons`, `page-paths` (path segments, the ltree encoding) and
  `personal-access-tokens` (`config.scope`, `requestUser(req)`).
- **Procedures** — `.claude/skills/`: `throwaway-instance` boots, scripts and tears down a
  disposable instance.

A rule's `paths:` should name every file whose editing needs it. A new subsystem gets a rule file of
its own rather than a section here.

## Commands

Run backend commands from `backend/`, frontend from `frontend/`, blocks from `blocks/`.

```sh
# backend
npm run dev              # nodemon, restarts on any backend file change
npm run start            # plain node
npm run typecheck        # tsc — type check only, never emits
npm run typecheck:watch
npm run db-generate -- --name=foo-column   # drizzle-kit generate — after editing db/schema.ts
npm run db-up            # drizzle-kit up

# frontend
npm run dev            # vite dev server on :3001 (needs backend running on :3000)
npm run build          # builds into ../assets — required before the backend can serve the UI

# blocks
npm run build              # rollup → blocks/compiled/
npm run package -- block-x # compile one block → blocks/packages/block-x.wkblock
```

`npx ncu -i` (`npm run ncu`) for interactive dependency updates.

The API is browsable via Swagger UI at `http://localhost:3000/_api` in a running instance. Default
admin login is `admin@example.com` / `12345678`.

### How far to go verifying a change

Match the check to the size of the change. `npm run build`, `npx oxlint` and `npm run typecheck` are
seconds each and are the right check for nearly everything.

**Do not stand up a throwaway instance and drive a headless browser to look at a small change.** That
means booting a backend against a scratch database, seeding it, and screenshotting through a
headless browser — a good ten minutes of setup that a moved border, a colour, a spacing tweak or a
renamed label does not earn. Read the rule you wrote, trust the build, and say what you changed.

It is worth the setup for a **new** piece of UI whose markup has to meet a stylesheet written
elsewhere, where being wrong means shipping something visibly broken — a component reusing existing
content classes is the case that has actually gone wrong. Also for a flow with real state to exercise
(a login, an upload, a save), where a screenshot answers a question reading cannot.

When it is worth it, the `throwaway-instance` skill is how.

## Conventions

### Style, linting, formatting

**oxlint** for linting, **oxfmt** for formatting — not ESLint or Prettier (ESLint is explicitly
disabled in `.vscode/settings.json`). Both are devDependencies of `backend/` and `frontend/`.

```sh
npx oxlint            # from backend/ or frontend/ — uses that dir's .oxlintrc.json
npx oxfmt <paths>     # config is the repo-root .oxfmtrc.json
```

Format settings (root `.oxfmtrc.json`): no semicolons, single quotes, no trailing commas,
`bracketSameLine`, LF, final newline. 2-space indent, per `.editorconfig`.

Otherwise follow **standard JS** rules. Note that much of `frontend/` predates oxfmt and still uses
the standard-style space before parens (`function initializeRouter ()`); new and touched code should
be oxfmt-formatted, but don't reformat untouched files as drive-by changes.

Each workspace has its own `.oxlintrc.json` — the backend declares the `WIKI` global and node env;
the frontend adds the `vue` plugin and the `API_CLIENT` / `EVENT_BUS` / `Temporal` globals. Only the
`correctness` category is an error.

Both tools handle `.ts` with no extra configuration, and the backend's oxlint config already enables
the `typescript` plugin. oxlint does not type-check — run `npm run typecheck` for that.

**Never put two statements in a Vue template attribute.** `@click="doOne(); doTwo()"` builds today
and is a build error the moment the file is formatted, because `semi: false` and Vue disagree about
the same character. Vue's `transformOn` decides whether an inline handler is a statement block or an
expression from `exp.content.includes(';')` — with the semicolon it emits `$event => { … }`,
without it `$event => ( … )`. oxfmt breaks the handler across lines and drops the semicolon, so Vue
parenthesises two statements and the template fails to compile (`Error parsing JavaScript
expression: Unexpected token`). Write a named handler instead — `@click="closeAndRefresh"` — as
`EditorMarkdown.vue` and `PageRelationDialog.vue` do.

Neither side of that is worth reconfiguring, so don't try: the `includes(';')` check has no compiler
option behind it, and the parse error is raised by the built-in `transformExpression`, which