core-principles by MadAppGang

---
name: core-principles
description: Use when planning new projects, onboarding, or reviewing architectural decisions. Core principles and project structure for React 19 SPA development. Covers stack overview, project organization, agent execution rules, and authoritative sources.
updated: 2026-01-20
keywords: react-19, spa, project-structure, architecture, vite, typescript, tanstack, biome
---

# 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