Development
Frontend guide
Working inside apps/frontend — SvelteKit structure, the Bits UI rules, and the theme tokens.
SvelteKit (Svelte 5, runes), Bits UI, Tailwind CSS v4, Tiptap, Lucide.
Directory map
| Directory | Responsibility |
|---|---|
src/routes/ |
Pages (SSR) plus /api/[...path], the reverse proxy to the backend |
src/lib/api/ |
Typed API client; response types come from packages/contract (below) |
src/lib/components/ |
Application components; Icon.svelte is the single Lucide wrapper |
src/lib/components/ui/ |
Bits UI (headless) wrappers |
src/lib/editor/ |
Tiptap integration, lazy-loaded on /compose |
The reverse proxy
The web UI calls the same-origin /api and uses normal session cookies. Caddy
routes public API requests directly to the backend. /api/[...path] remains a
development/SSR proxy and preserves CORS headers and preflights for independent
bearer-token clients. OAuth token/revocation and metadata routes also proxy to
their root backend paths during local development.
INTERNAL_API_URL tells the frontend how to reach the backend inside the
container network.
API types and the backend contract
src/lib/types.ts re-exports the API’s types from @omicron/contract
(packages/contract, linked into the app). That package holds a zod/mini
schema for every payload the backend sends, with each field documented: which
field to build a link from, which is null and when. It is the one definition of
the API’s shapes, shared by the backend, the web app, and the mobile app.
Each app holds it to a different standard:
| App | How it uses the contract |
|---|---|
| Backend | Routes use satisfies Reply<"SchemaName">; tests/contract/contract.test.ts checks serializer types and parses real output |
| Web | Types only. It ships with the backend, so it trusts the payloads |
| Mobile | Parses every response with its schema; a list item that does not fit is dropped, anything else is an error |
A serializer change the contract does not describe fails the backend’s
pnpm check, naming the pair, instead of surfacing at runtime in whichever
component read the field.
The backend image is built from the repository root so it can include
packages/contract. The frontend image is built from apps/frontend and uses
type-only imports, so no contract runtime code enters its bundle. The contract
itself imports nothing but zod/mini.
UI rules
These are strict, and they are what keeps the app visually coherent.
1. Use Bits UI for every primitive that has one
Button, Avatar, DropdownMenu, Tabs, Toolbar, Label, Separator, Dialog, Tooltip,
and the rest. Fall back to native HTML only where Bits UI ships no equivalent
— text <input>, <form>, headings, layout — because Bits UI is headless and
has no such component.
2. Style with the ported theme tokens, never ad-hoc colours
| Kind | Tokens |
|---|---|
| Colours | foreground, foreground-alt, muted, muted-foreground, background, background-alt, dark, dark-10, accent, destructive, border / border-input |
| Radii | rounded-input, rounded-card, rounded-9px, rounded-button, … |
| Shadows | shadow-mini, shadow-popover, shadow-btn, shadow-card |
3. Copy the docs’ class strings verbatim
The Bits UI docs are the single source of truth for appearance. Copy each component page’s example classes as-is: the docs and this app both use Tailwind v4, so no syntax translation is needed.
Where the theme lives
- Tokens (colours, radii, shadows, fonts) and the CSS variables, ported
verbatim from the docs’
:root: the@themeblock inapps/frontend/src/app.css. There is notailwind.config.ts.
Keep them in sync with the Bits UI docs theme. Do not invent new design tokens.
Icons
One wrapper, Icon.svelte, around Lucide. Import icons through it rather than
scattering direct Lucide imports — it keeps sizing and stroke width consistent
and the bundle predictable.
The editor
Tiptap lives in src/lib/editor/ and is lazy-loaded on /compose only. It
carries Markdown input rules, image upload on paste and drop, and corner-drag
image resizing. It is the heaviest dependency in the app; keep it off every other
route.
Typography and fonts
- Inter (variable, self-hosted) for UI — no render-blocking third-party font request.
- Source Sans 3 (variable, self-hosted) for rendered post content
(
font-content). - Twemoji as a self-hosted COLR colour font, scoped by
unicode-rangeto emoji codepoints only, so every reader sees the same emoji artwork regardless of OS while the document keeps plain Unicode emoji — federation-friendly, selectable, copyable.
Rendered post content
.prose-omicron styles the HTML Tiptap produces. Media never overflows the
reading column, and wide preformatted blocks are scaled to fit rather than
pushing the page sideways.
Checks
cd apps/frontend
pnpm fmt
pnpm check # oxfmt, svelte-check, oxlint, and Vitest
Tests live in tests/, mirroring src/; see the application repository’s
AGENTS.md for the helpers (tests/fakeFetch.ts, tests/fixtures.ts, and the
$app/* stand-ins).
Found a mistake?Edit this page on GitHub.