@react-spa-scaffold/mcp 2.1.0 → 2.2.0

package/dist/utils/scaffold/generators.js.map

@@ -1 +1 @@
-{"version":3,"file":"generators.js","sourceRoot":"","sources":["../../../src/utils/scaffold/generators.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generators.js","sourceRoot":"","sources":["../../../src/utils/scaffold/generators.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-spa-scaffold/mcp",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "MCP server for scaffolding projects based on react-spa-scaffold template",
   "type": "module",
   "main": "dist/index.js",

package/templates/.env.example

@@ -19,3 +19,9 @@ VITE_APP_URL=http://localhost:5173
 # - SENTRY_AUTH_TOKEN: API token for uploading source maps
 # - SENTRY_ORG: Sentry organization slug
 # - SENTRY_PROJECT: Sentry project slug
+
+# ─────────────────────────────────────────────────────────────
+# Clerk Authentication
+# ─────────────────────────────────────────────────────────────
+# Get your Publishable Key from: https://dashboard.clerk.com/~/api-keys
+VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY

package/templates/.github/workflows/ci.yml

@@ -84,11 +84,16 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - type: functional
-            project: functional
-            command: npx playwright test --project=functional
+          - type: desktop
+            project: desktop
+            command: npx playwright test --project=desktop
             report-name: playwright-report
             upload-on: failure
+          - type: mobile
+            project: mobile
+            command: npx playwright test --project=mobile
+            report-name: playwright-report-mobile
+            upload-on: failure
           - type: performance
             project: performance
             command: PERF_TEST=true npx playwright test --project=performance

package/templates/CLAUDE.md

@@ -14,7 +14,9 @@ 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 functional E2E tests
+npm run e2e              # Playwright E2E (desktop)
+npm run e2e:mobile       # Playwright E2E (mobile)
+npm run e2e:all          # Playwright E2E (all viewports)
 npm run e2e:perf         # Performance regression tests
 npm run i18n:extract     # Extract translations to .po
 ```
@@ -50,6 +52,76 @@ e2e/               # Playwright tests
 
 See [docs/CODING_STANDARDS.md](docs/CODING_STANDARDS.md) and [docs/COMPONENT_GUIDELINES.md](docs/COMPONENT_GUIDELINES.md).
 
+## Custom Hooks
+
+### State & Storage
+
+```tsx
+import { useLocalStorage } from '@/hooks';
+
+// localStorage with tab sync and updater functions
+const [value, setValue] = useLocalStorage('key', defaultValue);
+setValue((prev) => newValue);
+```
+
+### Form State Sync
+
+```tsx
+import { useSyncedFormData, useSyncedState } from '@/hooks';
+
+// Sync form data when trigger changes (dialog open, ID changes)
+const [formData, setFormData] = useSyncedFormData(sourceData, syncTrigger);
+
+// Sync state but block when actively editing
+const [localValue, setLocalValue] = useSyncedState(externalValue, isEditing);
+```
+
+### Utilities
+
+```tsx
+import { useCopyFeedback, useDebouncedCallback, useKeyboardShortcut, useDocumentTitle } from '@/hooks';
+
+// Copy feedback with auto-reset
+const { isCopied, triggerCopied } = useCopyFeedback(2000);
+
+// Debounced callbacks
+const debouncedSearch = useDebouncedCallback(handleSearch, 300);
+
+// Keyboard shortcuts
+useKeyboardShortcut('mod+s', handleSave, { preventDefault: true });
+
+// Dynamic page titles
+useDocumentTitle('Dashboard');
+```
+
+### Mobile & iOS
+
+```tsx
+import { useIOSViewportReset, useMobileContext, useTouchSizes } from '@/hooks';
+
+// iOS Safari keyboard viewport fix
+const handleBlur = useIOSViewportReset();
+<input onBlur={handleBlur} />;
+
+// Responsive breakpoints
+const { isMobile, isTablet, isDesktop } = useMobileContext();
+
+// Touch-aware sizes (44px on mobile)
+const sizes = useTouchSizes();
+<Button size={sizes.button}>Click</Button>;
+```
+
+## TIMING Constants
+
+Use centralized timing constants for consistent UX:
+
+```tsx
+import { TIMING } from '@/lib/constants';
+
+// TIMING.DEBOUNCE_DELAY = 300ms
+// TIMING.COPY_FEEDBACK_DURATION = 2000ms
+```
+
 ## UI Components (Shadcn/UI)
 
 This project uses **Shadcn/UI** with radix-nova style. Components live in `src/components/ui/`.
@@ -104,6 +176,7 @@ resolve-library-id → get-library-docs
 - `zod` - Schema validation
 - `date-fns` - Date formatting
 - `msw` - Mock service worker setup
+- `@clerk/react-router` - Authentication patterns
 
 ### Decision Flow
 

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);