TASKS-1823 WebManager module

2026-08-28 08:35:58 +00:00
parent fdb2cf3837
commit c93d8c025b
654 changed files with 26232 additions and 6075 deletions
@@ -0,0 +1,58 @@
+# Web App
+
+The public website: a Next.js App Router app that server-renders the pages editors publish in [Web Manager](../../docs/core/web-manager/Readme.md). Everything visitors see comes from the backend's public API. Package: `@crux-kit/web-app`.
+
+Architecture — request flow, layers, backend boundary, rendering registries, i18n, SEO — is documented in the [Next.js web architecture](../../docs/architecture/web/Readme.md).
+
+| Tech       | Version                                  |
+| ---------- | ---------------------------------------- |
+| Next.js    | 16 (App Router, React Server Components) |
+| React      | 19                                       |
+| next-intl  | 4 — locale routing and translations      |
+| Tailwind   | 4 — CSS-first, no config file            |
+| TypeScript | 5.9, `strict`, `noEmit`                  |
+| Vitest     | 4 — node environment, no DOM tests       |
+
+## Configuration
+
+| Variable            | Required                | Purpose                                                               |
+| ------------------- | ----------------------- | --------------------------------------------------------------------- |
+| `BACKEND_API_URL`   | yes — throws without it | Backend origin. No `/web-manager/public` suffix.                      |
+| `SITE_URL`          | in production           | Canonical origin. Missing → `http://localhost:3000` + a logged error. |
+| `REVALIDATE_SECRET` | for purges to work      | Must equal the backend's `WEB_REVALIDATE_SECRET`.                     |
+
+Copy `.env.example` to `.env`. In Docker the backend URL must use the compose service name (`http://backend:3333`), not `localhost`.
+
+## Development
+
+```bash
+npm run dev:web
+```
+
+```bash
+npm run test:web
+```
+
+```bash
+npm run build:web
+```
+
+`build` runs `tsc --noEmit` before `next build`, so a type error fails the build.
+
+Under Docker the `web` service runs `npm run dev` on port 3000 with `.next` on an anonymous volume. That volume survives rebuilds and is the usual cause of a stale bundle — recreate with `docker compose up -d --force-recreate --renew-anon-volumes web`.
+
+Path alias: `#*` maps to the app root. `vitest.config.ts` mirrors it by hand (Vitest ignores `tsconfig` paths) and stubs `server-only`.
+
+## Tests
+
+`tests/` covers the pure logic (normalization, cache tags, registries, metadata, sitemap, site URL, structured data) in a node environment — component rendering is not covered and would need `@testing-library/react`. `registry.test.ts` keeps a hand-mirrored list of the backend's block and page types and asserts the registries match exactly — the tripwire for a block the CMS can publish but the site cannot draw.
+
+## Adding Things
+
+| Task                         | Where                                                                                                     |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
+| A new CMS block or page type | Spans three apps — follow [Web Manager → Extending](../../docs/core/web-manager/integration.md#extending) |
+| A non-CMS route              | A folder under `app/[locale]/`; keep the logic in `web-runtime/`                                          |
+| A shared UI primitive        | `shared/ui/` — content-agnostic only                                                                      |
+| A new locale                 | Add it to `site.config.ts` and add the five `i18n/translations/*/<locale>.json` files                     |
+| A new backend read           | A method on `WebRuntimeAPI` with its tags, plus a normalizer for the response                             |