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
• 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

Quality

• npm run lint / npm run lint:fix — ESLint over src/
• npm run golden — lint + test + test:integration; the CI-equivalent gate to run before declaring work done

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