@react-spa-scaffold/mcp 2.1.1 → 2.3.0

package/templates/CLAUDE.md

@@ -14,9 +14,14 @@ 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
+npm run db:types         # Generate Supabase TypeScript types
+npm run db:push          # Push database migrations
+npm run db:studio        # Open Supabase Studio
 ```
 
 ## Project Structure
@@ -50,6 +55,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 +179,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
 
@@ -140,10 +216,183 @@ import { render, mockMatchMedia, server } from '@/test';
 
 MSW handlers auto-reset after each test.
 
+## Authentication (Clerk)
+
+When the auth feature is enabled, Clerk authentication is required.
+
+### Setup
+
+1. Create an account at [clerk.com](https://clerk.com)
+2. Get your Publishable Key from the dashboard
+3. Copy `.env.example` to `.env` and set your key:
+   ```
+   VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
+   ```
+
+### Usage
+
+```tsx
+// Protect routes that require authentication
+import { ProtectedRoute } from '@/components/shared';
+
+<Route
+  path="/dashboard"
+  element={
+    <ProtectedRoute>
+      <DashboardPage />
+    </ProtectedRoute>
+  }
+/>;
+```
+
+```tsx
+// Conditional rendering based on auth state
+import { SignedIn, SignedOut, UserButton, SignInButton } from '@clerk/react-router';
+
+<SignedIn>
+  <UserButton />
+</SignedIn>
+<SignedOut>
+  <SignInButton mode="modal">
+    <Button>Sign In</Button>
+  </SignInButton>
+</SignedOut>
+```
+
+### Testing
+
+Clerk is automatically mocked in tests. Use test utilities to control auth state:
+
+```tsx
+import { setMockClerkSignedIn, resetClerkMocks } from '@/test';
+
+beforeEach(() => resetClerkMocks());
+
+it('shows sign-in when not authenticated', () => {
+  setMockClerkSignedIn(false);
+  // ...
+});
+```
+
+## Database (Supabase)
+
+Supabase provides PostgreSQL database with Row Level Security (RLS), integrated with Clerk authentication.
+
+### Setup
+
+1. Create a project at [supabase.com](https://supabase.com)
+2. Configure Clerk as third-party auth provider:
+   - Supabase Dashboard → Authentication → Providers → Third-Party Auth → Add Clerk
+3. Enable Supabase integration in Clerk:
+   - Clerk Dashboard → Integrations → Supabase → Activate
+4. Set environment variables in `.env`:
+   ```
+   VITE_SUPABASE_DATABASE_URL=https://your-project.supabase.co
+   VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+   ```
+
+### Database Commands
+
+```bash
+npm run db:types    # Generate TypeScript types from schema
+npm run db:push     # Push migrations to database
+npm run db:reset    # Reset database (WARNING: destructive)
+npm run db:studio   # Open Supabase Studio
+```
+
+### Usage
+
+```tsx
+import { useSupabase, useSupabaseQuery, useProfile } from '@/hooks';
+
+// Direct client access
+const supabase = useSupabase();
+const { data } = await supabase.from('profiles').select();
+
+// TanStack Query wrapper for automatic caching
+const { data, isLoading } = useSupabaseQuery({
+  table: 'profiles',
+  queryKey: ['current'],
+});
+
+// Convenience hook for current user's profile
+const { profile, isLoading, exists } = useProfile();
+```
+
+### Profile Mutations
+
+```tsx
+import { useUpsertProfile, useUpdateProfile, useDeleteProfile } from '@/hooks';
+
+// Create or update profile (upsert)
+const upsertProfile = useUpsertProfile();
+await upsertProfile.mutateAsync({ id: userId, email: 'user@example.com' });
+
+// Update current user's profile
+const updateProfile = useUpdateProfile();
+await updateProfile.mutateAsync({ full_name: 'John' });
+
+// Delete current user's profile
+const deleteProfile = useDeleteProfile();
+await deleteProfile.mutateAsync();
+```
+
+### Auto-Sync with ProfileSync
+
+```tsx
+import { ProfileSync } from '@/components/shared';
+
+// Add to your app to auto-sync Clerk user data to Supabase
+function App() {
+  return (
+    <>
+      <ProfileSync />
+      <Routes>...</Routes>
+    </>
+  );
+}
+```
+
+### Row Level Security (RLS)
+
+All tables should have RLS enabled. Policies use `auth.uid()` which equals the Clerk user_id:
+
+```sql
+-- Users can only access their own data
+CREATE POLICY "Users can view own profile"
+  ON profiles FOR SELECT TO authenticated
+  USING (id = auth.uid());
+```
+
+### Testing
+
+Supabase context is mocked in tests with state controls:
+
+```tsx
+import { render, setMockSupabaseData, setMockSupabaseError, createProfile, resetSupabaseMocks } from '@/test';
+
+beforeEach(() => resetSupabaseMocks());
+
+it('displays profile data', async () => {
+  setMockSupabaseData([createProfile({ full_name: 'Test User' })]);
+  render(<ProfileCard />);
+  // Assert profile is displayed
+});
+
+it('handles error', async () => {
+  setMockSupabaseError({ message: 'Failed', code: 'ERROR' });
+  render(<ProfileCard />);
+  // Assert error state
+});
+```
+
 ## 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()`)
