Skip to content

Frontend build

The frontend is a Svelte 5 single-page app built with SvelteKit 3 on Vite. @sveltejs/adapter-static writes a static site to frontend/build/, and nginx serves it and proxies /api/ to the backend, both in production and in the local compose stack.

How the app starts

SvelteKit owns the entry point. src/app.html is the page template, and every route is served by the same fallback page, 200.html. The root src/routes/+layout.ts sets ssr = false, so pages render in the browser only, as they did before.

src/hooks.client.ts runs init once when the app starts. It calls initializeApiInterceptors() from src/lib/api-interceptors.ts, which points the generated client at relative URLs with cookies included, registers the CSRF header and error interceptors, and gives the query client its error handler. Its handleError logs errors from navigation, loading and rendering; SvelteKit then shows src/routes/+error.svelte. Error handling has the details.

src/routes/+layout.ts asks /api/v1/auth/me who is signed in before any page renders. src/routes/+layout.svelte imports app.css, provides the TanStack Query client, applies the theme from the user settings query once signed in, and renders the header, the toaster, the page and the footer. Routing covers the routes and their guards.

src/lib/api/ is generated by @hey-api/openapi-ts from docs/reference/openapi.json with Prettier as a post-processor. The typescript plugin emits types and, with enums: 'javascript', runtime objects for every enum such as UserRole. The sdk and client-fetch plugins emit the request functions and the client. Responses stay plain JSON with no transformer, so a date-time field is the ISO string the API sends and the types say string; the formatters parse it only to display it. The zod plugin emits a schema per model, such as zUserCreate, with the spec's validation rules and defaults. The schemas use zod/mini: classic Zod builds its faster parser with new Function, which the CSP blocks, while mini never tries. The @tanstack/svelte-query plugin emits query and mutation options for every operation, covered in Server state. The client, the schemas and those options are re-exported from the index, so everything imports from #lib/api/index.ts, and Zod with every schema loads with the first page. Don't edit any of it by hand. After a backend change, uv run python -m scripts.export_openapi in backend/ rewrites the spec from create_app(), and npm run generate:api rewrites the client from it.

Tailwind v4 is configured in CSS through the @tailwindcss/vite plugin, and there is no tailwind.config.js. src/app.css imports tailwindcss, styles/components.css (the shared classes: buttons, badges, cards, alerts, form controls, the page column, fields, label and value lists, stats, links, tables, overlays), styles/pages.css (editor and home page layout) and tw-animate-css (the open and close animations of the bits-ui overlays), loads @tailwindcss/forms with the class strategy and @tailwindcss/typography for the privacy page's prose, and declares the color tokens. Each token is one CSS variable: :root holds its light value and .dark (which mode-watcher toggles on <html>) its dark one, and @theme inline turns it into utilities. So bg-surface or text-fg-muted is right in both modes, and markup never needs a dark: variant.

The tokens are page, surface, sidebar, muted (a 5% tint of the text color, for fills and hovers on any surface), fg, fg-muted, fg-subtle, border (also the default border color), border-input, ring, accent (links and accent text), success, warning, danger, info and the categorical purple, indigo and orange, each of the last seven with a -soft fill, plus code and backdrop. primary, secondary, danger-solid and tooltip are fills that keep one color in both modes. ESLint rejects a dark: variant or a raw palette color such as text-red-600 in markup and in TS class maps.

Server data lives in the TanStack query cache. Who is signed in is layout data, page.data.user from $app/state, and nothing keeps a copy. The theme is mode-watcher's own state, which components read and set directly; its modes are the API's Theme values (light, dark, system). <ModeWatcher> in the root layout stores the choice under app-theme, follows the system for system, and puts the dark class on <html>; it runs without its inline head script and transition style, which the CSP would block. userPrefersMode.current is the choice, which the header's toggle cycles through, and mode.current the resolved mode, which the editor uses for its CodeMirror theme. Toasts come from svelte-sonner, not a store.

Configuration

