@react-spa-scaffold/mcp 2.2.0 → 2.3.0

package/dist/utils/scaffold/generators.js

@@ -30,6 +30,10 @@ export function generateViteEnvDts(featureIds) {
     if (featureIds.includes(FEATURE.AUTH)) {
         envVars.push('  readonly VITE_CLERK_PUBLISHABLE_KEY: string;');
     }
+    if (featureIds.includes(FEATURE.DATABASE)) {
+        envVars.push('  readonly VITE_SUPABASE_DATABASE_URL: string;');
+        envVars.push('  readonly VITE_SUPABASE_ANON_KEY: string;');
+    }
     // Vite built-in env vars (always required for TypeScript)
     envVars.push("  readonly MODE: 'development' | 'production' | 'test';");
     envVars.push('  readonly DEV: boolean;');
@@ -48,21 +52,20 @@ interface ImportMeta {
 }
 /** Generate env.ts content based on selected features. */
 export function generateEnvTs(featureIds) {
-    const schemaFields = [
-        '  VITE_APP_NAME: z.string().min(1).optional(),',
-        '  VITE_APP_URL: z.string().url().optional(),',
-    ];
+    // Check if we need the booleanEnv helper
+    const needsBooleanEnv = featureIds.includes(FEATURE.OBSERVABILITY) || featureIds.includes(FEATURE.PERFORMANCE);
+    const schemaFields = ['  VITE_APP_NAME: z.string().min(1),', '  VITE_APP_URL: z.string().url(),'];
     const envFields = [
         '    VITE_APP_NAME: import.meta.env.VITE_APP_NAME,',
         '    VITE_APP_URL: import.meta.env.VITE_APP_URL,',
     ];
     if (featureIds.includes(FEATURE.API)) {
-        schemaFields.push('  VITE_API_URL: z.string().url().optional(),');
+        schemaFields.push('  VITE_API_URL: z.string().url(),');
         envFields.push('    VITE_API_URL: import.meta.env.VITE_API_URL,');
     }
     if (featureIds.includes(FEATURE.OBSERVABILITY)) {
-        schemaFields.push('  VITE_SENTRY_DSN: z.string().url().optional(),');
-        schemaFields.push('  VITE_SENTRY_ENABLED: z.string().optional(),');
+        schemaFields.push('  VITE_SENTRY_DSN: z.string().url(),');
+        schemaFields.push('  VITE_SENTRY_ENABLED: booleanEnv,');
         envFields.push('    VITE_SENTRY_DSN: import.meta.env.VITE_SENTRY_DSN,');
         envFields.push('    VITE_SENTRY_ENABLED: import.meta.env.VITE_SENTRY_ENABLED,');
     }
@@ -70,20 +73,45 @@ export function generateEnvTs(featureIds) {
         schemaFields.push('  VITE_CLERK_PUBLISHABLE_KEY: z.string().min(1),');
         envFields.push('    VITE_CLERK_PUBLISHABLE_KEY: import.meta.env.VITE_CLERK_PUBLISHABLE_KEY,');
     }
+    if (featureIds.includes(FEATURE.DATABASE)) {
+        schemaFields.push('  VITE_SUPABASE_DATABASE_URL: z.string().url(),');
+        schemaFields.push('  VITE_SUPABASE_ANON_KEY: z.string().min(1),');
+        envFields.push('    VITE_SUPABASE_DATABASE_URL: import.meta.env.VITE_SUPABASE_DATABASE_URL,');
+        envFields.push('    VITE_SUPABASE_ANON_KEY: import.meta.env.VITE_SUPABASE_ANON_KEY,');
+    }
+    if (featureIds.includes(FEATURE.PERFORMANCE)) {
+        schemaFields.push('  VITE_PERF_TEST: booleanEnv,');
+        envFields.push('    VITE_PERF_TEST: import.meta.env.VITE_PERF_TEST,');
+    }
     // Vite built-in env vars (always included)
-    schemaFields.push("  MODE: z.enum(['development', 'production', 'test']).default('development'),");
-    schemaFields.push('  DEV: z.boolean().default(false),');
-    schemaFields.push('  PROD: z.boolean().default(false),');
+    schemaFields.push("  MODE: z.enum(['development', 'production', 'test']),");
+    schemaFields.push('  DEV: z.boolean(),');
+    schemaFields.push('  PROD: z.boolean(),');
     envFields.push('    MODE: import.meta.env.MODE,');
     envFields.push('    DEV: import.meta.env.DEV,');
     envFields.push('    PROD: import.meta.env.PROD,');
+    // Build the booleanEnv helper if needed
+    const booleanEnvHelper = needsBooleanEnv
+        ? `
+/**
+ * Transforms string env var to boolean.
+ * - 'true', '1' → true
+ * - 'false', '0' → false
+ */
+const booleanEnv = z.enum(['true', 'false', '1', '0']).transform((val) => val === 'true' || val === '1');
+
+`
+        : '';
     return `/**
  * Environment variable validation using Zod.
  * Validates at runtime to catch missing/invalid env vars early.
+ *
+ * All env vars are REQUIRED. The MCP scaffold tool strips unused vars
+ * when scaffolding builds without certain features.
  */
 
 import { z } from 'zod';
-
+${booleanEnvHelper}
 const envSchema = z.object({
 ${schemaFields.join('\n')}
 });
@@ -92,7 +120,7 @@ export type Env = z.infer<typeof envSchema>;
 
 /**
  * Validate environment variables and return typed env object.
- * Throws if validation fails in production.
+ * Throws if any required env var is missing or invalid.
  */
 export function validateEnv(): Env {
   const env = {
@@ -102,15 +130,17 @@ ${envFields.join('\n')}
   const result = envSchema.safeParse(env);
 
   if (!result.success) {
-    const errors = result.error.format();
-    console.error('Environment validation failed:', errors);
+    const errors = result.error.flatten();
+    const fieldErrors = Object.entries(errors.fieldErrors)
+      .map(([key, msgs]) => \`\${key}: \${(msgs as string[]).join(', ')}\`)
+      .join('; ');
+    const formErrors = errors.formErrors.join('; ');
+    const allErrors = [fieldErrors, formErrors].filter(Boolean).join('; ');
 
-    if (import.meta.env.PROD) {
-      throw new Error('Invalid environment configuration');
-    }
+    throw new Error(\`Environment validation failed: \${allErrors}\`);
   }
 
-  return result.data
+  return result.data;
 }
 
 /**
@@ -120,16 +150,21 @@ ${envFields.join('\n')}
 export const env = validateEnv();
 `;
 }
-/** Generates routes.ts content. */
-export function generateRoutesTs() {
+/** Generates routes.ts content based on selected features. */
+export function generateRoutesTs(featureIds) {
+    const routes = ["  HOME: '/',"];
+    // Add PROFILE route when database feature is selected
+    if (featureIds.includes(FEATURE.DATABASE)) {
+        routes.push("  PROFILE: '/profile',");
+    }
+    routes.push("  NOT_FOUND: '*',");
     return `/**
  * Typed route constants.
  * Use these instead of hardcoded strings for type-safe navigation.
  */
 
 export const ROUTES = {
-  HOME: '/',
-  NOT_FOUND: '*',
+${routes.join('\n')}
 } as const;
 
 export type AppRoute = (typeof ROUTES)[keyof typeof ROUTES];

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.2.0",
+  "version": "2.3.0",
   "description": "MCP server for scaffolding projects based on react-spa-scaffold template",
   "type": "module",
   "main": "dist/index.js",

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

@@ -96,7 +96,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 +106,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

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

@@ -0,0 +1,59 @@
+name: Deploy
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+  deployments: write
+
+concurrency:
+  group: deploy-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-node-deps
+
+      - name: Build
+        run: npm run build
+
+      - 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' || github.event_name == 'workflow_dispatch'
+        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/CLAUDE.md

@@ -19,6 +19,9 @@ 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
@@ -213,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