@react-spa-scaffold/mcp 2.2.0 → 2.3.0

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

package/templates/docs/DEPLOYMENT.md

@@ -0,0 +1,268 @@
+# Deployment Guide
+
+Automated deployment to Netlify with GitHub Actions for preview and production environments.
+
+---
+
+## Overview
+
+```
+PR Created/Updated → GitHub Actions → Build → Netlify Preview
+                                               ↓
+                               Comment with preview URL on PR
+
+Push to main → GitHub Actions → Build → Netlify Production
+```
+
+**Features:**
+
+- Automatic preview deploys for pull requests
+- Production deploys on push to main/master
+- PR comments with preview URLs
+- Manual deploy via workflow_dispatch
+- Security headers pre-configured
+
+**Note:** Enable branch protection rules to require CI to pass before merging to main.
+
+---
+
+## Netlify Setup
+
+### 1. Create Netlify Site
+
+1. Go to [app.netlify.com](https://app.netlify.com) and sign in
+2. Click "Add new site" → "Import an existing project"
+3. Connect your GitHub repository
+4. Configure build settings (auto-detected from `netlify.toml`):
+   - Build command: `npm run build`
+   - Publish directory: `dist`
+5. Click "Deploy site"
+
+### 2. Get API Credentials
+
+1. **Personal Access Token** (for `NETLIFY_AUTH_TOKEN`):
+   - User Settings → Applications → Personal access tokens
+   - Click "New access token", name it, and copy the token
+
+2. **Site ID** (for `NETLIFY_SITE_ID`):
+   - Site Settings → General → Site details → Site ID
+
+### 3. Add GitHub Secrets
+
+Go to your repository → Settings → Secrets and variables → Actions → New repository secret:
+
+| Secret Name          | Description                      |
+| -------------------- | -------------------------------- |
+| `NETLIFY_AUTH_TOKEN` | Personal access token from above |
+| `NETLIFY_SITE_ID`    | Site ID from above               |
+
+---
+
+## Environment Variables
+
+### Build-Time Variables
+
+Set in Netlify Dashboard → Site Settings → Environment variables:
+
+| Variable                     | Required      | Description           |
+| ---------------------------- | ------------- | --------------------- |
+| `VITE_CLERK_PUBLISHABLE_KEY` | If using auth | Clerk publishable key |
+| `VITE_SUPABASE_DATABASE_URL` | If using db   | Supabase project URL  |
+| `VITE_SUPABASE_ANON_KEY`     | If using db   | Supabase anon key     |
+
+### Context-Specific Variables
+
+Use Netlify CLI to set variables for specific contexts:
+
+```bash
+# Set for all contexts
+netlify env:set VAR_NAME value
+
+# Set for production only
+netlify env:set VAR_NAME value --context production
+
+# Set for deploy previews only
+netlify env:set VAR_NAME value --context deploy-preview
+```
+
+---
+
+## Supabase Integration
+
+If using the database feature, connect Supabase to Netlify for automatic environment variable sync.
+
+### Extension Setup
+
+1. **Netlify Dashboard** → Extensions → Search "Supabase" → Install
+2. **Project Settings** → General → Supabase → Connect
+3. Authorize with Supabase and select your project
+4. For Vite projects:
+   - Framework: Select "Other"
+   - Environment variable prefix: Enter `VITE_`
+
+### Auto-Configured Variables
+
+After connecting, these are automatically injected:
+
+| Variable                     | Description                              |
+| ---------------------------- | ---------------------------------------- |
+| `VITE_SUPABASE_DATABASE_URL` | Project URL                              |
+| `VITE_SUPABASE_ANON_KEY`     | Client API key                           |
+| `SUPABASE_SERVICE_ROLE_KEY`  | Server-side only (not exposed to client) |
+
+### Local Development
+
+Run `netlify dev` to inject Supabase variables locally:
+
+```bash
+npm install -g netlify-cli
+netlify login
+netlify link  # Link to your Netlify site
+netlify dev   # Starts dev server with injected env vars
+```
+
+---
+
+## Preview Deploys
+
+Every pull request automatically gets a preview deployment:
+
+1. Open a PR against main/master
+2. GitHub Actions builds and deploys to Netlify
+3. Bot comments on PR with preview URL
+4. Preview updates on each push to the PR
+5. Preview is deleted when PR is closed
+
+### Preview URL Pattern
+
+- PR previews: `https://pr-{number}--{site-name}.netlify.app`
+- Branch deploys: `https://{branch}--{site-name}.netlify.app`
+
+---
+
+## Production Deploys
+
+Pushing to main/master triggers production deployment:
+
+1. Deploy workflow builds the app
+2. Deploys to production URL: `https://your-site.netlify.app`
+
+**Important:** Enable branch protection rules on main/master to require CI to pass before merging. This ensures production only gets code that passed all checks.
+
+### Manual Deploys
+
+Use workflow_dispatch for manual production deploys:
+
+1. Go to Actions → Deploy → Run workflow
+2. Select branch
+3. Click "Run workflow"
+
+---
+
+## Configuration
+
+### netlify.toml
+
+The `netlify.toml` file in your project root configures:
+
+- **Build settings**: Command and publish directory
+- **Redirects**: SPA fallback to index.html
+- **Headers**: Security headers and caching rules
+- **Context overrides**: Environment-specific settings
+
+### Customizing Headers
+
+Add custom headers in `netlify.toml`:
+
+```toml
+[[headers]]
+  for = "/api/*"
+  [headers.values]
+    Access-Control-Allow-Origin = "https://example.com"
+```
+
+### Redirect Rules
+
+Add redirects before the SPA fallback:
+
+```toml
+[[redirects]]
+  from = "/old-path"
+  to = "/new-path"
+  status = 301
+
+# SPA fallback (keep last)
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200
+```
+
+---
+
+## CLI Commands
+
+```bash
+# Install Netlify CLI
+npm install -g netlify-cli
+
+# Login and link
+netlify login
+netlify link
+
+# Local development with Netlify env vars
+netlify dev
+
+# Manual deploys
+npm run deploy:preview   # Deploy preview build
+npm run deploy:prod      # Deploy to production
+
+# Environment variables
+netlify env:list                    # List all variables
+netlify env:set KEY value           # Set variable
+netlify env:get KEY                 # Get variable value
+netlify env:unset KEY               # Remove variable
+
+# Build locally
+netlify build                       # Test production build
+netlify build --context deploy-preview  # Test preview build
+
+# Check status
+netlify status
+```
+
+---
+
+## Troubleshooting
+
+| Issue                              | Cause                        | Solution                                      |
+| ---------------------------------- | ---------------------------- | --------------------------------------------- |
+| Deploy fails with "Site not found" | Missing `NETLIFY_SITE_ID`    | Add secret to GitHub repository               |
+| Deploy fails with "Unauthorized"   | Invalid `NETLIFY_AUTH_TOKEN` | Regenerate token in Netlify                   |
+| Preview not commenting on PR       | Missing permissions          | Check workflow has `pull-requests: write`     |
+| Env vars undefined in build        | Not set in Netlify           | Add to Netlify Dashboard or use `netlify env` |
+| 404 on page refresh                | SPA fallback not working     | Check `netlify.toml` has `/* -> /index.html`  |
+| Production deploy not triggered    | CI workflow failed           | Check CI workflow status first                |
+
+### Debug Build Locally
+
+Test production build locally:
+
+```bash
+npm run build
+npx serve dist
+
+# Or with Netlify CLI:
+netlify build
+netlify deploy --dir=dist
+```
+
+---
+
+## Resources
+
+- [Netlify Documentation](https://docs.netlify.com/)
+- [Netlify CLI Reference](https://cli.netlify.com/)
+- [File-based Configuration](https://docs.netlify.com/configure-builds/file-based-configuration/)
+- [GitHub Actions for Netlify](https://github.com/nwtgck/actions-netlify)
+- [Netlify Supabase Extension](https://www.netlify.com/integrations/supabase/)

package/templates/docs/E2E_TESTING.md

@@ -10,16 +10,22 @@
 
 ```
 e2e/
+├── auth/
+│   └── auth.setup.ts      # Clerk authentication setup
 ├── fixtures/
 │   └── index.ts           # setupPage, setupCleanPage, test, expect
 ├── tests/                  # Functional E2E tests
 │   ├── home.spec.ts       # Page structure, accessibility
 │   ├── theme.spec.ts      # Theme toggle, persistence
 │   ├── language.spec.ts   # Language switcher
-│   └── navigation.spec.ts # Routing, 404
-└── performance/            # Performance regression tests
-    ├── setup.ts           # Performance test fixture
-    └── home.spec.ts       # Home page performance tests
+│   ├── navigation.spec.ts # Routing, 404
+│   ├── profile.spec.ts    # Unauthenticated profile tests
+│   └── profile.auth.spec.ts # Authenticated profile tests
+├── performance/            # Performance regression tests
+│   ├── setup.ts           # Performance test fixture
+│   └── home.spec.ts       # Home page performance tests
+└── .clerk/                 # Auth state storage (gitignored)
+    └── user.json          # Saved auth state for tests
 ```
 
 ## Imports
@@ -111,8 +117,79 @@ 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
+
+# Authenticated tests (requires credentials)
+npx playwright test --project=authenticated
+```
+
+## Authenticated Testing
+
+Tests requiring authentication use `@clerk/testing` with Playwright. These tests run with a real authenticated user session.
+
+### Setup
+
+1. Install the testing package (already included):
+
+   ```bash
+   npm install -D @clerk/testing
+   ```
+
+2. Set environment variables in `.env`:
+
+   ```bash
+   CLERK_SECRET_KEY=sk_test_xxxxx
+   E2E_CLERK_USER_USERNAME=test@example.com
+   E2E_CLERK_USER_PASSWORD=your-test-password
+   ```
+
+3. Create a test user in your Clerk dashboard with the above credentials.
+
+### File Naming Convention
+
+- `*.spec.ts` - Regular tests (run in `desktop`/`mobile` projects)
+- `*.auth.spec.ts` - Authenticated tests (run in `authenticated` project only)
+
+### Writing Authenticated Tests
+
+```typescript
+// e2e/tests/my-feature.auth.spec.ts
+import { expect, test } from '@playwright/test';
+import { existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const authFile = join(__dirname, '../.clerk/user.json');
+const hasAuthState = existsSync(authFile);
+
+test.describe('My Authenticated Feature', () => {
+  // Skip if auth state doesn't exist
+  test.skip(!hasAuthState, 'Authentication required');
+
+  test.beforeEach(async ({ page }) => {
+    // User is already authenticated via storageState
+    await page.goto('/protected-page');
+  });
+
+  test('can access protected content', async ({ page }) => {
+    await expect(page.getByText('Protected Content')).toBeVisible();
+  });
+});
 ```
 
+### How It Works
+
+1. **Setup project** runs `auth.setup.ts` which:
+   - Calls `clerkSetup()` to get a testing token
+   - Signs in with test credentials
+   - Saves auth state to `e2e/.clerk/user.json`
+
+2. **Authenticated project** uses the saved state:
+   - Loads `storageState` from `user.json`
+   - Tests run with pre-authenticated session
+
+3. **Tests skip gracefully** when credentials aren't configured
+
 ## Mobile Testing
 
 Tests run on both desktop (Chrome) and mobile (Pixel 5) viewports. Use the `isMobile` fixture for device-specific behavior.