README
¶
/web
Frontend for the control plane, embedded into the Go binary via embed.FS
(no Node runtime on the server, no separately hosted frontend). React 19, Vite, TypeScript (strict), Tailwind CSS,
TanStack Router (file-based routing, per-route code splitting), TanStack
Query, TanStack Virtual.
Architecture and route structure are documented in
docs-local/research/frontend-plan.md. This scaffold implements the App
List route from that plan's section 4 skeleton; the remaining routes
(app detail, deploy history, live build logs, env editor, domain config)
are deferred to follow-up passes.
Commands
npm install # install dependencies
npm run dev # start the Vite dev server
npm run build # type-check (tsc -b) and produce a production build in dist/
npm run typecheck # tsc -b only, no bundling
npm run lint # eslint
npm run lint:fix # eslint --fix
npm run format # prettier --write
npm run format:check # prettier --check
npm run preview # preview the production build locally
npm run build also writes dist/stats.html, a treemap of final chunk
sizes (via rollup-plugin-visualizer), for keeping an eye on bundle size
against the route-level code splitting budget enforced in CI. A CI
script that fails the build on a size regression is not implemented yet.
Conventions
- No data fetching in component bodies. Route loaders prime the TanStack
Query cache; components read it via
useSuspenseQuery/useSuspenseInfiniteQueryagainst the same query key. - Query keys come from a factory per resource (see
src/queries/apps.ts), never an inline array in a component. - Every list that can exceed 50 items is virtualized with
@tanstack/react-virtual, unconditionally, not just past the 50-item mark, so there is one list implementation to keep correct. - TypeScript strict mode, no
any.src/routeTree.gen.tsis generated by the TanStack Router Vite plugin on everydev/buildrun and is not committed.
Documentation
¶
Overview ¶
Package web embeds the built frontend via embed.FS, keeping the control plane a single static binary with no Node runtime required on the server, and serves it with client-side-routing fallback, so a hard refresh or direct link to a TanStack Router path like /apps/foo resolves correctly instead of 404ing at the server before React Router ever gets a chance to handle it.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DistFS embed.FS
DistFS is intentionally empty (Go's embed.FS zero value, no //go:embed directive) in the default build. web/dist is a gitignored build artifact that doesn't exist until `npm run build` runs; a bare //go:embed dist here would make plain `go build ./...` fail on any checkout that hasn't built the frontend yet, breaking it repo-wide, including every quick sanity `go build`/`go vet`/`golangci-lint run` both this project's git hooks and CI already rely on. The real frontend is embedded only by an explicit `-tags embedweb` build, after `cd web && npm run build`; see embed_real.go and Handler's doc comment for what happens when it isn't.
Functions ¶
func Handler ¶
Handler serves the embedded frontend. If this binary wasn't built with -tags embedweb (the default, see embed_stub.go), it serves a 501 with an actionable message instead of panicking or 404ing silently: a missing frontend is a build configuration fact worth surfacing clearly, not a routing failure to debug.
Types ¶
This section is empty.
Source Files