@react-spa-scaffold/mcp 2.1.1 → 2.3.0

package/templates/e2e/tests/profile.auth.spec.ts

@@ -0,0 +1,103 @@
+import { expect, test } from '@playwright/test';
+
+import { ASYNC_CONTENT_TIMEOUT } from '../fixtures';
+
+// Check if auth credentials are configured
+const hasAuthCredentials = !!(
+  process.env.CLERK_SECRET_KEY &&
+  process.env.E2E_CLERK_USER_USERNAME &&
+  process.env.E2E_CLERK_USER_PASSWORD
+);
+
+/**
+ * Authenticated Profile Page E2E Tests
+ *
+ * These tests run with an authenticated user (from auth.setup.ts).
+ * They test the full profile CRUD flow with Supabase integration.
+ *
+ * Required environment variables:
+ * - E2E_CLERK_USER_USERNAME: Test user email
+ * - E2E_CLERK_USER_PASSWORD: Test user password
+ * - CLERK_SECRET_KEY: Clerk secret key for testing
+ *
+ * @see https://clerk.com/docs/testing/playwright
+ */
+test.describe('Authenticated Profile Tests', () => {
+  // Skip all tests if auth credentials aren't configured
+  test.skip(
+    !hasAuthCredentials,
+    'Auth credentials required (CLERK_SECRET_KEY, E2E_CLERK_USER_USERNAME, E2E_CLERK_USER_PASSWORD)',
+  );
+
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/profile');
+    // Wait for profile content to load (semantic selector instead of CSS class)
+    await expect(page.getByText('Full Name')).toBeVisible({ timeout: ASYNC_CONTENT_TIMEOUT });
+  });
+
+  test('displays profile card with user info', async ({ page }) => {
+    await expect(page.getByText('Your Profile')).toBeVisible();
+    await expect(page.getByText('Manage your profile information stored in Supabase')).toBeVisible();
+  });
+
+  test('shows user email in profile', async ({ page }) => {
+    const email = process.env.E2E_CLERK_USER_USERNAME;
+    if (email) {
+      await expect(page.getByText(email)).toBeVisible();
+    }
+  });
+
+  test('can enter edit mode for name', async ({ page }) => {
+    await page.getByRole('button', { name: /edit/i }).click();
+
+    // Input field should appear
+    await expect(page.getByRole('textbox')).toBeVisible();
+
+    // Save and Cancel buttons should be visible
+    await expect(page.getByRole('button', { name: /save/i })).toBeVisible();
+    await expect(page.getByRole('button', { name: /cancel/i })).toBeVisible();
+  });
+
+  test('can cancel edit without saving', async ({ page }) => {
+    // Enter edit mode
+    await page.getByRole('button', { name: /edit/i }).click();
+
+    // Type a new name
+    const input = page.getByRole('textbox');
+    await input.clear();
+    await input.fill('Temporary Name');
+
+    // Cancel
+    await page.getByRole('button', { name: /cancel/i }).click();
+
+    // Should exit edit mode (input gone, edit button back)
+    await expect(input).not.toBeVisible();
+    await expect(page.getByRole('button', { name: /edit/i })).toBeVisible();
+  });
+
+  test('can update profile name', async ({ page }) => {
+    // Enter edit mode
+    await page.getByRole('button', { name: /edit/i }).click();
+
+    // Generate unique name with timestamp
+    const newName = `E2E Test User ${Date.now()}`;
+
+    // Update name
+    const input = page.getByRole('textbox');
+    await input.clear();
+    await input.fill(newName);
+
+    // Save
+    await page.getByRole('button', { name: /save/i }).click();
+
+    // Wait for save to complete (exit edit mode)
+    await expect(page.getByRole('button', { name: /edit/i })).toBeVisible({ timeout: ASYNC_CONTENT_TIMEOUT });
+
+    // Verify name is displayed
+    await expect(page.getByText(newName)).toBeVisible();
+  });
+
+  test('Full Name label is present', async ({ page }) => {
+    await expect(page.getByText('Full Name')).toBeVisible();
+  });
+});

package/templates/e2e/tests/profile.spec.ts

