@react-spa-scaffold/mcp 0.3.0

package/templates/CLAUDE.md

@@ -0,0 +1,145 @@
+# CLAUDE.md
+
+AI assistant guidance for this React 19 + TypeScript + Vite 7 codebase. See [README.md](README.md) for project overview and tech rationale.
+
+## Commands
+
+```bash
+npm run dev              # Dev server at localhost:5173
+npm run build            # Production build (typecheck + bundle)
+npm run typecheck        # TypeScript only
+npm run lint             # ESLint check
+npm run lint:fix         # ESLint auto-fix
+npm run format           # Prettier format
+npm run test             # Vitest once
+npm run test:watch       # Vitest watch mode
+npm run test:coverage    # Coverage (80% threshold)
+npm run e2e              # Playwright E2E
+npm run i18n:extract     # Extract translations to .po
+```
+
+## Project Structure
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for full structure and data flow.
+
+```
+src/
+├── components/    # ui/ (primitives), layout/, shared/ (features)
+├── contexts/      # React Context providers
+├── hooks/         # Custom hooks
+├── lib/           # api, routes, config, utils, format, storage
+├── pages/         # Lazy-loaded route components
+├── stores/        # Zustand stores
+└── types/         # TypeScript definitions
+
+tests/unit/        # Vitest (mirrors src/)
+e2e/               # Playwright tests
+```
+
+## Code Patterns
+
+**Imports**: Always use `@/` path alias
+
+**Components**: Named exports + `Props` interface. Pages use default exports for lazy loading.
+
+**TypeScript**: `type` for unions, `interface` for objects
+
+**State hierarchy**: Zustand (persisted) → TanStack Query (server) → Context (UI) → useState (local)
+
+See [docs/CODING_STANDARDS.md](docs/CODING_STANDARDS.md) and [docs/COMPONENT_GUIDELINES.md](docs/COMPONENT_GUIDELINES.md).
+
+## UI Components (Shadcn/UI)
+
+This project uses **Shadcn/UI** with radix-nova style. Components live in `src/components/ui/`.
+
+### Adding New Components
+
+```bash
+npx shadcn@latest add button           # Single component
+npx shadcn@latest add dialog card input # Multiple components
+```
+
+**Pattern**: Import directly (no barrel exports for UI):
+
+```tsx
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+```
+
+## MCP Servers (PREFER OVER WebSearch)
+
+Use MCP servers for documentation lookup. They provide **structured, version-accurate data** directly from source—faster and more reliable than web scraping.
+
+### Why MCP over WebSearch?
+
+- **Accuracy**: MCP fetches from official sources, not potentially outdated blog posts
+- **Version-aware**: Gets docs for the exact library version you're using
+- **Structured**: Returns code snippets, types, and examples in consistent format
+- **Faster**: Direct API calls vs parsing HTML from search results
+
+### Shadcn MCP (UI Components)
+
+| Need                | Tool                                             |
+| ------------------- | ------------------------------------------------ |
+| Find component      | `mcp__shadcn__search_items_in_registries`        |
+| View component code | `mcp__shadcn__view_items_in_registries`          |
+| Usage examples      | `mcp__shadcn__get_item_examples_from_registries` |
+| CLI add command     | `mcp__shadcn__get_add_command_for_items`         |
+
+### Context7 MCP (All 3rd Party Libraries)
+
+Use for **any npm package** documentation—not just React libraries:
+
+```
+resolve-library-id → get-library-docs
+```
+
+**Examples**:
+
+- `react-hook-form` - Form validation patterns
+- `@tanstack/react-query` - Query/mutation usage
+- `zustand` - Store patterns
+- `zod` - Schema validation
+- `date-fns` - Date formatting
+- `msw` - Mock service worker setup
+
+### Decision Flow
+
+```
+Need UI component?     → Shadcn MCP
+Need library docs?     → Context7 MCP (any npm package)
+Need general info?     → WebSearch (fallback only)
+```
+
+## Translations (CRITICAL)
+
+All user-facing text MUST have translator comments. ESLint enforces this.
+
+```tsx
+<Trans comment="Dashboard heading">Welcome back</Trans>;
+t({ message: 'Close', comment: 'Close button' });
+```
+
+See [docs/INTERNATIONALIZATION.md](docs/INTERNATIONALIZATION.md).
+
+## Testing
+
+See [docs/TESTING.md](docs/TESTING.md) and [docs/E2E_TESTING.md](docs/E2E_TESTING.md).
+
+Tests in `tests/unit/` mirror `src/` structure. 80% coverage required.
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { screen, renderHook } from '@testing-library/react';
+import { render, mockMatchMedia, server } from '@/test';
+```
+
+MSW handlers auto-reset after each test.
+
+## Common Gotchas
+
+1. **Node.js >= 22.0.0** required (check `.nvmrc`)
+2. **Conventional commits** enforced by commitlint
+3. **Context hooks throw** outside provider (e.g., `useMobileContext()`)
+4. **Barrel exports** in each directory via `index.ts`
+5. **UI components** import directly: `@/components/ui/button` (no barrel)

package/templates/docs/API_REFERENCE.md

@@ -0,0 +1,58 @@
+# API Reference
+
+Quick reference for what's available. For architectural decisions, see [Architecture Guide](./ARCHITECTURE.md).
+
+## Utilities (`lib/`)
+
+| Module           | Purpose               | When to Use                                                         |
+| ---------------- | --------------------- | ------------------------------------------------------------------- |
+| `api.ts`         | HTTP client           | Any API calls - handles errors, timeouts, JSON. Includes API_CONFIG |
+| `config.ts`      | App configuration     | Access APP_CONFIG, SENTRY_CONFIG                                    |
+| `env.ts`         | Environment variables | Type-safe `env.VITE_*` access                                       |
+| `format.ts`      | Formatters            | Dates, numbers, currency, bytes - all locale-aware                  |
+| `routes.ts`      | Route constants       | Type-safe navigation, avoid magic strings                           |
+| `storage.ts`     | localStorage wrapper  | SSR-safe, typed storage with error handling                         |
+| `storageKeys.ts` | Storage key constants | Centralized key management                                          |
+| `utils.ts`       | Common utilities      | `cn()` for Tailwind class merging                                   |
+
+### Key Pattern: API Client
+
+```tsx
+import { api } from '@/lib/api';
+
+const data = await api.get<User[]>('/users');
+// Throws ApiClientError on failure (check .status for HTTP code)
+```
+
+## Hooks (`hooks/`)
+
+| Hook                           | Purpose               | When to Use                          |
+| ------------------------------ | --------------------- | ------------------------------------ |
+| `useMediaQuery`                | Track media query     | Custom responsive logic              |
+| `useIsMobile` / `useIsDesktop` | Viewport checks       | Conditional rendering by screen size |
+| `useLanguage`                  | Locale state          | Language switcher components         |
+| `useThemeEffect`               | Theme sync            | Apply theme to document              |
+| `useTouchSizes`                | Touch-friendly sizing | Mobile-optimized UI                  |
+
+### Key Pattern: Context Hooks
+
+Context hooks throw if used outside their provider:
+
+```tsx
+const { isMobile } = useMobileContext();
+// Throws if not wrapped in <MobileProvider>
+```
+
+## Contexts (`contexts/`)
+
+| Context         | Provider         | Purpose                                  |
+| --------------- | ---------------- | ---------------------------------------- |
+| `mobileContext` | `MobileProvider` | Viewport detection (isMobile, isDesktop) |
+
+## Stores (`stores/`)
+
+| Store              | Purpose                        | Persisted?         |
+| ------------------ | ------------------------------ | ------------------ |
+| `preferencesStore` | User preferences (theme, etc.) | Yes (localStorage) |
+
+Access via Zustand hooks - see store files for available actions.

package/templates/docs/ARCHITECTURE.md

@@ -0,0 +1,185 @@
+# Architecture Guide
+
+High-level architecture and key decisions. For API details, see [API Reference](./API_REFERENCE.md).
+
+## Tech Stack
+
+| Layer          | Technology               | Why                                         |
+| -------------- | ------------------------ | ------------------------------------------- |
+| Framework      | React 19 + TypeScript    | Largest ecosystem, concurrent features      |
+| Build          | Vite 7                   | 10-100x faster than Webpack, native ESM     |
+| Routing        | React Router 7           | De facto standard, lazy loading support     |
+| Styling        | Tailwind CSS 4           | No runtime cost, scales with team size      |
+| State          | Zustand + TanStack Query | Minimal boilerplate, separation of concerns |
+| Forms          | React Hook Form + Zod    | Minimal re-renders, type-safe validation    |
+| i18n           | Lingui                   | Smaller runtime, compile-time extraction    |
+| Testing        | Vitest + Playwright      | Fast, Vite-native, true cross-browser       |
+| Error Tracking | Sentry                   | Industry standard, lazy-loaded              |
+
+## Project Structure
+
+```
+src/
+├── components/
+│   ├── layout/     # Page structure (Header)
+│   ├── shared/     # Feature components (ThemeToggle, LanguageSwitcher)
+│   └── ui/         # Primitives (Button, Spinner) - shadcn/ui
+├── contexts/       # React Context providers
+├── hooks/          # Custom React hooks
+├── i18n/           # Internationalization setup
+├── lib/            # Utilities, API client, config, routes
+├── locales/        # Translation files (.po)
+├── mocks/          # MSW handlers and fixtures
+├── pages/          # Route page components
+├── stores/         # Zustand stores
+├── test/           # Test utilities and providers
+└── types/          # Shared TypeScript definitions
+
+tests/unit/         # Vitest tests (mirrors src/ structure)
+e2e/                # Playwright end-to-end tests
+```
+
+### Why This Structure?
+
+- **components/ui/**: Primitives from shadcn/ui. Direct imports (`@/components/ui/button`) because shadcn recommends against barrel exports for tree-shaking.
+- **components/shared/**: Feature components with barrel exports. Each feature folder contains component + index.ts.
+- **lib/**: Pure utilities with no React dependencies. Can be tested without rendering.
+- **pages/**: One component per route. Default exports enable lazy loading.
+
+## Data Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        App Entry                            │
+│  main.tsx → Providers → App.tsx → Routes → Pages            │
+└─────────────────────────────────────────────────────────────┘
+                              │
+         ┌────────────────────┼────────────────────┐
+         ▼                    ▼                    ▼
+   ┌──────────┐        ┌──────────┐        ┌──────────┐
+   │  Zustand │        │ TanStack │        │  Context │
+   │  Stores  │        │  Query   │        │ Providers│
+   └──────────┘        └──────────┘        └──────────┘
+         │                    │                    │
+   Persisted           Server State          UI State
+   Preferences         (API Cache)          (Mobile, etc)
+```
+
+## Key Architectural Decisions
+
+### 1. Provider Hierarchy
+
+Providers wrap the app in this specific order:
+
+```tsx
+<StrictMode>
+  <QueryProvider>
+    {' '}
+    {/* TanStack Query - outermost for global cache */}
+    <I18nProvider>
+      {' '}
+      {/* Lingui - translations available everywhere */}
+      <BrowserRouter>
+        {' '}
+        {/* React Router - routing context */}
+        <MobileProvider>
+          {' '}
+          {/* Viewport - depends on router for SSR */}
+          <ErrorBoundary>
+            <App />
+            <Toaster />
+          </ErrorBoundary>
+        </MobileProvider>
+      </BrowserRouter>
+    </I18nProvider>
+  </QueryProvider>
+</StrictMode>
+```
+
+**Why this order?**
+
+- QueryProvider outermost so cache persists across route changes
+- I18nProvider before Router so route components can use translations
+- MobileProvider inside Router for potential SSR viewport detection
+- ErrorBoundary innermost to catch errors in App without breaking providers
+
+### 2. State Management Separation
+
+| Use Case              | Solution            | Location          | Why                           |
+| --------------------- | ------------------- | ----------------- | ----------------------------- |
+| User preferences      | Zustand + persist   | `stores/`         | Survives refresh, syncs tabs  |
+| Server/async data     | TanStack Query      | `hooks/use*Query` | Automatic caching, refetching |
+| Shared UI state       | React Context       | `contexts/`       | Prop drilling avoidance       |
+| Component-local state | useState/useReducer | Component file    | Simplest solution             |
+
+**Key invariant**: Server state (TanStack Query) and client state (Zustand) never overlap. If data comes from an API, use Query. If it's user preference, use Zustand.
+
+### 3. Lazy Loading Strategy
+
+Pages are lazy-loaded to reduce initial bundle size:
+
+```tsx
+// App.tsx
+const HomePage = lazy(() => import('@/pages/Home').then((m) => ({ default: m.HomePage })));
+
+// Routes
+<Suspense fallback={<PageSkeleton />}>
+  <Routes>
+    <Route path={ROUTES.HOME} element={<HomePage />} />
+  </Routes>
+</Suspense>;
+```
+
+**Why pages only?**
+
+- Pages are the largest units and least likely to be needed immediately
+- UI components are small and frequently reused—overhead of lazy loading outweighs benefit
+- Shared components may be needed before Suspense resolves
+
+### 4. Error Handling Layers
+
+| Layer      | Mechanism      | Catches                 |
+| ---------- | -------------- | ----------------------- |
+| Component  | ErrorBoundary  | React render errors     |
+| API        | ApiClientError | Network/HTTP errors     |
+| Global     | window.onerror | Uncaught exceptions     |
+| Production | Sentry         | All errors with context |
+
+**Key invariant**: Errors should never silently fail. Every error either:
+
+- Shows user feedback (toast, error UI)
+- Logs to console (development)
+- Reports to Sentry (production)
+
+### 5. Translation Enforcement
+
+All user-facing text must have translator comments. This is enforced by ESLint.
+
+**Why mandatory comments?**
+
+- Translators lack code context—"Close" could be adjective or verb
+- Comments appear in PO files, reducing translation errors
+- ESLint catches missing comments before merge
+
+## Import Conventions
+
+```tsx
+// UI primitives: direct import (no barrel)
+import { Button } from '@/components/ui/button';
+
+// Shared components: barrel export
+import { ThemeToggle } from '@/components/shared';
+
+// Utilities
+import { api } from '@/lib/api';
+import { render } from '@/test';
+```
+
+## Related Docs
+
+- [API Reference](./API_REFERENCE.md) - Utilities, hooks, and common patterns
+- [Component Guidelines](./COMPONENT_GUIDELINES.md) - React component blueprint
+- [Coding Standards](./CODING_STANDARDS.md) - TypeScript and state patterns
+- [Testing](./TESTING.md) - Unit testing guidelines
+- [E2E Testing](./E2E_TESTING.md) - Playwright patterns
+- [Internationalization](./INTERNATIONALIZATION.md) - Lingui i18n setup

package/templates/docs/CODING_STANDARDS.md

@@ -0,0 +1,53 @@
+# Coding Standards
+
+See [Architecture Guide](./ARCHITECTURE.md) for project structure and [Component Guidelines](./COMPONENT_GUIDELINES.md) for the complete React component blueprint.
+
+## TypeScript
+
+Use `type` for unions, `interface` for object shapes:
+
+```tsx
+type Theme = 'light' | 'dark' | 'system';
+
+interface User {
+  id: string;
+  name: string;
+}
+```
+
+## State Management
+
+See [Architecture Guide](./ARCHITECTURE.md#state-management) for when to use each solution.
+
+### Query Hooks
+
+Extract the fetcher function:
+
+```tsx
+async function fetchTodos(): Promise<Todo[]> {
+  return api.get<Todo[]>('/todos');
+}
+
+export function useTodosQuery() {
+  return useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  });
+}
+```
+
+### Context Hooks
+
+Throw if used outside their provider:
+
+```tsx
+const MyContext = createContext<MyValue | null>(null);
+
+export function useMyContext() {
+  const context = useContext(MyContext);
+  if (!context) {
+    throw new Error('useMyContext must be used within MyProvider');
+  }
+  return context;
+}
+```