Development

Package manager: npm (.npmrc with legacy-peer-deps=true for the peer conflict between openapi-typescript and TypeScript 6 — keep it).

Commands

npm install            # install (reproducible via package-lock.json)
npm run dev            # dev server on http://localhost:3000
npm run typecheck      # tsc --noEmit
npm run check          # biome check + typecheck (run before finishing a task)
npm run format         # biome format
npm run lint           # biome lint
npm run build          # production client + SSR build
npm run preview        # serves the production build
npm test               # vitest run

Code generation

npm run api:gen        # downloads /docs-json → scripts/openapi.latest.json (gitignored)
                       # → openapi-typescript → src/core/api/generated/schema.ts (committed)
npm run generate-routes # tsr generate → src/routeTree.gen.ts (after every route change)

Environment

Copy .env.example to .env if needed:

VITE_API_URL=/api/v1

The default /api/v1 value is relative (same origin): in dev, the vite.config.ts proxy relays /api/* to the backend https://dev.sim.strife-cyber.org (that backend’s CORS rejects localhost:*). An absolute URL (https://host/api/v1) remains possible if the frontend is hosted on another domain.

VITE_API_URL is not secret (exposed to the browser). JWT tokens are never put in a .env or in the bundle as constants.

Production (Docker)

docker compose up --build     # build + run → http://localhost:3004

The compose host port is 3004 (3000 is captured by WSL on this machine); the container’s internal port stays 3000 (PORT).

The image (multi-stage Dockerfile) builds dist/ then runs it via prod-server.mjs: a node:http host that performs SSR rendering (dist/server/server.js), serves assets (dist/client/), and relays /api/* to the backend defined by the API_TARGET env var (same pattern as the dev Vite proxy — the browser only calls the same origin, backend CORS does not apply). Without API_TARGET, /api/* answers 404.

• VITE_API_URL is inlined at build (default /api/v1, same origin).
• PORT (default 3000) and API_TARGET are container variables.
• docker compose points API_TARGET at the dev instance by default — replace it with the production backend URL on deployment.
• npm run build && node prod-server.mjs reproduces the runtime locally (no Docker).

Typical workflow

1. npm run dev for development (HMR: routes, tailwind).
2. Before finishing: npm run check then npm test.

Don’ts

• ❌ Use pnpm or yarn (the npm lockfile must remain the source of truth).
• ❌ Commit scripts/openapi.latest.json (gitignored).
• ❌ Remove legacy-peer-deps from .npmrc.