@@ -0,0 +1,64 @@
+import { expect, test } from '@playwright/test';
+
+/**
+ * Profile Page E2E Tests
+ *
+ * Note: These tests require a valid Clerk configuration to run.
+ * Without VITE_CLERK_PUBLISHABLE_KEY, the app may show an error page.
+ *
+ * For authenticated testing, see @clerk/testing package documentation.
+ * @see https://clerk.com/docs/testing/playwright
+ */
+
+test.describe('Profile Page', () => {
+  test.beforeEach(async ({ page }) => {
+    // Check if the app loads (Clerk needs to be configured)
+    await page.goto('/');
+
+    // Wait for app to be ready (header should be visible if Clerk is configured)
+    const header = page.getByRole('banner');
+    const isAppReady = await header.isVisible({ timeout: 5000 }).catch(() => false);
+
+    if (!isAppReady) {
+      test.skip(true, 'App not ready - Clerk may not be configured');
+    }
+  });
+
+  test('protected route blocks unauthenticated access', async ({ page }) => {
+    await page.goto('/profile');
+
+    // Wait for Clerk to process the route
+    await page.waitForTimeout(3000);
+
+    // Profile content should NOT be visible without authentication
+    const profileCard = page.getByText('Your Profile');
+    const isVisible = await profileCard.isVisible().catch(() => false);
+
+    // Should either redirect or show sign-in UI, but NOT show profile
+    expect(isVisible).toBe(false);
+  });
+
+  test('profile link only visible when authenticated', async ({ page }) => {
+    await page.goto('/');
+
+    // Wait for Clerk to initialize
+    await page.waitForTimeout(2000);
+
+    // Check for Profile link/button in header
+    // This is wrapped in <SignedIn>, so it should only appear for authenticated users
+    const profileButton = page.getByRole('button', { name: /profile/i });
+    const profileLink = page.getByRole('link', { name: /profile/i });
+
+    const buttonVisible = await profileButton.isVisible().catch(() => false);
+    const linkVisible = await profileLink.isVisible().catch(() => false);
+
+    // Without authentication, neither should be visible
+    // (unless user happens to be authenticated, which is also valid)
+    expect(buttonVisible || linkVisible).toBe(false);
+  });
+});
+
+/**
+ * @see profile.auth.spec.ts for authenticated profile tests (edit, update, etc.)
+ * @see https://clerk.com/docs/testing/playwright
+ */

package/templates/e2e/tests/register-form.spec.ts

@@ -0,0 +1,38 @@
+import { expect, test } from '@playwright/test';
+
+test.describe('Registration Form', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/');
+  });
+
+  test('displays registration form with all fields', async ({ page }) => {
+    await expect(page.getByLabel(/username/i)).toBeVisible();
+    await expect(page.getByLabel(/email/i)).toBeVisible();
+    await expect(page.getByLabel('Password', { exact: true })).toBeVisible();
+    await expect(page.getByLabel(/confirm password/i)).toBeVisible();
+    await expect(page.getByRole('button', { name: /create account/i })).toBeVisible();
+  });
+
+  test('shows validation errors for empty submission', async ({ page }) => {
+    await page.getByRole('button', { name: /create account/i }).click();
+
+    await expect(page.getByText(/username must be at least/i)).toBeVisible();
+    await expect(page.getByText(/valid email address/i)).toBeVisible();
+    await expect(page.getByText(/password must be at least/i)).toBeVisible();
+  });
+
+  test('validates password requirements', async ({ page }) => {
+    await page.getByLabel('Password', { exact: true }).fill('weak');
+    await page.getByRole('button', { name: /create account/i }).click();
+
+    await expect(page.getByText(/password must be at least 8 characters/i)).toBeVisible();
+  });
+
+  test('validates password confirmation match', async ({ page }) => {
+    await page.getByLabel('Password', { exact: true }).fill('StrongPass1');
+    await page.getByLabel(/confirm password/i).fill('DifferentPass1');
+    await page.getByRole('button', { name: /create account/i }).click();
+
+    await expect(page.getByText(/passwords don't match/i)).toBeVisible();
+  });
+});

