mirror of
https://github.com/Cockatrice/Cockatrice.git
synced 2026-07-06 05:23:56 -07:00
75 lines
4 KiB
Markdown
75 lines
4 KiB
Markdown
# 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/](architecture/). For prose — WebSocket layering, Redux store shape, test conventions — see [.github/instructions/webclient.instructions.md](../.github/instructions/webclient.instructions.md).
|
|
|
|
## Stack
|
|
|
|
React 19 + TypeScript, built with [Vite](https://vite.dev/) 8. State via Redux Toolkit + RxJS, UI via MUI v9, tests via Vitest, protobuf bindings generated by [buf](https://buf.build/) 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
|
|
|
|
```bash
|
|
npm install
|
|
npm start
|
|
```
|
|
|
|
`npm start` boots the Vite dev server and opens a browser tab at [http://localhost:5173](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](../.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](https://vite.dev/guide/) · [React docs](https://react.dev/) · [Vitest docs](https://vitest.dev/)
|