Webatrice

The Cockatrice web client — a React/TypeScript SPA that connects to a Servatrice server over a WebSocket.

Application Architecture

For the full set of diagrams (detailed layer map + command/response/event sequence) and the npm run diagram scripts that regenerate them, see architecture/. For prose — WebSocket layering, Redux store shape, test conventions — see .github/instructions/webclient.instructions.md.

Stack

React 19 + TypeScript, built with Vite 8. State via Redux Toolkit + RxJS, UI via MUI v9, tests via Vitest, protobuf bindings generated by buf into Protobuf-ES.

Prerequisites

Node.js and npm
Docker Desktop — only required for npm run test:e2e (spins up servatrice + MySQL via docker compose)
Run every command below from the webclient/ directory

Getting started

npm install
npm start

npm start boots the Vite dev server and opens a browser tab at http://localhost:5173 automatically (configured via server.open in vite.config.ts). The first start runs proto:generate and prebuild.js via the prestart hook, so give it a moment.

Scripts

Dev & build

npm start — start the Vite dev server (runs proto:generate + prebuild.js first via prestart)
npm run build — production build into build/ (also runs the prebuild hooks)
npm run preview — serve the built build/ output locally to smoke-test a production build

Tests

npm test — one-shot Vitest run (unit specs)
npm run test:watch — Vitest in watch mode
npm run test:integration — integration specs via vitest.integration.config.ts
npm run test:coverage / npm run test:integration:coverage — the above with v8 coverage
npm run test:e2e — full Playwright e2e pipeline (requires Docker Desktop): test:e2e:up → test:e2e:run → test:e2e:down, preserving the run's exit code
npm run test:e2e:run — run specs against an already-running stack (use this in dev loops)
npm run test:e2e:open — Playwright UI mode for debugging specs interactively
npm run test:e2e:up / npm run test:e2e:down — bring the dockerized servatrice + MySQL stack up / down (volumes are wiped on down)

The pretest:e2e hook runs playwright install --with-deps chromium automatically on first invocation, so no manual browser install is needed.

Quality

npm run lint / npm run lint:fix — ESLint over src/
npm run golden — lint + test + test:integration; the fast CI-equivalent gate to run before declaring work done
npm run golden:full — golden + test:e2e; the full pre-merge gate (requires Docker Desktop)

Codegen & i18n

npm run proto:generate — regenerate Protobuf-ES bindings from ../libcockatrice_protocol via buf generate
npm run translate — re-run the i18n merge only (prebuild.js -i18nOnly)

Generated files

Produced by proto:generate and prebuild.js on every npm start / npm run build. Don't edit them by hand:

File	Tracked?	Notes
`src/generated/proto/**`	Gitignored	Protobuf bindings. Regenerate with `npm run proto:generate`; only appears after a first local run.
`src/server-props.json`	Gitignored	Build metadata including the current git SHA. Written by `prebuild.js`; only appears after a first local run.
`src/i18n-default.json`	Committed	Merged i18n catalog. Regenerate with `npm run translate` and commit whenever it changes.

4 KiB Raw Blame History