+3. **Context hooks throw** outside provider (e.g., `useMobileContext()`, `useSupabase()`)
 4. **Barrel exports** in each directory via `index.ts`
 5. **UI components** import directly: `@/components/ui/button` (no barrel)
+6. **Clerk auth required** when auth feature is enabled - set `VITE_CLERK_PUBLISHABLE_KEY` in `.env`
+7. **Supabase requires Clerk** - SupabaseProvider must be inside ClerkProvider
+8. **RLS policies required** - All Supabase tables should have Row Level Security enabled

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/AUTHENTICATION.md

@@ -0,0 +1,325 @@
+# Authentication
+
+Clerk authentication integration with shadcn theming and Supabase token injection.
+For quick-start usage, see [CLAUDE.md](../CLAUDE.md#authentication-clerk).
+
+---
+
+## Why Clerk
+
+This project uses Clerk instead of Supabase Auth for:
+
+- **Production-ready UI** - Pre-built `SignInButton`, `UserButton` components with modal flows
+- **Superior OAuth** - 20+ providers vs ~10, dashboard configuration vs code
+- **Automatic session management** - Cross-tab sync, token refresh handled transparently
+- **Separation of concerns** - Clerk = authentication (who), Supabase = authorization + data (what)
+
+---
+
+## Architecture
+
+```
+ClerkProvider (ClerkThemeProvider wrapper)
+    │
+    ├── useAuth()    → { isLoaded, isSignedIn, userId, getToken }
+    ├── useUser()    → { user: { id, email, fullName, imageUrl } }
+    └── useSession() → { session.getToken() } → JWT Token
+                                                   │
+                                                   ▼
+                                    SupabaseProvider injects token
+                                                   │
+                                                   ▼
+                                    Supabase validates JWT
+                                    auth.uid() = Clerk user_id
+```
+
+**Authentication Flow:**
+
+1. User clicks Sign In → Clerk modal opens
+2. User authenticates (email, OAuth, etc.)
+3. Clerk creates session, `useAuth()` returns `isSignedIn: true`
+4. `useSession().getToken()` provides JWT for Supabase
+5. RLS policies grant access via `auth.uid()`
+
+---
+
+## Setup
+
+### 1. Environment Variable
+
+```bash
+VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
+```
+
+Get from [Clerk Dashboard](https://dashboard.clerk.com) → API Keys.
+
+### 2. Dashboard Setup
+
+1. Create application at [clerk.com](https://clerk.com)
+2. Configure sign-in methods (Email, Google, GitHub, etc.)
+3. **For Supabase**: Integrations → Supabase → Activate (adds `role: authenticated` claim)
+4. Copy Clerk domain → Supabase Dashboard → Authentication → Add Clerk provider
+
+### 3. Provider Hierarchy
+
+```tsx
+// main.tsx - SupabaseProvider MUST be inside ClerkProvider
+<ClerkThemeProvider publishableKey={CLERK_PUBLISHABLE_KEY}>
+  <SupabaseProvider>
+    <App />
+  </SupabaseProvider>
+</ClerkThemeProvider>
+```
+
+---
+
+## File Structure
+
+```
+src/
+├── contexts/
+│   └── clerkContext.tsx          # ClerkThemeProvider with shadcn theme
+├── components/shared/
+│   ├── AccountButton/            # Sign in / User button
+│   ├── ProtectedRoute/           # Auth guard wrapper
+│   └── ProfileSync/              # Auto-sync Clerk → Supabase
+├── test/
+│   └── clerkMock.tsx             # Comprehensive Clerk mocks
+├── mocks/
+│   ├── constants.ts              # Mock user/session constants
+│   └── fixtures/users.ts         # Mock user factories
+└── index.css                     # Includes @clerk/themes/shadcn.css
+```
+
+---
+
+## Theme Configuration
+
+### ClerkThemeProvider
+
+```typescript
+// src/contexts/clerkContext.tsx
+import { ClerkProvider } from '@clerk/react-router';
+import { shadcn } from '@clerk/themes';
+
+const appearance: Appearance = {
+  baseTheme: shadcn,
+  variables: {
+    fontFamily: '"Inter Variable", sans-serif',
+    borderRadius: '0.45rem',
+  },
+  elements: {
+    modalBackdrop: 'backdrop-blur-sm',
+    modalContent: 'sm:max-w-md max-sm:min-h-svh max-sm:min-w-full max-sm:rounded-none',
+    card: 'max-sm:rounded-none max-sm:shadow-none',
+  },
+};
+
+export function ClerkThemeProvider({ children, publishableKey }: Props) {
+  return (
+    <ClerkProvider publishableKey={publishableKey} afterSignOutUrl="/" appearance={appearance}>
+      {children}
+    </ClerkProvider>
+  );
+}
+```
+
+### CSS Import
+
+```css
+/* src/index.css */
+@import '@clerk/themes/shadcn.css';
+```
+
+Enables automatic light/dark mode adaptation with shadcn CSS variables.
+
+---
+
+## Components
+
+| Component            | Location                            | Purpose                                              |
+| -------------------- | ----------------------------------- | ---------------------------------------------------- |
+| `ClerkThemeProvider` | `contexts/clerkContext.tsx`         | Clerk wrapper with shadcn theme                      |
+| `AccountButton`      | `components/shared/AccountButton/`  | Sign-in button (logged out) / UserButton (logged in) |
+| `ProtectedRoute`     | `components/shared/ProtectedRoute/` | Auth guard, redirects to sign-in                     |
+| `ProfileSync`        | `components/shared/ProfileSync/`    | Auto-syncs Clerk user → Supabase profiles            |
+
+### AccountButton
+
+Shows `SignInButton` when logged out, `UserButton` when logged in. Displays skeleton while loading.
+
+### ProtectedRoute
+
+```tsx
+<Route
+  path="/dashboard"
+  element={
+    <ProtectedRoute>
+      <DashboardPage />
+    </ProtectedRoute>
+  }
+/>
+```
+
+Returns `<PageLoading />` while checking auth, `<RedirectToSignIn />` if not authenticated.
+
+### ProfileSync
+
+Invisible component that syncs Clerk user data to Supabase on sign-in:
+
+- `id` → Clerk user ID
+- `email` → Primary email
+- `full_name` → Full name
+- `avatar_url` → Profile image
+
+---
+
+## Hooks Reference
+
+All hooks imported from `@clerk/react-router`:
+
+| Hook           | Key Returns                                                   | Use Case                                     |
+| -------------- | ------------------------------------------------------------- | -------------------------------------------- |
+| `useAuth()`    | `isLoaded`, `isSignedIn`, `userId`, `sessionId`, `getToken()` | Auth state without user details              |
+| `useUser()`    | `isLoaded`, `user`                                            | User profile (id, email, fullName, imageUrl) |
+| `useSession()` | `isLoaded`, `session.getToken()`                              | JWT token for API calls                      |
+| `useClerk()`   | `signOut({ redirectUrl })`                                    | Programmatic sign-out                        |
+
+### User Object Properties
+
+| Property                                 | Type             | Description   |
+| ---------------------------------------- | ---------------- | ------------- |
+| `user.id`                                | `string`         | Clerk user ID |
+| `user.primaryEmailAddress?.emailAddress` | `string`         | Email         |
+| `user.fullName`                          | `string \| null` | Full name     |
+| `user.imageUrl`                          | `string`         | Avatar URL    |
+
+For usage examples, see [CLAUDE.md](../CLAUDE.md#authentication-clerk).
+
+---
+
+## Supabase Integration
+
+Clerk tokens are injected into Supabase for authenticated database access:
+
+```typescript
+// src/contexts/supabaseContext.tsx
+const { session } = useSession();
+
+const supabase = useMemo(
+  () =>
+    createSupabaseClient(async () => {
+      if (!session) return null;
+      return session.getToken(); // Clerk JWT injected
+    }),
+  [session?.id], // Only recreate on sign in/out, not every render
+);
+```
+
+**Key points:**
+
+- JWT includes `sub` (user ID) and `role: authenticated` claims
+- Supabase `auth.uid()` equals Clerk user ID
+- RLS policies enforce user-scoped access
+
+See [SUPABASE_INTEGRATION.md](./SUPABASE_INTEGRATION.md) for full details.
+
+---
+
+## Testing
+
+### Mock Utilities
+
+Import from `@/test`:
+
+| Utility                      | Purpose                                  |
+| ---------------------------- | ---------------------------------------- |
+| `setMockClerkSignedIn(bool)` | Set sign-in status                       |
+| `setMockClerkLoaded(bool)`   | Set loading state                        |
+| `setMockClerkState({ ... })` | Set multiple values                      |
+| `setMockClerkUser({ ... })`  | Customize mock user                      |
+| `resetClerkMocks()`          | Reset to defaults (call in `beforeEach`) |
+
+### Mock Components
+
+| Component          | Test ID               |
+| ------------------ | --------------------- |
+| `SignInButton`     | `sign-in-button`      |
+| `SignUpButton`     | `sign-up-button`      |
+| `UserButton`       | `user-button`         |
+| `RedirectToSignIn` | `redirect-to-sign-in` |
+
+### Mock Constants & Fixtures
+
+```typescript
+// src/mocks/constants.ts
+export const MOCK_USER = {
+  id: 'user_123',
+  email: 'test@example.com',
+  fullName: 'Test User',
+  avatarUrl: 'https://example.com/avatar.jpg',
+};
+export const MOCK_SESSION_ID = 'sess_123';
+export const MOCK_AUTH_TOKEN = 'mock-auth-token';
+```
+
+```typescript
+// src/mocks/fixtures/users.ts
+import { createUser, createUsers } from '@/test';
+
+const user = createUser({ fullName: 'Jane Doe' }); // Single user with overrides
+const users = createUsers(3); // Array of mock users
+```
+
+### E2E Testing
+
+For Playwright tests requiring authentication, use `@clerk/testing`:
+
+```bash
+CLERK_SECRET_KEY=sk_test_xxxxx
+E2E_CLERK_USER_USERNAME=test@example.com
+E2E_CLERK_USER_PASSWORD=your-password
+```
+
+See [E2E_TESTING.md](./E2E_TESTING.md#authenticated-testing) for full details.
+
+---
+
+## Troubleshooting
+
+| Issue                                       | Cause                      | Fix                                                   |
+| ------------------------------------------- | -------------------------- | ----------------------------------------------------- |
+| "Missing VITE_CLERK_PUBLISHABLE_KEY"        | Env var not set            | Add to `.env`, restart dev server                     |
+| UI not matching theme                       | Missing CSS import         | Add `@import '@clerk/themes/shadcn.css'` to index.css |
+| "useAuth must be used within ClerkProvider" | Component outside provider | Check `main.tsx` provider order                       |
+| Modal not opening                           | Missing `mode="modal"`     | Use `<SignInButton mode="modal">`                     |
+| Supabase not getting tokens                 | Wrong provider order       | SupabaseProvider must be inside ClerkProvider         |
+| User data undefined                         | Checking before loaded     | Wait for `isLoaded === true` before accessing user    |
+
+### Debug Auth State
+
+```typescript
+const { isLoaded, isSignedIn, userId } = useAuth();
+console.log({ isLoaded, isSignedIn, userId });
+```
+
+### Debug Token Claims
+
+```typescript
+const { session } = useSession();
+const token = await session?.getToken();
+if (token) {
+  const payload = JSON.parse(atob(token.split('.')[1]));
+  console.log(payload); // { sub: "user_xxx", role: "authenticated", ... }
+}
+```
+
+---
+
+## Resources
+
+- [Clerk Documentation](https://clerk.com/docs)
+- [Clerk React Router Integration](https://clerk.com/docs/references/react-router/overview)
+- [Clerk Supabase Integration](https://clerk.com/docs/integrations/databases/supabase)
+- [Clerk Appearance Customization](https://clerk.com/docs/customization/overview)
+- [SUPABASE_INTEGRATION.md](./SUPABASE_INTEGRATION.md) - Database integration with Clerk tokens