Developers

Svelte pitfalls

The web UI is a Svelte 5 app embedded in the binary. Most of its rules are enforced by a check, so a mistake fails loudly. A few are not, and one of those went unnoticed from the first release until a user hit it. This page lists both kinds.

Braces in a quoted attribute are an expression

In Svelte, {…} inside a quoted attribute value is an expression, not text. pattern="[0-9]{6}" reaches the browser as pattern="[0-9]6": the {6} is the number 6 and the quantifier is gone. Nothing warns you.

  • Write the value as an expression: pattern={'[0-9]{6}'}. The same goes for any attribute that holds braces as text (a regular expression, an SVG path template, a JSON snippet).
  • The guard: ui/tests/e2e/6-markup.spec.ts scans every .svelte file in ui/src for a quoted attribute that holds {digits} or {digits,digits} and fails with the file and line. It needs no browser.
  • To check a suspicion, compile the file with svelte/compiler and look at the set_attribute call it generates. That is how the bug below was confirmed.

The content security policy

The server sends this policy with the page (crates/wrendns-api/src/ui.rs):

default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:;
font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'none';
form-action 'self'; frame-ancestors 'none'
  • Everything comes from the page's own origin. No external font, image, script, or request. That is a privacy rule as much as a security one: the UI never tells a third party which names a person looks at.
  • No inline styles. Use classes, and Svelte's style: directive for a computed value (style:width={…}), which sets the property from script. The UI has no style="…" attribute at all, and about ninety style: directives.
  • Images are 'self' or data:. Draw icons as inline SVG.
  • A violation is a console error, and the Playwright suite fails on any console error. You find out in the first run.

What the build checks

CommandWhat it enforces
npm run checksvelte-check with warnings as failures: type errors, and accessibility warnings (a control with no label, a click handler on a non-interactive element), and unused CSS selectors.
npm run check:helpEvery <HelpButton id="…"> has a topic in docs/help/topics.json, and every topic not marked general is used somewhere (API-011).
npm run typesRegenerates ui/src/lib/api-types.ts from docs/api/openapi.json. CI fails if the committed file differs. Don't hand-write a type for something the API returns; the few exceptions are commented.
npm run buildThe 400 KiB gzipped budget for the whole of ui/dist, lazy chunks included. See Size and performance budgets.
npm run test:e2eThe Playwright suite, which also fails on any page error or console error. See Write UI tests.

Habits that keep it working

  • Big data is a lazy chunk. Load it with a dynamic import() the first time something needs it, and fall back to something that works if the load fails (the icon glyphs fall back to letters).
  • Both themes. A colour that works on light can vanish on dark. Component styles that depend on the theme repeat their rule for :root[data-theme='dark'] and for prefers-color-scheme: dark (see DomainIcon.svelte); look at both.
  • The address is the state of a list page. The query log's form mirrors the URL and the URL drives loading, so a search can be bookmarked and shared. Add new keys without changing what old addresses mean, and drop a key whose filter is absent instead of sending the API a request it refuses.
  • Decorative marks are hidden from screen readers (aria-hidden), and the text beside them is the label.
  • An $effect reruns when anything it reads changes. One that writes state it also reads can loop. Prefer $derived for a value computed from other state.
  • Give a thing a test id (data-testid) when a test must find it and its text may change.

Worked example: two-factor sign-in

In 0.7.0 a user reported that two-factor sign-in could not be turned on: the code box answered "Please match the requested format" to every code, even the example. The box had pattern="[0-9]{6}". Compiled with the project's Svelte, the attribute was pattern="[0-9]6": one digit then a literal 6. The same box on the sign-in form meant nobody who had two-factor could sign in with a code either. It had been that way since the first UI in v0.1.0, and no test touched two-factor.

  • The fix was two characters of syntax in two files.
  • The tests were the real work. A Playwright test turns two-factor on through the page with a code it computes from the shown secret, signs out, signs in with the next code, and turns it off; with the old pattern put back it fails at the first step. And the markup guard above stops the whole class.
  • The lesson: a feature with no test through the real page can be broken for a month without anyone knowing. When you add a form field, drive it in a test.