fancy-dns/web

The console

Vite + React + TypeScript + Tailwind, built into internal/web/dist and served by the Go binary from an //go:embed. There is no separate deployment: the binary is the console.

Day-to-day

make web-check     # npx tsc -b --noEmit && npm run build  (what CI runs)
make web-dev       # Vite dev server, proxying /api to 127.0.0.1:8080
make web           # production build into internal/web/dist

For make web-dev to show anything, a fancy-dns has to be listening on 127.0.0.1:8080 with the API key the console sends. deploy/config.example.yaml binds there, but on port 53; rewrite the ports (or use make smoke, which does it for you) before starting it.

Two traps that have cost time, both from AGENTS.md:

• tsc -b replays cached diagnostics from node_modules/.tmp/*.tsbuildinfo. After a large edit rm -f node_modules/.tmp/*.tsbuildinfo, or you will read errors that no longer exist and miss ones that do.
• npm run build empties internal/web/dist and deletes its .gitkeep. Restore it (git checkout -- internal/web/dist/.gitkeep). The Go build still works while the directory is empty, so a console rebuild in the middle of someone else's go build is not fatal — but the commit is.

The API contract

src/lib/types.ts is a hand-written mirror of the Go json tags in internal/api and internal/app/hooks.go. apiFetch ends in JSON.parse(text) as T, so the compiler checks the console against its own declarations and nothing else: a field that loses its json tag, or a response a struct never had, shows up as an empty table in a browser and nowhere else. That is not hypothetical — a round of this found the Sources table, the ACL group cards and both Save buttons broken exactly that way.

So, when you touch either side:

• Go: add or keep the json tag. internal/app has contract tests that assert the exact key set of every admin endpoint; they are the spec, and a rename fails them.
• Console: change the interface in the same commit. If the server is wrong, fix the server — do not "adapt" in the client, and do not paper a mismatch over with as any, an optional field or a ?? 0 default. Those casts are precisely what hides drift.
• Never rename a field on one side only. The dashboard, the ServiceMonitor queries and the Grafana panels are consumers of the same JSON.

The durable fix is to generate types.ts from the Go structs, or to publish an OpenAPI document from the server and generate from that. It is in the plan at the end of STATUS.md.

What is checked

npx tsc -b --noEmit (strict, with noUnusedLocals) and oxlint (two rules: react/rules-of-hooks and react/only-export-components). There is no test runner and no component test — the console's correctness rests entirely on its types, which are only as good as the mirror above. Adding vitest and a handful of tests for lib/format.ts (the percent/latency/duration formatters, which have already shipped a units bug) is cheap and worth doing.