Cockatrice/webclient

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.

Further reading

• .github/instructions/webclient.instructions.md — architecture deep dive, conventions, and domain-knowledge invariants for working in this directory (the canonical AI-tool instruction surface for this package)
• Vite docs · React docs · Vitest docs