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

1. Data Access: Wire only through feature hooks that wrap TanStack Query. Never fetch inside UI components.

1. New Routes:

- Create file under /src/routes/** (file-based routing) - If needs data at navigation, add loader that prefetches with Query

1. 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

1. Compiler-Friendly:

- Keep code pure (pure components, minimal effects) - If compiler flags something, fix it or add "use no memo" temporarily

1. Tests:

- Add Vitest tests for new logic - Component tests use RTL - Stub network with msw

1. 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