# Tech Stack Decisions — frontend-shell Existing stack (unchanged): React 19, TypeScript, Vite, TanStack Router, Chakra UI v3, pnpm. See [technology-stack.md](../../../../../_shared/reverse-engineering/technology-stack.md). All new packages are installed with pnpm at their latest stable version and pinned by `pnpm-lock.yaml` (SECURITY-10). ## Dependency Changes | Package | Change | Kind | Why | |---|---|---|---| | `vitest` | add | dev | Test runner, native to Vite (NFR-03) | | `@vitest/coverage-v8` | add | dev | Coverage with per-file thresholds (NFR-M-02) | | `jsdom` | add | dev | DOM environment for component tests | | `@testing-library/react`, `@testing-library/user-event`, `@testing-library/jest-dom` | add | dev | Component tests from the user's perspective | | `fast-check` | add | dev | Property-based testing (PBT-09) | | `vitest-axe` (on `axe-core`) | add | dev | Accessibility assertions in component tests (Q4 = A) | | `eslint`, `@eslint/js`, `typescript-eslint`, `eslint-plugin-react-hooks`, `eslint-plugin-jsx-a11y`, `globals` | add | dev | Linting (Q5 = A) | | `@lhci/cli` | add | dev | Lighthouse CI with assertions (Q3 = B) | | `next-themes` | **remove** | — | The site is fixed to light; it only added an inline script (Q2 = A) | | `@vitejs/plugin-react` | move to dev | dev | Build tool (FR-11) | | `@tanstack/react-router-devtools` | move to dev | dev | Loaded only in development (NFR-P-04) | ## Decisions ### TD-01 Property-based testing: fast-check (PBT-09) - **Generators**: fast-check provides custom arbitraries for the domain types (`SocialLink`, `EmailAddress`, `SitePage`, paths, JSON values). - **Shrinking and replay**: shrinking is on by default. On failure, fast-check reports the seed and path, and `fc.assert(..., { seed, path })` replays the exact case. - **Test runner**: runs as normal Vitest tests, so no separate runner is needed. - **Default runs**: 100 per property. Raise it per property only when needed. - **Considered**: `@fast-check/vitest` (adds `test.prop`). Not needed: plain `fc.assert` inside `it` is enough and is one dependency less. ### TD-02 Test environment: Vitest + jsdom - The Vitest config lives in `vite.config.ts` (`test` section), so tests use the same aliases and plugins as the app. - Setup file: `@testing-library/jest-dom` matchers + `vitest-axe` matchers. - Router-dependent components are tested inside a memory-history router. - **Fallback**: if `vitest-axe` turns out to be incompatible with the installed Vitest version, a ~10-line custom `toHaveNoViolations` matcher on `axe-core` replaces it. Same assertion, one dependency less. ### TD-03 Linting: ESLint flat config - Rule sets: `@eslint/js` recommended, `typescript-eslint` recommended, `react-hooks` recommended, `jsx-a11y` recommended. - Prettier remains the formatter. No stylistic ESLint rules, to avoid conflicts. - Excluded: `routeTree.gen.ts` and `dist`. ### TD-04 Lighthouse CI - **Server**: `@lhci/cli` starts `pnpm preview`, so the real production headers and the SPA fallback apply. It measures every route in `sitePages` plus one unknown URL (the 404), on both mobile and desktop. - **Assertions**: - Performance ≥ 0.9 - Accessibility = 1 - Best Practices = 1 - SEO = 1 on indexed URLs. On `noindex` URLs only the `is-crawlable` audit is allowed to fail (NFR-S-02). - **Requirements**: a local Chrome/Chromium. - **Results**: written to `.lighthouseci/`, which is git-ignored. No upload to a public server. - **Scripts**: - `pnpm lighthouse` runs it on its own. - It is part of `pnpm check` (CQ1 = A). ### TD-05 Security headers in Vite - **One source**: `securityHeaders(mode)` in a small config module, used by `server.headers` (dev) and `preview.headers`. - Production mode returns the strict set (NFR-SEC-01/02). - Dev mode adds only the Vite exceptions (NFR-SEC-03). - **Testing**: the function is pure, so a test can check that the production CSP never contains `unsafe-eval`, never contains `unsafe-inline` in `script-src`, and never contains `ws:`. - **Production**: the same production set is the required configuration for the future host. ### TD-06 Vite config in TypeScript - `vite.config.js` becomes `vite.config.ts`. It contains: - the existing plugins - the local `sitemap` plugin (BR-SEO-06), which reads `sitePages` - the security headers (TD-05) - the Vitest `test` section - **Plugin**: about 30 lines, using Rollup's `generateBundle` hook to emit `sitemap.xml`. The XML itself comes from the pure, tested `sitemapXml`. ### TD-07 Scripts in `package.json` | Script | Runs | |---|---| | `test` | `vitest run --coverage` | | `test:watch` | `vitest` | | `lint` | `eslint .` | | `format:check` | `prettier --check .` | | `audit:deps` | `pnpm audit --audit-level high` | | `lighthouse` | `lhci autorun` | | `check` | lint → format:check → test → build → audit:deps → lighthouse, stopping at the first failure | ### TD-08 Colour mode - **Without `next-themes`**: the light theme is the default. The `_dark` semantic token values stay in the theme, so a dark mode can be added later without rework. - **Considered**: keeping `next-themes` and allowing its script via a CSP hash. Rejected: the hash breaks on every library update, and the script has no use while the site is light-only. ## Security Baseline Compliance (NFR Requirements) | Rule | Status | Rationale | |---|---|---| | SECURITY-04 | Compliant | Header set + CSP defined, `unsafe-inline` only for styles with documented justification (NFR-SEC-01…04) | | SECURITY-09 | Compliant | Devtools dev-only, starter assets removed, generic error pages | | SECURITY-10 | Compliant | Lock file, `audit:deps` in `check`, unused `next-themes` removed, build tools in dev | | SECURITY-13 | Compliant | No CDN resources; Lighthouse CI uploads nothing externally | | SECURITY-15 | Compliant | Root error boundary (NFR-R-01) | | SECURITY-03, -14 | N/A | No server component; revisit with the .NET API | | Others | N/A | As in requirements.md | ## PBT Compliance (NFR Requirements) | Rule | Status | Rationale | |---|---|---| | PBT-09 | Compliant | fast-check: custom arbitraries, shrinking, seed replay, runs in Vitest (TD-01) | | Others | N/A at this stage | Applied in Code Generation |