stwaidele/dorfteich
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 22 Wiki Activity
6d51c0d099
dorfteich/docs/architecture/adr/0005-react-vite-frontend.md
Claude Fable 5 0629411966 Add architecture documentation, ADRs, and operations concept 
Initial deliverable of the architecture phase: 16 ADRs (stack, CRDT
collaboration, plugin sandbox, import/export, backups, CI/CD), data
model, permission model, real-time collaboration and plugin concepts,
deployment/operations/security documentation, and the milestone roadmap
that the implementation issues are derived from.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-04 14:36:16 +02:00

2.4 KiB
Raw Blame History

ADR 0005: React + Vite single-page application

  • Status: accepted
  • Date: 2026-07-04

Context

The frontend hosts a heavily stateful collaborative editor (ADR 0003/0004), a collapsible pond sidebar, admin UIs, and a plugin sandbox host. It must work offline (PWA) and be maintainable by many independent contributors. SEO for wiki content matters only for publicly readable pages; the separate static project site (dorfteich.cloud) covers marketing needs.

Decision

  • React (current stable) + Vite + TypeScript, shipped as a static single-page application served by the web container (nginx serving dist/, with SPA fallback to index.html).
  • Routing: React Router. Server state: TanStack Query. Local/UI state: Zustand where component state is not enough. Forms: react-hook-form + Zod schemas from packages/shared.
  • Styling: CSS custom properties + a small utility layer; the visual design is plain and professional per the vision. Pond-level font configuration (ADR 0016) is applied via CSS variables.
  • PWA: vite-plugin-pwa service worker caches the app shell for offline editor startup (works with y-indexeddb, ADR 0003).
  • Public read-only pages are server-rendered for crawlers only where needed: the API exposes a plain HTML rendering endpoint per public page (also used for PDF export, ADR 0009). We deliberately avoid SSR frameworks for the app itself.

Consequences

  • Simple deployment (static files + API), no Node server for the frontend.
  • TipTap's React bindings are first-class; the editor integration follows the officially documented path.
  • The SPA is the only consumer of the REST API, which keeps the API honest as the boundary for self-hosted automation and future integrations.
  • SEO for public wiki pages relies on the HTML rendering endpoint being served to crawlers via reverse-proxy rules — documented in deployment.md and acceptable for a wiki (dorfteich.cloud handles discoverability of the product itself).

Alternatives considered

  • SvelteKit: excellent framework and used elsewhere in the operator's projects, but the TipTap/Yjs collaborative-editing ecosystem, examples, and collective experience are strongest in React; for a contributor-diverse open-source project the larger ecosystem wins.
  • Next.js: SSR/ISR complexity buys little for an app that is 95% behind a login or served to a small community; PWA/offline is simpler in a pure SPA.