madappgang/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