core-principles

# Core Principles for React 19 SPA Development Production-ready best practices for building modern React applications with TypeScript, Vite, and TanStack ecosystem. ## Stack Overview - **React 19** with React Compiler (auto-memoization) - **TypeScript** (strict mode) - **Vite** (bundler) - **Biome** (formatting + linting) - **TanStack Query** (server state) - **TanStack Router** (file-based routing) - **Vitest** (testing with jsdom) - **Apidog MCP** (API spec source of truth) ## Project Structure ``` /src /app/ # App shell, providers, global styles /routes/ # TanStack Router file-based routes /components/ # Reusable, pure UI components (no data-fetch) /features/ # Feature folders (UI + hooks local to a feature) /api/ # Generated API types & client (from OpenAPI) /lib/ # Utilities (zod schemas, date, formatting, etc.) /test/ # Test utilities ``` **Key Principles:** - One responsibility per file - UI components don't fetch server data - Put queries/mutations in feature hooks - Co-locate tests next to files ## Agent Execution Rules **Always do this when you add or modify code:** 1. **API Spec:** Fetch latest via Apidog MCP and regenerate `/src/api` types if changed 2. **Data Access:** Wire only through feature hooks that wrap TanStack Query. Never fetch inside UI components. 3. **New Routes:** - Create file under `/src/routes/**` (file-based routing) - If needs data at navigation, add loader that prefetches with Query 4. **Server Mutations:** - Use React 19 Actions OR TanStack Query `useMutation` (choose one per feature) - Use optimistic UI via `useOptimistic` (Actions) or Query's optimistic updates - Invalidate/selectively update cache on success 5. **Compiler-Friendly:** - Keep code pure (pure components, minimal effects) - If compiler flags something, fix it or add `"use no memo"` temporarily 6. **Tests:** - Add Vitest tests for new logic - Component tests use RTL - Stub network with msw 7. **Before Committing:** - Run `biome check --write` - Ensure Vite build passes ## "Done" Checklist per PR - [ ] Route file added/updated; loader prefetch (if needed) present - [ ] Query keys are stable (`as const`), `staleTime`/`gcTime` tuned - [ ] Component remains pure; no unnecessary effects; compiler ✨ visible - [ ] API calls typed from `/src/api`; inputs/outputs validated at boundaries - [ ] Tests cover new logic; Vitest jsdom setup passes - [ ] `biome check --write` clean; Vite build ok ## Authoritative Sources - **React 19 & Compiler:** - React v19 overview - React Compiler: overview + installation + verification - `<form action>` / Actions API; `useOptimistic`; `use` - CRA deprecation & guidance - **Vite:** - Getting started; env & modes; TypeScript targets - **TypeScript:** - `moduleResolution: "bundler"` (for bundlers like Vite) - **Biome:** - Formatter/Linter configuration & CLI usage - **TanStack Query:** - Caching & important defaults; v5 migration notes; devtools/persisting cache - **TanStack Router:** - Install with Vite plugin; file-based routing; search params; devtools - **Vitest:** - Getting started & config (jsdom) - **Apidog + MCP:** - Apidog docs (import/export, OpenAPI); MCP server usage ## Final Notes - Favor compile-friendly React patterns - Let the compiler and Query/Router handle perf and data orchestration - Treat Apidog's OpenAPI (via MCP) as the single source of truth for network shapes - Keep this doc as your "contract"—don't add heavy frameworks or configs beyond what's here unless explicitly requested ## Related Skills - **tooling-setup** - Vite, TypeScript, Biome configuration - **react-patterns** - React 19 specific patterns (compiler, actions, forms) - **tanstack-router** - Routing patterns - **tanstack-query** - Server state management with Query v5 - **router-query-integration** - Integrating Router with Query - **api-integration** - Apidog + MCP patterns - **performance-security** - Performance, accessibility, security