Skip to content

ADR-0005: React 19 for Frontend Framework

Status: Accepted Date: 2025-01-15 (Estimated) Deciders: GetCimple Team Tags: architecture, frontend, framework

Context

GetCimple needs a frontend framework for building the compliance SaaS web application.

Requirements: - Modern UI framework with strong ecosystem - Component library availability (shadcn/ui, Radix UI) - TypeScript support - State management for complex compliance dashboards - Form handling with validation (assessment questionnaires) - Data tables (compliance reports, audit trails) - Fast development velocity for 3-person team

Constraints: - Team has React experience - Must integrate with Supabase (good React client support) - Must integrate with Kinde Auth (React SDK available) - Build tool: Vite (already decided) - Budget: Free framework preferred

Options Considered

Option A: React 19 + Vite

Description: Latest React with Vite build tool, shadcn/ui components, TanStack ecosystem.

Pros: - ✅ Massive ecosystem: Largest component library selection (shadcn/ui, Radix, MUI, Chakra) - ✅ Team familiarity: All team members know React - ✅ TypeScript excellence: First-class TypeScript support - ✅ TanStack ecosystem: Query, Table, Router, Form all best-in-class - ✅ shadcn/ui: 50+ production-ready, accessible components (perfect for compliance SaaS) - ✅ Vite integration: Fast HMR, instant dev server, optimized builds - ✅ Supabase: Excellent React client (@supabase/supabase-js) - ✅ Kinde: React SDK available (@kinde-oss/kinde-auth-react) - ✅ React Hook Form + Zod: Perfect for compliance questionnaires - ✅ Documentation: Extensive resources, large community - ✅ Server Components: React 19 brings server-side improvements (can adopt later)

Cons: - ❌ Bundle size larger than Svelte or Solid - ❌ Re-renders can be inefficient (requires memoization discipline) - ❌ More boilerplate than Svelte

Estimated Effort: 1 week (team already familiar)

Option B: Svelte/SvelteKit

Description: Compiled framework with smaller bundle size, SvelteKit for full-stack.

Pros: - ✅ Smaller bundle size (faster page loads) - ✅ Less boilerplate (cleaner code) - ✅ SvelteKit full-stack features - ✅ Good TypeScript support

Cons: - ❌ Smaller ecosystem: Fewer component libraries - ❌ Learning curve: Team would need to learn Svelte syntax - ❌ No shadcn/ui equivalent: Would need to build components from scratch or use limited libraries - ❌ TanStack not optimized for Svelte: Query works but Table/Router less mature - ❌ Smaller community (harder to find solutions) - ❌ Riskier bet for startup (less proven at scale)

Estimated Effort: 2-3 weeks (learning curve)

Option C: Vue 3 + Nuxt

Description: Progressive framework with Nuxt for full-stack features.

Pros: - ✅ Good component ecosystem - ✅ Good TypeScript support - ✅ Nuxt provides full-stack features

Cons: - ❌ Team unfamiliar with Vue - ❌ Smaller than React ecosystem - ❌ No shadcn/ui equivalent - ❌ Learning curve for team

Estimated Effort: 2-3 weeks (learning curve)

Decision

We chose: Option A - React 19 + Vite

Rationale: 1. Zero learning curve: Team already knows React, can start building immediately 2. shadcn/ui advantage: 50+ accessible, production-ready components save weeks of UI development 3. TanStack ecosystem: Query (server state), Table (data grids), Router, Form all best-in-class for our needs 4. Component availability: Need complex data tables, forms with validation, dashboards—React has proven libraries 5. Integration certainty: Both Supabase and Kinde have excellent React SDKs and examples 6. Startup velocity: Use proven tools, ship fast, optimize later 7. Compliance UX: shadcn/ui components are accessible (WCAG 2.1) out-of-the-box

Key Trade-offs Accepted: - We're accepting larger bundle size (React ~50KB vs Svelte ~10KB) for ecosystem advantages - We're accepting potential re-render performance issues by using React best practices (memoization, React.memo) - We're choosing "boring technology" over "innovative" (Svelte/Solid) for risk reduction

Consequences

Positive

  • ✅ Immediate productivity: Team starts building features day 1, no learning curve
  • ✅ Component velocity: shadcn/ui provides dashboards, forms, tables instantly
  • ✅ Form handling: React Hook Form + Zod perfect for compliance questionnaires
  • ✅ Data management: TanStack Query handles server state with caching, mutations, real-time
  • ✅ Table complexity: TanStack Table handles sortable, filterable compliance reports
  • ✅ TypeScript: Strong typing from Supabase schema → React components
  • ✅ Community: Largest React community means every problem already solved on Stack Overflow

Negative

  • ⚠️ Bundle size: Initial load ~200-300KB (acceptable with code splitting)
  • ⚠️ Performance discipline: Team must use React.memo, useMemo, useCallback properly
  • ⚠️ Boilerplate: More code than Svelte (useState, useEffect vs Svelte reactivity)

Risks

Risk Likelihood Impact Mitigation
Performance issues from unnecessary re-renders MEDIUM MEDIUM Use React DevTools Profiler; implement memoization; code review for performance
Bundle size affects mobile users LOW MEDIUM Code splitting; lazy loading; monitor Core Web Vitals; compress assets
React ecosystem churn (new state library trends) LOW LOW Stick with TanStack ecosystem; avoid flavor-of-the-month libraries

Compliance Note

ACSC Essential 8 Impact: - Not directly applicable: Frontend framework is implementation detail - User Application Hardening: React security best practices (XSS prevention, CSP headers)

Australian Data Residency: - Frontend code: Served globally via Cloudflare CDN (no data residency concerns) - Client-side processing: All sensitive data processing done server-side (Supabase)

Audit Trail: - Frontend code changes tracked via Git - User actions logged via application code (not framework-specific)

Implementation Notes

Prerequisites: - Node.js 18+ and pnpm installed - Vite configured - TypeScript config established

Integration Points: - Vite: Build tool with React plugin - shadcn/ui: Component library - TanStack Query: Server state management - React Hook Form: Form handling - Zod: Schema validation - Supabase: @supabase/supabase-js client - Kinde: @kinde-oss/kinde-auth-react

Monitoring: - Core Web Vitals (LCP, FID, CLS) - Bundle size tracking - React DevTools for performance profiling

Documentation Updates Needed: - ✅ Frontend architecture in tech-stack-mvp.md - ✅ Component patterns in development docs - ✅ React best practices guide (to be created)

Revisit

Revisit By: 2026-06-01 or if performance issues arise Blast Radius: CRITICAL - Entire frontend would need rewrite

Conditions for Revisit: - Consistent performance issues that cannot be resolved (>500ms interaction latency) - React ecosystem significantly changes (unlikely) - Team expands with Svelte/Vue expertise and wants to migrate - New framework emerges that's significantly better (very unlikely)

Next Review: 2025-12-01 (evaluate performance and team satisfaction)

References

Version History

Version Date Author Changes
1.0 2025-10-20 Claude Initial ADR capturing historical decision