@react-spa-scaffold/mcp 2.2.0 → 2.4.0

package/templates/.env.example

@@ -1,19 +1,17 @@
-# Application
+# ─────────────────────────────────────────────────────────────
+# Application (required)
+# ─────────────────────────────────────────────────────────────
 VITE_APP_NAME="My App"
 VITE_APP_URL=http://localhost:5173
-
-# Optional: Base URL for deployment subdirectory
-# VITE_BASE_URL=/
+VITE_API_URL=https://jsonplaceholder.typicode.com
 
 # ─────────────────────────────────────────────────────────────
-# Sentry Error Tracking (production only)
+# Sentry Error Tracking (required)
 # ─────────────────────────────────────────────────────────────
-# Set to 'false' to disable Sentry entirely (opt-out)
-# Enabled by default when DSN is provided
-# VITE_SENTRY_ENABLED=true
-
 # Runtime DSN for error reporting (client-side, safe to expose)
-# VITE_SENTRY_DSN=https://xxxxx@o123456.ingest.sentry.io/789
+# Get from: https://sentry.io/settings/projects/YOUR_PROJECT/keys/
+VITE_SENTRY_DSN=https://xxxxx@o123456.ingest.sentry.io/789
+VITE_SENTRY_ENABLED=true
 
 # CI/CD secrets for source map upload (set in GitHub Secrets):
 # - SENTRY_AUTH_TOKEN: API token for uploading source maps
@@ -21,7 +19,37 @@ VITE_APP_URL=http://localhost:5173
 # - SENTRY_PROJECT: Sentry project slug
 
 # ─────────────────────────────────────────────────────────────
-# Clerk Authentication
+# Clerk Authentication (required)
 # ─────────────────────────────────────────────────────────────
 # Get your Publishable Key from: https://dashboard.clerk.com/~/api-keys
-VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
+VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
+
+# ─────────────────────────────────────────────────────────────
+# Supabase Database (required)
+# ─────────────────────────────────────────────────────────────
+# Get your Project URL and API Key from:
+# https://supabase.com/dashboard/project/YOUR_PROJECT/settings/api
+#
+# For Netlify deployments, these can be auto-configured via the
+# Netlify Supabase extension: Extensions > Supabase > Connect
+VITE_SUPABASE_DATABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+# ─────────────────────────────────────────────────────────────
+# Performance Testing (required)
+# ─────────────────────────────────────────────────────────────
+VITE_PERF_TEST=false
+
+# Supabase CLI (required for npm run db:types)
+# Project ID is the subdomain from your Supabase URL (e.g., abc123xyz from https://abc123xyz.supabase.co)
+SUPABASE_PROJECT_ID=your-project-id
+
+# ─────────────────────────────────────────────────────────────
+# E2E Testing (optional - for authenticated Playwright tests)
+# ─────────────────────────────────────────────────────────────
+# Create a test user in Clerk and provide credentials here
+# Required for running: npx playwright test --project=authenticated
+# E2E_CLERK_USER_USERNAME=test@example.com
+# E2E_CLERK_USER_PASSWORD=your-test-password
+# CLERK_SECRET_KEY=sk_test_xxxxx
+

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

@@ -20,6 +20,7 @@ jobs:
       - uses: ./.github/actions/setup-node-deps
       - run: npm run lint
       - run: npm run format:check
+      - run: npm run sync:check
 
   typecheck:
     name: Type Check
@@ -41,7 +42,7 @@ jobs:
 
   build:
     name: Build
-    needs: [lint, typecheck]
+    needs: [lint, typecheck, security]
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
@@ -96,7 +97,7 @@ jobs:
             upload-on: failure
           - type: performance
             project: performance
-            command: PERF_TEST=true npx playwright test --project=performance
+            command: PERF_TEST=true PERF_CI=true npx playwright test --project=performance
             report-name: performance-report
             upload-on: always
     steps:
@@ -106,6 +107,9 @@ jobs:
         with:
           name: dist
           path: dist/
+      - name: Rebuild with performance tracking
+        if: matrix.type == 'performance'
+        run: VITE_PERF_TEST=true npm run build
       - name: Get Playwright version
         id: playwright-version
         run: echo "version=$(npm ls @playwright/test --json | jq -r '.dependencies["@playwright/test"].version')" >> $GITHUB_OUTPUT
@@ -131,3 +135,46 @@ jobs:
           name: ${{ matrix.report-name }}
           path: playwright-report/
           retention-days: ${{ matrix.type == 'performance' && 14 || 7 }}
+
+  deploy:
+    name: Deploy
+    needs: [build, test, test-e2e]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pull-requests: write
+      deployments: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: dist
+          path: dist/
+
+      - name: Deploy Preview
+        if: github.event_name == 'pull_request'
+        uses: nwtgck/actions-netlify@v3
+        with:
+          publish-dir: './dist'
+          production-deploy: false
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          deploy-message: 'Preview deploy from PR #${{ github.event.number }}'
+          enable-pull-request-comment: true
+          enable-commit-comment: false
+          overwrites-pull-request-comment: true
+          alias: pr-${{ github.event.number }}
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+
+      - name: Deploy Production
+        if: github.event_name == 'push'
+        uses: nwtgck/actions-netlify@v3
+        with:
+          publish-dir: './dist'
+          production-deploy: true
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          deploy-message: 'Production deploy from ${{ github.sha }}'
+          enable-commit-comment: true
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

package/templates/.github/workflows/deploy.yml

@@ -0,0 +1,46 @@
+name: Deploy (Manual)
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 'Deploy environment'
+        required: true
+        default: 'preview'
+        type: choice
+        options:
+          - preview
+          - production
+
+permissions:
+  contents: read
+  deployments: write
+
+jobs:
+  deploy:
+    name: Deploy (${{ inputs.environment }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-node-deps
+
+      - name: Build
+        run: npm run build
+        env:
+          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+          SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
+          SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
+
+      - name: Deploy
+        uses: nwtgck/actions-netlify@v3
+        with:
+          publish-dir: './dist'
+          production-deploy: ${{ inputs.environment == 'production' }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          deploy-message: 'Manual ${{ inputs.environment }} deploy from ${{ github.sha }}'
+          enable-commit-comment: ${{ inputs.environment == 'production' }}
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

package/templates/CLAUDE.md

@@ -19,6 +19,11 @@ 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
+npm run sync:check       # Check monorepo dependency versions
+npm run sync:fix         # Auto-fix version mismatches
 ```
 
 ## Project Structure
@@ -213,10 +218,184 @@ 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
+9. **Monorepo deps** - Run `npm run sync:check` to detect version mismatches across packages