@react-spa-scaffold/mcp 0.3.0

package/templates/docs/TESTING.md

@@ -0,0 +1,259 @@
+# Testing Guidelines
+
+## Overview
+
+- **Framework**: Vitest + React Testing Library
+- **Coverage threshold**: 80% (lines, branches, functions, statements)
+- **Test location**: `tests/unit/` mirroring `src/` structure
+
+## File Structure
+
+```
+tests/unit/
+├── components/     # Component tests
+├── hooks/          # Hook tests
+├── lib/            # Utility function tests
+├── stores/         # Zustand store tests
+├── contexts/       # Context provider tests
+└── i18n/           # Internationalization tests
+```
+
+## Naming Conventions
+
+```typescript
+// File: [name].test.ts or [name].test.tsx (for JSX)
+// Describe blocks: match the module/function name
+// Test names: describe behavior, not implementation
+
+describe('formatDate', () => {
+  it('returns "Invalid date" for invalid input', () => {});
+  it('formats date with custom options', () => {});
+});
+```
+
+## Imports
+
+```typescript
+// Vitest - test framework
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// Testing Library - DOM utilities
+import { screen, renderHook, act, waitFor, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+// Custom utilities from @/test
+import { render, mockMatchMedia, createTestQueryClient, server } from '@/test';
+```
+
+## Core Patterns
+
+### Use `it.each` for Similar Tests
+
+```typescript
+// ✅ Good - parameterized tests
+it.each([
+  { input: 0, expected: '0 Bytes' },
+  { input: 1024, expected: '1 KB' },
+  { input: 1024 * 1024, expected: '1 MB' },
+])('formats $input bytes', ({ input, expected }) => {
+  expect(formatBytes(input)).toBe(expected);
+});
+
+// ❌ Avoid - repetitive individual tests
+it('formats 0 bytes', () => expect(formatBytes(0)).toBe('0 Bytes'));
+it('formats 1024 bytes', () => expect(formatBytes(1024)).toBe('1 KB'));
+it('formats 1MB', () => expect(formatBytes(1024 * 1024)).toBe('1 MB'));
+```
+
+### Use Shared Mocks
+
+```typescript
+import { mockMatchMedia } from '@/test';
+
+describe('useMediaQuery', () => {
+  beforeEach(() => {
+    window.matchMedia = mockMatchMedia(false);
+  });
+
+  it('detects desktop viewport', () => {
+    window.matchMedia = mockMatchMedia(true); // matches min-width query
+    const { result } = renderHook(() => useIsDesktop());
+    expect(result.current).toBe(true);
+  });
+});
+```
+
+### Component Testing
+
+```typescript
+import { screen } from '@testing-library/react';
+import { render } from '@/test';
+
+describe('Header', () => {
+  it('renders navigation links', () => {
+    render(<Header />);
+    expect(screen.getByRole('navigation')).toBeInTheDocument();
+  });
+});
+```
+
+### Hook Testing
+
+```typescript
+import { renderHook, act } from '@testing-library/react';
+
+describe('useCounter', () => {
+  it('increments value', () => {
+    const { result } = renderHook(() => useCounter());
+
+    act(() => result.current.increment());
+
+    expect(result.current.count).toBe(1);
+  });
+});
+```
+
+### Async Testing
+
+```typescript
+// For promises
+it('fetches data', async () => {
+  const result = await fetchData();
+  expect(result).toBeDefined();
+});
+
+// For state updates
+it('updates after async action', async () => {
+  const { result } = renderHook(() => useAsync());
+
+  await waitFor(() => {
+    expect(result.current.data).toBeDefined();
+  });
+});
+```
+
+### Mocking
+
+```typescript
+import { mockMatchMedia } from '@/test';
+
+// Mock modules at top of file
+vi.mock('@/lib/storage', () => ({
+  setStorageItem: vi.fn(() => true),
+}));
+
+// Mock browser APIs using shared utilities
+beforeEach(() => {
+  window.matchMedia = mockMatchMedia(false);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// Mock fetch for API tests
+const mockFetch = vi.fn();
+beforeEach(() => {
+  global.fetch = mockFetch;
+});
+mockFetch.mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({}) });
+```
+
+### MSW (Mock Service Worker)
+
+MSW handlers are organized in `src/mocks/`:
+
+```
+src/mocks/
+├── handlers/
+│   ├── index.ts     # Combines all handlers
+│   └── todos.ts     # Example domain handlers
+├── fixtures/
+│   └── todos.ts     # Response data
+├── browser.ts       # Browser worker setup
+└── node.ts          # Node server for tests
+```
+
+Override handlers per-test:
+
+```typescript
+import { http, HttpResponse, server } from '@/test';
+
+it('handles API error', async () => {
+  server.use(http.get('/api/todos', () => new HttpResponse(null, { status: 500 })));
+  // Test error handling...
+});
+```
+
+MSW handlers auto-reset after each test via `src/test-setup.ts`.
+
+### Store Testing (Zustand)
+
+```typescript
+import { act } from '@testing-library/react';
+
+describe('preferencesStore', () => {
+  beforeEach(() => {
+    usePreferencesStore.setState({ theme: 'light' });
+  });
+
+  it.each(['light', 'dark', 'system'] as const)('sets theme to %s', (theme) => {
+    act(() => usePreferencesStore.getState().setTheme(theme));
+    expect(usePreferencesStore.getState().theme).toBe(theme);
+  });
+});
+```
+
+## Test Organization
+
+### Structure Within Test Files
+
+```typescript
+describe('ModuleName', () => {
+  // Setup/teardown at top
+  beforeEach(() => {});
+  afterEach(() => {});
+
+  // Group related tests
+  describe('methodName', () => {
+    it('handles normal case', () => {});
+    it('handles edge case', () => {});
+    it('handles error case', () => {});
+  });
+});
+```
+
+### What to Test
+
+| Type       | Test Focus                                    |
+| ---------- | --------------------------------------------- |
+| Components | Rendering, user interactions, accessibility   |
+| Hooks      | Return values, state changes, side effects    |
+| Utils      | Input/output, edge cases, error handling      |
+| Stores     | State mutations, computed values, persistence |
+
+### What NOT to Test
+
+- Implementation details (internal state, private methods)
+- Third-party library internals
+- Static content without logic
+- TypeScript types (compiler handles this)
+
+## Running Tests
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+npm run test:coverage # With coverage report
+npm run test:ui       # Visual UI
+```
+
+## Checklist for New Tests
+
+- [ ] File follows `[name].test.ts(x)` naming
+- [ ] Uses `it.each` for parameterized cases
+- [ ] Mocks are cleared in `beforeEach`/`afterEach`
+- [ ] No duplicate helper functions
+- [ ] Tests behavior, not implementation
+- [ ] Async tests use `await`/`waitFor` properly
+- [ ] Coverage threshold maintained (80%)

package/templates/docs/WORKFLOW.md

@@ -0,0 +1,170 @@
+# Workflow Commands
+
+Custom commands to support TDD feature development.
+
+## Commands
+
+### /implement
+
+**Purpose**: Setup for TDD feature implementation.
+
+**Usage**:
+
+```
+/implement <feature description>
+```
+
+**What it does**:
+
+1. Creates a task branch
+2. Provides instructions to run `/feature-dev` with TDD context
+3. Reminds you to run `/check` before committing
+
+**Note**: This is a setup command. You'll manually run `/feature-dev` with the TDD instructions provided.
+
+### /check
+
+**Purpose**: Pre-commit quality validation.
+
+**Usage**:
+
+```
+/check
+```
+
+**Runs**:
+
+1. `npm run test` - All tests must pass
+2. `npm run typecheck` - No TypeScript errors
+3. `npm run lint` - No lint errors
+4. `npm run build` - Build must succeed
+
+### /feature-dev
+
+**Purpose**: Full guided feature development (plugin command).
+
+**Usage**:
+
+```
+/feature-dev:feature-dev <feature description>
+```
+
+**7 Phases**:
+
+1. Discovery - Understand requirements
+2. Codebase Exploration - Find patterns
+3. Clarifying Questions - Resolve ambiguities
+4. Architecture Design - Plan approach
+5. Implementation - Build the feature
+6. Quality Review - Check code quality
+7. Summary - Document what was built
+
+## TDD Workflow
+
+The `tdd-workflow` skill (`.claude/skills/tdd-workflow/SKILL.md`) provides TDD guidance.
+
+### Red-Green-Refactor
+
+1. **RED**: Write failing test first
+2. **GREEN**: Minimal code to pass
+3. **REFACTOR**: Clean up (tests stay green)
+
+### Test Location
+
+Tests go in `tests/unit/` mirroring `src/`:
+
+| Source                      | Test                                    |
+| --------------------------- | --------------------------------------- |
+| `src/hooks/useAuth.ts`      | `tests/unit/hooks/useAuth.test.ts`      |
+| `src/components/Button.tsx` | `tests/unit/components/Button.test.tsx` |
+
+### Test Patterns
+
+See [docs/TESTING.md](TESTING.md) for detailed patterns.
+
+## Typical Workflow
+
+```
+1. /implement Add user authentication
+   → Creates branch, shows TDD instructions
+
+2. /feature-dev:feature-dev Add user authentication
+   → Follow the 7 phases
+   → During Phase 5, apply TDD (tests first)
+
+3. /check
+   → Verify all quality gates pass
+
+4. Commit
+   → Create conventional commit
+```
+
+## File Structure
+
+```
+.claude/
+├── commands/
+│   ├── implement/implement.md   # /implement
+│   └── quality/check.md         # /check
+├── skills/
+│   └── tdd-workflow/SKILL.md    # TDD guidance
+└── settings.local.json          # Permissions
+```
+
+## MCP Server Integration
+
+Use MCP servers instead of WebSearch for documentation. They provide **structured, version-accurate data** directly from source.
+
+### Why MCP over WebSearch?
+
+| Benefit           | Explanation                                            |
+| ----------------- | ------------------------------------------------------ |
+| **Accuracy**      | Fetches from official sources, not outdated blog posts |
+| **Version-aware** | Gets docs for the exact library version in use         |
+| **Structured**    | Returns code snippets, types, examples consistently    |
+| **Faster**        | Direct API calls vs parsing HTML from search results   |
+
+### Shadcn MCP (UI Components)
+
+```
+mcp__shadcn__search_items_in_registries    # Find components
+mcp__shadcn__view_items_in_registries      # View component code
+mcp__shadcn__get_item_examples_from_registries  # Usage examples
+mcp__shadcn__get_add_command_for_items     # CLI add command
+mcp__shadcn__list_items_in_registries      # List all components
+```
+
+### Context7 MCP (All 3rd Party Libraries)
+
+Use for **any npm package**—not just React libraries:
+
+```
+resolve-library-id    # Get library ID (e.g., "react-hook-form")
+get-library-docs      # Fetch documentation
+```
+
+**Common libraries in this project**:
+
+- `react-hook-form` - Form handling
+- `@tanstack/react-query` - Server state
+- `zustand` - Client state
+- `zod` - Validation schemas
+- `@lingui/react` - i18n
+- `msw` - API mocking
+
+### Decision Flow
+
+```
+Need UI component?     → Shadcn MCP
+Need library docs?     → Context7 MCP (any npm package)
+Need general info?     → WebSearch (fallback only)
+```
+
+### Adding Shadcn Components
+
+```bash
+npx shadcn@latest add button           # Single component
+npx shadcn@latest add dialog card input # Multiple components
+```
+
+Components are installed to `src/components/ui/`. Import directly (no barrel exports).

package/templates/src/App.tsx

@@ -0,0 +1,42 @@
+import { useLingui } from '@lingui/react/macro';
+import { lazy, Suspense } from 'react';
+import { Route, Routes } from 'react-router';
+
+import { Header } from '@/components/layout';
+import { SEO } from '@/components/shared';
+import { PageLoading } from '@/components/ui/loading';
+import { SkipLink } from '@/components/ui/visually-hidden';
+import { useThemeEffect } from '@/hooks';
+import { ROUTES } from '@/lib/routes';
+
+// Lazy load pages for code splitting
+// eslint-disable-next-line lingui/no-unlocalized-strings
+const HomePage = lazy(() => import('@/pages/Home').then((m) => ({ default: m.HomePage })));
+// eslint-disable-next-line lingui/no-unlocalized-strings
+const NotFoundPage = lazy(() => import('@/pages/NotFound').then((m) => ({ default: m.NotFoundPage })));
+
+export default function App() {
+  const { t } = useLingui();
+  useThemeEffect();
+
+  return (
+    <div className="bg-background text-foreground min-h-screen">
+      <SEO
+        description={t({
+          message: 'A modern React 19 application with TypeScript and Vite',
+          comment: 'Default site-wide meta description for SEO',
+        })}
+      />
+      <SkipLink />
+      <Header />
+      <main id="main">
+        <Suspense fallback={<PageLoading />}>
+          <Routes>
+            <Route path={ROUTES.HOME} element={<HomePage />} />
+            <Route path={ROUTES.NOT_FOUND} element={<NotFoundPage />} />
+          </Routes>
+        </Suspense>
+      </main>
+    </div>
+  );
+}

package/templates/src/components/layout/Header.tsx

@@ -0,0 +1,19 @@
+import { Trans } from '@lingui/react/macro';
+
+import { LanguageSwitcher, ThemeToggle } from '@/components/shared';
+
+export function Header() {
+  return (
+    <header className="border-border border-b">
+      <div className="container mx-auto flex h-14 items-center justify-between px-4">
+        <h1 className="text-lg font-semibold">
+          <Trans comment="Application name displayed in the header navigation">My App</Trans>
+        </h1>
+        <div className="flex items-center gap-2">
+          <LanguageSwitcher />
+          <ThemeToggle />
+        </div>
+      </div>
+    </header>
+  );
+}

package/templates/src/components/layout/index.ts

@@ -0,0 +1 @@
+export { Header } from './Header';

package/templates/src/components/shared/ErrorBoundary/ErrorBoundary.tsx

@@ -0,0 +1,104 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import { Trans } from '@lingui/react/macro';
+
+import { SENTRY_CONFIG } from '@/lib/config';
+
+interface Props {
+  children: ReactNode;
+  fallback?: ReactNode;
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+  onReset?: () => void;
+}
+
+interface State {
+  hasError: boolean;
+  error: Error | null;
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error('ErrorBoundary caught an error:', error, errorInfo);
+
+    // Call custom error handler if provided
+    this.props.onError?.(error, errorInfo);
+
+    // Report to Sentry in production (if enabled and configured)
+    if (import.meta.env.PROD && SENTRY_CONFIG.enabled && SENTRY_CONFIG.dsn) {
+      // eslint-disable-next-line lingui/no-unlocalized-strings
+      import('@sentry/react')
+        .then((Sentry) => {
+          Sentry.captureException(error, {
+            extra: { componentStack: errorInfo.componentStack },
+          });
+        })
+        .catch(() => {
+          // Sentry failed to load, error already logged above
+        });
+    }
+  }
+
+  /**
+   * Reset the error boundary state
+   */
+  reset = () => {
+    this.props.onReset?.();
+    this.setState({ hasError: false, error: null });
+  };
+
+  render() {
+    if (this.state.hasError) {
+      if (this.props.fallback) {
+        return this.props.fallback;
+      }
+
+      return (
+        <div className="flex min-h-screen items-center justify-center p-4">
+          <div className="text-center">
+            <h1 className="text-destructive text-2xl font-bold">
+              <Trans comment="Error boundary - main error heading">Something went wrong</Trans>
+            </h1>
+            <p className="text-muted-foreground mt-2">
+              <Trans comment="Error boundary - error explanation">
+                We're sorry, but something unexpected happened.
+              </Trans>
+            </p>
+            {import.meta.env.DEV && this.state.error && (
+              <details className="bg-muted mt-4 rounded-md p-4 text-left">
+                <summary className="cursor-pointer font-medium">
+                  <Trans comment="Error boundary - debug section heading">Error details</Trans>
+                </summary>
+                <pre className="mt-2 overflow-auto text-sm">{this.state.error.message}</pre>
+                <pre className="mt-1 overflow-auto text-xs opacity-75">{this.state.error.stack}</pre>
+              </details>
+            )}
+            <div className="mt-6 flex justify-center gap-3">
+              <button
+                onClick={this.reset}
+                className="bg-secondary text-secondary-foreground rounded px-4 py-2 transition-colors hover:opacity-90"
+              >
+                <Trans comment="Error boundary - try again button">Try Again</Trans>
+              </button>
+              <button
+                onClick={() => window.location.reload()}
+                className="bg-primary text-primary-foreground rounded px-4 py-2 transition-colors hover:opacity-90"
+              >
+                <Trans comment="Error boundary - refresh button">Refresh Page</Trans>
+              </button>
+            </div>
+          </div>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}

package/templates/src/components/shared/ErrorBoundary/index.ts

@@ -0,0 +1 @@
+export { ErrorBoundary } from './ErrorBoundary';

package/templates/src/components/shared/LanguageSwitcher/LanguageSwitcher.tsx

@@ -0,0 +1,45 @@
+import { useLingui } from '@lingui/react/macro';
+import { Languages } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { useLanguage } from '@/hooks/useLanguage';
+import { LOCALE_LABELS } from '@/i18n';
+
+export function LanguageSwitcher() {
+  const { t } = useLingui();
+  const { currentLocale, changeLanguage, supportedLocales } = useLanguage();
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button
+          variant="ghost"
+          size="icon"
+          aria-label={t({
+            message: 'Change language',
+            comment: 'Accessibility label for the language selector dropdown button',
+          })}
+        >
+          <Languages className="size-5" />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end">
+        {supportedLocales.map((locale) => (
+          <DropdownMenuItem
+            key={locale}
+            onClick={() => changeLanguage(locale)}
+            className={currentLocale === locale ? 'bg-accent' : ''}
+          >
+            {LOCALE_LABELS[locale].native}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/templates/src/components/shared/LanguageSwitcher/index.ts

@@ -0,0 +1 @@
+export { LanguageSwitcher } from './LanguageSwitcher';