package/templates/gitignore

@@ -23,10 +23,15 @@ coverage/
 playwright-report/
 test-results/
 playwright/.cache/
+e2e/.clerk/*
+!e2e/.clerk/.gitkeep
 
 # i18n compiled catalogs (generated by Vite plugin during build)
 src/locales/*.mjs
 
+# Supabase
+supabase/.temp/
+
 # Misc
 tmp
 *.log

package/templates/package.json

@@ -39,12 +39,17 @@
     "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",
+    "db:types": "dotenv -- supabase gen types typescript --project-id $SUPABASE_PROJECT_ID > src/types/supabase.ts",
+    "db:push": "supabase db push",
+    "db:reset": "supabase db reset",
+    "db:studio": "supabase studio",
     "prepare": "husky",
     "mcp:build": "npm run build -w @react-spa-scaffold/mcp",
     "mcp:dev": "npm run dev -w @react-spa-scaffold/mcp",
@@ -55,12 +60,15 @@
     "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",
     "@lingui/react": "^5.7.0",
     "@radix-ui/react-slot": "^1.2.3",
     "@sentry/react": "^10.32.1",
+    "@supabase/supabase-js": "^2.89.0",
     "@tanstack/react-query": "^5.90.14",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -69,6 +77,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",
@@ -80,6 +89,7 @@
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.29.8",
+    "@clerk/testing": "^1.13.26",
     "@commitlint/config-conventional": "^20.2.0",
     "@eslint/js": "^9.28.0",
     "@lingui/babel-plugin-lingui-macro": "^5.7.0",
@@ -102,6 +112,7 @@
     "babel-plugin-macros": "^3.1.0",
     "chrome-launcher": "^1.2.1",
     "commitlint": "^20.2.0",
+    "dotenv-cli": "^11.0.0",
     "eslint": "^9.28.0",
     "eslint-config-prettier": "^10.1.0",
     "eslint-plugin-lingui": "^0.11.0",
@@ -115,6 +126,7 @@
     "prettier": "^3.5.3",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "shadcn": "^3.6.2",
+    "supabase": "^2.70.5",
     "tailwindcss": "^4.1.17",
     "typescript": "~5.9.0",
     "typescript-eslint": "^8.33.0",

package/templates/playwright.config.ts

@@ -1,5 +1,18 @@
 import { defineConfig, devices } from '@playwright/test';
 
+import { AUTH_STATE_FILE } from './e2e/fixtures';
+
+// CI performance tests use preview server (serves pre-built dist) for faster startup
+// Local dev uses dev server with VITE_PERF_TEST for hot reload
+const isPerfCI = process.env.PERF_CI === 'true';
+const baseURL = isPerfCI ? 'http://localhost:4173' : 'http://localhost:5173';
+
+function getWebServerCommand(): string {
+  if (isPerfCI) return 'npm run preview';
+  if (process.env.PERF_TEST) return 'VITE_PERF_TEST=true npm run dev';
+  return 'npm run dev';
+}
+
 export default defineConfig({
   testDir: './e2e',
   fullyParallel: true,
@@ -8,7 +21,7 @@ export default defineConfig({
   workers: process.env.CI ? 1 : undefined,
   reporter: process.env.CI ? 'github' : [['list'], ['html']],
   use: {
-    baseURL: 'http://localhost:5173',
+    baseURL,
     trace: 'on-first-retry',
     screenshot: 'only-on-failure',
   },
@@ -16,11 +29,33 @@ export default defineConfig({
     timeout: 10000,
   },
   projects: [
+    // Auth setup - runs first to create authenticated state
     {
-      name: 'functional',
+      name: 'setup',
+      testDir: './e2e/auth',
+      testMatch: /.*\.setup\.ts/,
+    },
+    {
+      name: 'desktop',
       testDir: './e2e/tests',
       use: { ...devices['Desktop Chrome'] },
     },
+    {
+      name: 'mobile',
+      testDir: './e2e/tests',
+      use: { ...devices['Pixel 5'] },
+    },
+    // Authenticated tests - depend on setup project
+    {
+      name: 'authenticated',
+      testDir: './e2e/tests',
+      testMatch: /.*\.auth\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        ...devices['Desktop Chrome'],
+        storageState: AUTH_STATE_FILE,
+      },
+    },
     {
       name: 'performance',
       testDir: './e2e/performance',
@@ -34,8 +69,8 @@ export default defineConfig({
     },
   ],
   webServer: {
-    command: process.env.PERF_TEST ? 'VITE_PERF_TEST=true npm run dev' : 'npm run dev',
-    url: 'http://localhost:5173',
+    command: getWebServerCommand(),
+    url: baseURL,
     reuseExistingServer: !process.env.CI,
     timeout: 120000,
   },

package/templates/src/App.tsx

@@ -3,7 +3,7 @@ import { lazy, Suspense } from 'react';
 import { Route, Routes } from 'react-router';
 
 import { Header } from '@/components/layout';
-import { SEO } from '@/components/shared';
+import { ProfileSync, ProtectedRoute, SEO } from '@/components/shared';
 import { PageLoading } from '@/components/ui/loading';
 import { SkipLink } from '@/components/ui/visually-hidden';
 import { useThemeEffect } from '@/hooks';
@@ -14,29 +14,42 @@ import { ROUTES } from '@/lib/routes';
 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 })));
+// eslint-disable-next-line lingui/no-unlocalized-strings
+const ProfilePage = lazy(() => import('@/pages/Profile').then((m) => ({ default: m.ProfilePage })));
 
 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>
+    <>
+      <ProfileSync />
+      <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.PROFILE}
+                element={
+                  <ProtectedRoute>
+                    <ProfilePage />
+                  </ProtectedRoute>
+                }
+              />
+              <Route path={ROUTES.NOT_FOUND} element={<NotFoundPage />} />
+            </Routes>
+          </Suspense>
+        </main>
+      </div>
+    </>
   );
 }

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

@@ -2,7 +2,7 @@ import { screen } from '@testing-library/react';
 import { describe, expect, it } from 'vitest';
 
 import { Header } from '@/components/layout/Header';
-import { render } from '@/test';
+import { render, setMockClerkSignedIn } from '@/test';
 
 describe('Header', () => {
   it('renders the app title', () => {
@@ -30,4 +30,20 @@ describe('Header', () => {
     const header = screen.getByRole('banner');
     expect(header).toBeInTheDocument();
   });
+
+  it('renders sign-in button when user is signed out', () => {
+    setMockClerkSignedIn(false);
+
+    render(<Header />);
+
+    expect(screen.getByTestId('sign-in-button')).toBeInTheDocument();
+  });
+
+  it('renders user button when user is signed in', () => {
+    setMockClerkSignedIn(true);
+
+    render(<Header />);
+
+    expect(screen.getByTestId('user-button')).toBeInTheDocument();
+  });
 });

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

@@ -1,6 +1,10 @@
+import { SignedIn } from '@clerk/react-router';
 import { Trans } from '@lingui/react/macro';
+import { Link } from 'react-router';
 
-import { LanguageSwitcher, ThemeToggle } from '@/components/shared';
+import { AccountButton, LanguageSwitcher, ThemeToggle } from '@/components/shared';
+import { Button } from '@/components/ui/button';
+import { ROUTES } from '@/lib/routes';
 
 export function Header() {
   return (
@@ -10,8 +14,16 @@ export function Header() {
           <Trans comment="Application name displayed in the header navigation">My App</Trans>
         </h1>
         <div className="flex items-center gap-2">
+          <SignedIn>
+            <Button variant="ghost" size="sm" asChild>
+              <Link to={ROUTES.PROFILE}>
+                <Trans comment="Profile navigation link in header">Profile</Trans>
+              </Link>
+            </Button>
+          </SignedIn>
           <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, setMockClerkSignedIn, setMockClerkLoaded, resetClerkMocks } from '@/test';
+
+import { AccountButton } from './AccountButton';
+
+describe('AccountButton', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+  });
+
+  it('shows skeleton when not loaded', () => {
+    setMockClerkLoaded(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', () => {
+    setMockClerkSignedIn(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);