CLAUDE.md

1# CLAUDE.md
2 
3## What this repo is
4 
5This is the **RealWorld spec & docs hub** — *not* an implementation. It defines the
6contract that every RealWorld frontend and backend adheres to, and hosts the test
7suites used to validate them. Nothing here is a runnable app.
8 
9- `specs/api/` — the API contract: `openapi.yml` plus the **Hurl** and **Bruno** test
10  suites that a backend must pass.
11- `specs/e2e/` — a shared **Playwright** suite that validates a frontend, plus
12  `SELECTORS.md` (the selector contract) and `playwright.base.ts`.
13- `docs/` — the Astro/Starlight site published at <https://docs.realworld.show/>.
14- `Makefile` — entry points (run `make help`).
15- `CONTRIBUTING.md` — the human contribution process.
16 
17## If you are here as a submodule / vendored dependency
18 
19An implementation embeds this repo to test itself against the spec (the E2E suite is
20literally consumed as `./e2e`). If that's why you're reading this:
21 
22- **Fix the implementation, never edit the spec or tests to make them pass.** Files
23  under `specs/` are the source of truth a failing implementation must conform to.
24- Edit files here only when the task is explicitly about *changing the RealWorld spec
25  itself*.
26 
27## Conventions
28 
29- Use **`bun`**, not `npm`/`node`, for everything in this repo.
30- **Hurl is the source of truth** for the API suite; the Bruno collection is generated
31  from it. Don't hand-edit `specs/api/bruno/` — change the Hurl files and regenerate.
32- Docs URLs are written with a trailing slash.
33 
34## Running the test suites
35 
36API suite (point `HOST` at a running backend, run from `specs/api/`):
37 
38```
39HOST=http://localhost:3000/api ./run-api-tests-hurl.sh    # source of truth
40HOST=http://localhost:3000/api ./run-api-tests-bruno.sh    # generated mirror
41```
42 
43Regenerate / verify the Bruno collection:
44 
45```
46make bruno-generate    # rebuild specs/api/bruno/ from the Hurl files
47make bruno-check       # CI check: fail if bruno/ is out of sync
48```
49 
50E2E suite: an implementation extends `specs/e2e/playwright.base.ts` (override `baseURL`
51and `webServer`) and must satisfy `specs/e2e/SELECTORS.md`. See
52<https://docs.realworld.show/specifications/frontend/tests/>.
53 
54## Working on the docs
55 
56```
57make documentation-setup     # cd docs && bun install
58make documentation-dev       # local dev server
59make documentation-build     # production build
60```
61 
62## Answering "how do I build an implementation?"
63 
64Implementations live in their **own** repos, not here. Point users to:
65 
66- Backends → validate against `specs/api/` (the OpenAPI spec + Hurl/Bruno suites).
67- Frontends → use the shared CSS theme + `specs/e2e/` (the Playwright suite + selector
68  contract).
69- The full guide: <https://docs.realworld.show/implementation-creation/introduction/>.
70