@react-spa-scaffold/mcp 2.1.1 → 2.2.0

package/templates/docs/ARCHITECTURE.md

@@ -12,6 +12,7 @@ High-level architecture and key decisions. For API details, see [API Reference](
 | 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    |
+| Authentication | Clerk                    | Modal-based auth, shadcn theme integration  |
 | i18n           | Lingui                   | Smaller runtime, compile-time extraction    |
 | Testing        | Vitest + Playwright      | Fast, Vite-native, true cross-browser       |
 | Error Tracking | Sentry                   | Industry standard, lazy-loaded              |
@@ -73,22 +74,21 @@ 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>
+        <ClerkThemeProvider>
+          {/* Clerk - auth inside Router for @clerk/react-router */}
+          <MobileProvider>
+            {/* Viewport - depends on router for SSR */}
+            <ErrorBoundary>
+              <App />
+              <Toaster />
+            </ErrorBoundary>
+          </MobileProvider>
+        </ClerkThemeProvider>
       </BrowserRouter>
     </I18nProvider>
   </QueryProvider>
@@ -99,7 +99,8 @@ Providers wrap the app in this specific 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
+- ClerkThemeProvider inside Router (required by @clerk/react-router declarative mode)
+- MobileProvider inside Clerk for potential SSR viewport detection
 - ErrorBoundary innermost to catch errors in App without breaking providers
 
 ### 2. State Management Separation

package/templates/docs/CODING_STANDARDS.md

@@ -19,6 +19,71 @@ interface User {
 
 See [Architecture Guide](./ARCHITECTURE.md#state-management) for when to use each solution.
 
+### Zustand Best Practices
+
+**Auto-generated selectors**: All stores use `createSelectors` for cleaner access:
+
+```tsx
+// Store definition
+const useStoreBase = create<State>()(/* ... */);
+export const useStore = createSelectors(useStoreBase);
+
+// Component usage - auto-generated selectors
+const count = useStore.use.count();
+const increment = useStore.use.increment();
+```
+
+**Use `useShallow` for multiple values**: Prevents unnecessary re-renders:
+
+```tsx
+import { useShallow } from 'zustand/react/shallow';
+
+// Group state values with useShallow
+const { searchQuery, sortBy } = useStore(
+  useShallow((s) => ({
+    searchQuery: s.searchQuery,
+    sortBy: s.sortBy,
+  })),
+);
+```
+
+**Persist versioning**: Always include version and migrate for persisted stores:
+
+```tsx
+persist(
+  (set, get) => ({
+    /* ... */
+  }),
+  {
+    name: 'store-key',
+    version: 1, // Increment on breaking changes
+    migrate: (persisted, version) => {
+      if (version === 0) {
+        return { ...persisted, newField: 'default' };
+      }
+      return persisted;
+    },
+  },
+);
+```
+
+**Middleware order**: Stack middlewares correctly:
+
+```tsx
+// devtools → persist → subscribeWithSelector → store
+create<State>()(
+  devtools(
+    persist(
+      subscribeWithSelector((set, get) => ({
+        /* ... */
+      })),
+      { name: 'key' },
+    ),
+    { name: 'StoreName', enabled: process.env.NODE_ENV === 'development' },
+  ),
+);
+```
+
 ### Query Hooks
 
 Extract the fetcher function:

package/templates/docs/E2E_TESTING.md

@@ -11,7 +11,7 @@
 ```
 e2e/
 ├── fixtures/
-│   └── index.ts           # setupPage, clearAppState
+│   └── index.ts           # setupPage, setupCleanPage, test, expect
 ├── tests/                  # Functional E2E tests
 │   ├── home.spec.ts       # Page structure, accessibility
 │   ├── theme.spec.ts      # Theme toggle, persistence
@@ -26,9 +26,7 @@ e2e/
 
 ```typescript
 import { expect, test } from '@playwright/test';
-
-// For tests that need state clearing
-import { setupPage } from '../fixtures';
+import { setupPage, setupCleanPage } from '../fixtures';
 ```
 
 ## Core Patterns
@@ -107,13 +105,59 @@ await page.waitForTimeout(500);
 ## Running Tests
 
 ```bash
-npm run e2e           # Run functional tests
-npm run e2e:ui        # Functional tests with interactive UI
+npm run e2e           # Run desktop tests
+npm run e2e:mobile    # Run mobile tests (Pixel 5 emulation)
+npm run e2e:all       # Run both desktop and mobile
+npm run e2e:ui        # Interactive UI mode
 npm run e2e:perf      # Run performance tests
 npm run e2e:perf:ui   # Performance tests with interactive UI
-npm run e2e:all       # Run all tests (functional + performance)
 ```
 
+## Mobile Testing
+
+Tests run on both desktop (Chrome) and mobile (Pixel 5) viewports. Use the `isMobile` fixture for device-specific behavior.
+
+### Using isMobile Fixture
+
+```typescript
+import { expect, test } from '@playwright/test';
+
+test('theme toggle works on all devices', async ({ page, isMobile }) => {
+  await page.goto('/');
+
+  // Same test logic works on both platforms
+  await page.getByRole('button', { name: /dark mode/i }).click();
+  await expect(page.locator('html')).toHaveClass(/dark/);
+
+  // Add mobile-specific assertions if needed
+  if (isMobile) {
+    // Verify touch-friendly button size, etc.
+  }
+});
+```
+
+### Skip Tests by Platform
+
+```typescript
+test('hover tooltip shows', async ({ page, isMobile }) => {
+  test.skip(isMobile, 'Hover not available on touch devices');
+  // Desktop-only test
+});
+
+test('touch gesture works', async ({ page, isMobile }) => {
+  test.skip(!isMobile, 'Touch gesture only on mobile');
+  // Mobile-only test
+});
+```
+
+### Common Patterns
+
+| Pattern        | Desktop   | Mobile          |
+| -------------- | --------- | --------------- |
+| Viewport width | 1280px    | 393px (Pixel 5) |
+| Touch events   | Click     | Tap             |
+| Hover states   | Supported | Not applicable  |
+
 ## Performance Testing
 
 Performance tests use [react-performance-tracking](https://github.com/mkaczkowski/react-performance-tracking) to measure:
@@ -129,3 +173,4 @@ Performance tests use [react-performance-tracking](https://github.com/mkaczkowsk
 - [ ] No arbitrary timeouts
 - [ ] Tests behavior, not implementation
 - [ ] Uses `setupPage` when testing persistence
+- [ ] Considers mobile viewport when relevant

package/templates/e2e/fixtures/index.ts

@@ -1,10 +1,21 @@
 import type { Page } from '@playwright/test';
 
 /**
- * Navigate to page with clean state (clears localStorage)
+ * Navigate to page with clean state (clears localStorage).
  */
-export async function setupPage(page: Page, path = '/') {
+export async function setupPage(page: Page, path = '/'): Promise<void> {
   await page.goto(path);
   await page.evaluate(() => localStorage.clear());
   await page.reload();
 }
+
+/**
+ * Setup page with completely fresh state (cookies + localStorage).
+ * Use when tests need isolation from previous test state.
+ */
+export async function setupCleanPage(page: Page): Promise<void> {
+  await page.context().clearCookies();
+  await page.goto('/');
+  await page.evaluate(() => localStorage.clear());
+  await page.reload();
+}

package/templates/package.json

@@ -39,11 +39,12 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "e2e": "playwright test --project=functional",
-    "e2e:ui": "playwright test --project=functional --ui",
+    "e2e": "playwright test --project=desktop",
+    "e2e:mobile": "playwright test --project=mobile",
+    "e2e:all": "playwright test --project=desktop --project=mobile",
+    "e2e:ui": "playwright test --ui",
     "e2e:perf": "PERF_TEST=true playwright test --project=performance",
     "e2e:perf:ui": "PERF_TEST=true playwright test --project=performance --ui",
-    "e2e:all": "PERF_TEST=true playwright test",
     "i18n:extract": "lingui extract",
     "prepare": "husky",
     "mcp:build": "npm run build -w @react-spa-scaffold/mcp",
@@ -55,6 +56,8 @@
     "release": "changeset publish"
   },
   "dependencies": {
+    "@clerk/react-router": "^2.3.7",
+    "@clerk/themes": "^2.4.46",
     "@fontsource-variable/inter": "^5.2.5",
     "@hookform/resolvers": "^5.0.1",
     "@lingui/core": "^5.7.0",
@@ -69,6 +72,7 @@
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-hook-form": "^7.58.0",
+    "react-hotkeys-hook": "^5.2.1",
     "react-performance-tracking": "^1.2.1",
     "react-router": "^7.11.0",
     "sonner": "^2.0.7",

package/templates/playwright.config.ts

@@ -17,10 +17,15 @@ export default defineConfig({
   },
   projects: [
     {
-      name: 'functional',
+      name: 'desktop',
       testDir: './e2e/tests',
       use: { ...devices['Desktop Chrome'] },
     },
+    {
+      name: 'mobile',
+      testDir: './e2e/tests',
+      use: { ...devices['Pixel 5'] },
+    },
     {
       name: 'performance',
       testDir: './e2e/performance',

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

@@ -1,6 +1,6 @@
 import { Trans } from '@lingui/react/macro';
 
-import { LanguageSwitcher, ThemeToggle } from '@/components/shared';
+import { AccountButton, LanguageSwitcher, ThemeToggle } from '@/components/shared';
 
 export function Header() {
   return (
@@ -12,6 +12,7 @@ export function Header() {
         <div className="flex items-center gap-2">
           <LanguageSwitcher />
           <ThemeToggle />
+          <AccountButton />
         </div>
       </div>
     </header>

package/templates/src/components/shared/AccountButton/AccountButton.test.tsx

@@ -0,0 +1,30 @@
+import { screen } from '@testing-library/react';
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import { render, setMockSignedIn, setMockLoaded, resetClerkMocks } from '@/test';
+
+import { AccountButton } from './AccountButton';
+
+describe('AccountButton', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+  });
+
+  it('shows skeleton when not loaded', () => {
+    setMockLoaded(false);
+    const { container } = render(<AccountButton />);
+    expect(container.querySelector('.rounded-full')).toBeInTheDocument();
+  });
+
+  it('shows user button when signed in', () => {
+    render(<AccountButton />);
+    expect(screen.getByTestId('user-button')).toBeInTheDocument();
+  });
+
+  it('shows sign in button when signed out', () => {
+    setMockSignedIn(false);
+    render(<AccountButton />);
+    expect(screen.getByTestId('sign-in-button')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /sign in/i })).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,38 @@
+import { SignedIn, SignedOut, SignInButton, useAuth, UserButton } from '@clerk/react-router';
+import { useLingui } from '@lingui/react/macro';
+import { User } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { Skeleton } from '@/components/ui/skeleton';
+import { useTouchSizes } from '@/hooks';
+
+export function AccountButton() {
+  const { t } = useLingui();
+  const { isLoaded } = useAuth();
+  const sizes = useTouchSizes();
+
+  // Show skeleton while Clerk loads to prevent UI flash
+  if (!isLoaded) {
+    return <Skeleton className="size-9 rounded-full" />;
+  }
+
+  return (
+    <>
+      <SignedOut>
+        {/* eslint-disable-next-line lingui/no-unlocalized-strings */}
+        <SignInButton mode="modal">
+          <Button
+            variant="ghost"
+            size={sizes.iconButtonLg}
+            aria-label={t({ message: 'Sign in', comment: 'Sign in button aria label' })}
+          >
+            <User className="size-5" />
+          </Button>
+        </SignInButton>
+      </SignedOut>
+      <SignedIn>
+        <UserButton />
+      </SignedIn>
+    </>
+  );
+}

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

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

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

@@ -52,14 +52,14 @@ describe('ErrorBoundary', () => {
     expect(screen.getByRole('button', { name: /try again/i })).toBeInTheDocument();
   });
 
-  it('shows Refresh Page button', () => {
+  it('shows Reload Page button', () => {
     render(
       <ErrorBoundary>
         <ThrowingComponent />
       </ErrorBoundary>,
     );
 
-    expect(screen.getByRole('button', { name: /refresh page/i })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /reload page/i })).toBeInTheDocument();
   });
 
   it('renders custom fallback when provided', () => {
@@ -103,7 +103,7 @@ describe('ErrorBoundary', () => {
     expect(onReset).toHaveBeenCalledTimes(1);
   });
 
-  it('reloads page when Refresh Page is clicked', () => {
+  it('reloads page when Reload Page is clicked', () => {
     const reloadMock = vi.fn();
     const originalLocation = window.location;
 
@@ -119,7 +119,7 @@ describe('ErrorBoundary', () => {
       </ErrorBoundary>,
     );
 
-    fireEvent.click(screen.getByRole('button', { name: /refresh page/i }));
+    fireEvent.click(screen.getByRole('button', { name: /reload page/i }));
 
     expect(reloadMock).toHaveBeenCalledTimes(1);
 

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

@@ -1,7 +1,10 @@
-import { Component, type ErrorInfo, type ReactNode } from 'react';
 import { Trans } from '@lingui/react/macro';
+import { AlertTriangle, RefreshCw } from 'lucide-react';
+import { Component, type ErrorInfo, type ReactNode } from 'react';
 
-import { SENTRY_CONFIG } from '@/lib/config';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { captureException } from '@/lib/sentry';
 
 interface Props {
   children: ReactNode;
@@ -15,6 +18,48 @@ interface State {
   error: Error | null;
 }
 
+interface ErrorFallbackUIProps {
+  error: Error | null;
+  onRetry: () => void;
+  onReload: () => void;
+}
+
+function ErrorFallbackUI({ error, onRetry, onReload }: ErrorFallbackUIProps) {
+  return (
+    <div className="flex min-h-screen items-center justify-center p-4">
+      <Card className="max-w-md">
+        <CardHeader>
+          <div className="flex items-center gap-2">
+            <AlertTriangle className="text-destructive size-5" />
+            <CardTitle>
+              <Trans>Something went wrong</Trans>
+            </CardTitle>
+          </div>
+          <CardDescription>
+            <Trans>An unexpected error occurred. You can try again or reload the page.</Trans>
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          {error && (
+            <div className="bg-muted rounded-md p-3">
+              <p className="text-muted-foreground font-mono text-xs break-all">{error.message}</p>
+            </div>
+          )}
+          <div className="flex gap-2">
+            <Button onClick={onRetry} variant="default">
+              <Trans>Try Again</Trans>
+            </Button>
+            <Button onClick={onReload} variant="outline">
+              <RefreshCw className="mr-2 size-4" />
+              <Trans>Reload Page</Trans>
+            </Button>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
 export class ErrorBoundary extends Component<Props, State> {
   constructor(props: Props) {
     super(props);
@@ -28,22 +73,11 @@ export class ErrorBoundary extends Component<Props, State> {
   componentDidCatch(error: Error, errorInfo: ErrorInfo) {
     console.error('ErrorBoundary caught an error:', error, errorInfo);
 
+    // Report error to Sentry with component stack
+    captureException(error, { componentStack: errorInfo.componentStack ?? undefined });
+
     // 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
-        });
-    }
   }
 
   /**
@@ -54,49 +88,17 @@ export class ErrorBoundary extends Component<Props, State> {
     this.setState({ hasError: false, error: null });
   };
 
+  handleReload = () => {
+    window.location.reload();
+  };
+
   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 <ErrorFallbackUI error={this.state.error} onRetry={this.reset} onReload={this.handleReload} />;
     }
 
     return this.props.children;

package/templates/src/components/shared/ProtectedRoute/ProtectedRoute.test.tsx

@@ -0,0 +1,43 @@
+import { screen } from '@testing-library/react';
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import { render, setMockSignedIn, setMockLoaded, resetClerkMocks } from '@/test';
+
+import { ProtectedRoute } from './ProtectedRoute';
+
+describe('ProtectedRoute', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+  });
+
+  it('renders children when signed in', () => {
+    render(
+      <ProtectedRoute>
+        <div>Protected Content</div>
+      </ProtectedRoute>,
+    );
+    expect(screen.getByText('Protected Content')).toBeInTheDocument();
+  });
+
+  it('shows loading when auth is not loaded', () => {
+    setMockLoaded(false);
+    const { container } = render(
+      <ProtectedRoute>
+        <div>Protected Content</div>
+      </ProtectedRoute>,
+    );
+    expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
+    expect(container.querySelector('.animate-spin')).toBeInTheDocument();
+  });
+
+  it('redirects when not signed in', () => {
+    setMockSignedIn(false);
+    render(
+      <ProtectedRoute>
+        <div>Protected Content</div>
+      </ProtectedRoute>,
+    );
+    expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
+    expect(screen.getByTestId('redirect-to-sign-in')).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,35 @@
+import { RedirectToSignIn, useAuth } from '@clerk/react-router';
+import type { ReactNode } from 'react';
+
+import { PageLoading } from '@/components/ui/loading';
+
+interface ProtectedRouteProps {
+  children: ReactNode;
+}
+
+/**
+ * Wraps routes that require authentication.
+ * Shows loading state while auth loads, redirects to sign-in if not authenticated.
+ *
+ * @example
+ * ```tsx
+ * <Route path="/dashboard" element={
+ *   <ProtectedRoute>
+ *     <DashboardPage />
+ *   </ProtectedRoute>
+ * } />
+ * ```
+ */
+export function ProtectedRoute({ children }: ProtectedRouteProps) {
+  const { isLoaded, isSignedIn } = useAuth();
+
+  if (!isLoaded) {
+    return <PageLoading />;
+  }
+
+  if (!isSignedIn) {
+    return <RedirectToSignIn />;
+  }
+
+  return <>{children}</>;
+}

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

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

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

@@ -1,5 +1,7 @@
-export { ThemeToggle } from './ThemeToggle';
+export { AccountButton } from './AccountButton';
 export { ErrorBoundary } from './ErrorBoundary';
-export { SEO } from './SEO';
 export { LanguageSwitcher } from './LanguageSwitcher';
+export { ProtectedRoute } from './ProtectedRoute';
 export { RegisterForm } from './RegisterForm';
+export { SEO } from './SEO';
+export { ThemeToggle } from './ThemeToggle';