Files
AndreaSlopFotografie/aidlc-docs/features/frontend-shell/construction/frontend-shell/nfr-requirements/tech-stack-decisions.md
T
SluijsensandClaude Opus 5.5 069c7cb7eb Adds AI-DLC construction docs for the front-end shell feature
Functional design, NFR requirements, code generation plan and summary,
and build-and-test instructions with results.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18 17:05:03 +02:00

6.1 KiB

Tech Stack Decisions — frontend-shell

Existing stack (unchanged): React 19, TypeScript, Vite, TanStack Router, Chakra UI v3, pnpm. See 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