SvelteKit 3 reads its configuration from the sveltekit() plugin in vite.config.ts; there is no svelte.config.js. The plugin gets adapter-static with fallback: '200.html' and the CSP:

            // Kit hashes its inline script into a meta CSP; nginx adds frame-ancestors, which a meta CSP can't express
            csp: {
                mode: 'hash',
                directives: {
                    'default-src': ['self'],
                    'script-src': ['self'],
                    // nginx swaps in a per-response nonce, which CodeMirror puts on the <style> tag it injects
                    'style-src-elem': ['self', 'nonce-**CSP_NONCE**', 'https://fonts.googleapis.com'],
                    'style-src-attr': ['unsafe-inline'],
                    'img-src': ['self', 'data:', 'blob:'],
                    'font-src': ['self', 'data:', 'https://fonts.gstatic.com'],
                    'connect-src': ['self'],
                    'object-src': ['none'],
                    'base-uri': ['self'],
                    'form-action': ['self'],
                },
            },

SvelteKit forbids its own nonces on prerendered pages, so it writes the policy into 200.html as a <meta http-equiv="content-security-policy"> tag with a sha256 hash of its one inline bootstrap script. A meta CSP can't carry frame-ancestors, so nginx sends that one as a header. style-src-attr 'unsafe-inline' allows style="" attributes, which Svelte transitions and CodeMirror set at runtime.

CodeMirror injects its theme as a <style> tag in the document head, so style-src-elem has to let that one tag through. It carries a nonce-**CSP_NONCE** source, and app.html has a <meta name="csp-nonce" content="**CSP_NONCE**"> tag. nginx replaces the placeholder in both with $request_id on every response, and the editor hands the value to CodeMirror through EditorView.cspNonce. Without it the browser drops the editor's styles: no gutter, no highlighting. A Playwright test in e2e/editor.spec.ts checks the gutter's layout and fails on any CSP violation.

Imports use package.json subpath imports instead of the $lib alias that SvelteKit 3 dropped: #lib/*, #components/*, #routes/* and #test/*, each with an explicit file extension, such as #lib/editor/draft.svelte.ts or #lib/api/index.ts. Vite and TypeScript resolve them natively. tsconfig.json extends $app/tsconfig, which svelte-kit sync writes into node_modules; npm run check and npm run lint run the sync first, and npm install runs it through prepare.

npm run build runs vite build. The output in build/ is 200.html, the content-hashed JavaScript and CSS under _app/immutable/, and the files from static/ (favicon.png, robots.txt, sitemap.xml). Each route is its own chunk, so CodeMirror only loads with the editor. Vite doesn't type-check; the gate is npm run check, which runs svelte-check --fail-on-warnings in the frontend CI workflow next to npm run lint and npm run build.

Serving and local development

frontend/Dockerfile has two stages. node:26-alpine runs npm ci and npm run build. nginx:1.31-alpine copies build/ to /usr/share/nginx/html and puts nginx.conf.template in /etc/nginx/templates/, so the image's entrypoint fills in BACKEND_URL, GRAFANA_URL and GRAFANA_PUBLIC_URL with envsubst at startup.

nginx listens on 5001 with TLS. Its certificate is the one mounted at /etc/nginx/certs, or, when nothing is mounted, a self-signed one that a script in the image's /docker-entrypoint.d/ makes before nginx starts. It proxies /api/ to BACKEND_URL (https://backend:443 in compose), verifying the backend against the certificate the backend keeps in the backend_tls_cert volume, and gives /api/v1/events/ SSE settings: no buffering and 24 hour timeouts. /grafana is a 302 redirect to GRAFANA_PUBLIC_URL. Static assets get a one year expires, which is safe since their names carry content hashes, and HTML gets expires -1 so browsers revalidate it. Any path that isn't a file gets 200.html, so deep links and reloads work. Nginx configuration walks through the whole file.

docker compose up -d starts the compose stack, and the frontend service there is the same nginx image on https://localhost:5001. It has no source mount, so a frontend change needs docker compose up -d --build frontend to show up.

npm run dev runs the Vite dev server on port 5001 with hot module replacement. It uses HTTPS when ./certs/server.key and ./certs/server.crt exist (or SSL_KEY_FILE and SSL_CERT_FILE), and proxies /api to https://backend:443 with the certificate checked, so it needs NODE_EXTRA_CA_CERTS pointing at the backend's server.crt. The backend hostname only resolves inside compose, so API calls only work from a container on app-network, with the compose frontend service stopped to free the port.