@react-spa-scaffold/mcp 2.1.1 → 2.3.0

package/templates/docs/CODING_STANDARDS.md

@@ -19,6 +19,71 @@ interface User {
 
 See [Architecture Guide](./ARCHITECTURE.md#state-management) for when to use each solution.
 
+### Zustand Best Practices
+
+**Auto-generated selectors**: All stores use `createSelectors` for cleaner access:
+
+```tsx
+// Store definition
+const useStoreBase = create<State>()(/* ... */);
+export const useStore = createSelectors(useStoreBase);
+
+// Component usage - auto-generated selectors
+const count = useStore.use.count();
+const increment = useStore.use.increment();
+```
+
+**Use `useShallow` for multiple values**: Prevents unnecessary re-renders:
+
+```tsx
+import { useShallow } from 'zustand/react/shallow';
+
+// Group state values with useShallow
+const { searchQuery, sortBy } = useStore(
+  useShallow((s) => ({
+    searchQuery: s.searchQuery,
+    sortBy: s.sortBy,
+  })),
+);
+```
+
+**Persist versioning**: Always include version and migrate for persisted stores:
+
+```tsx
+persist(
+  (set, get) => ({
+    /* ... */
+  }),
+  {
+    name: 'store-key',
+    version: 1, // Increment on breaking changes
+    migrate: (persisted, version) => {
+      if (version === 0) {
+        return { ...persisted, newField: 'default' };
+      }
+      return persisted;
+    },
+  },
+);
+```
+
+**Middleware order**: Stack middlewares correctly:
+
+```tsx
+// devtools → persist → subscribeWithSelector → store
+create<State>()(
+  devtools(
+    persist(
+      subscribeWithSelector((set, get) => ({
+        /* ... */
+      })),
+      { name: 'key' },
+    ),
+    { name: 'StoreName', enabled: process.env.NODE_ENV === 'development' },
+  ),
+);
+```
+
 ### Query Hooks
 
 Extract the fetcher function:

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,25 +10,29 @@
 
 ```
 e2e/
+├── auth/
+│   └── auth.setup.ts      # Clerk authentication setup
 ├── fixtures/
-│   └── index.ts           # setupPage, clearAppState
+│   └── 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
 
 ```typescript
 import { expect, test } from '@playwright/test';
-
-// For tests that need state clearing
-import { setupPage } from '../fixtures';
+import { setupPage, setupCleanPage } from '../fixtures';
 ```
 
 ## Core Patterns
@@ -107,13 +111,130 @@ await page.waitForTimeout(500);
 ## Running Tests
 
 ```bash
-npm run e2e           # Run functional tests
-npm run e2e:ui        # Functional tests with interactive UI
+npm run e2e           # Run desktop tests
+npm run e2e:mobile    # Run mobile tests (Pixel 5 emulation)
+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
-npm run e2e:all       # Run all tests (functional + performance)
+
+# 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.
+
+### Using isMobile Fixture
+
+```typescript
+import { expect, test } from '@playwright/test';
+
+test('theme toggle works on all devices', async ({ page, isMobile }) => {
+  await page.goto('/');
+
+  // Same test logic works on both platforms
+  await page.getByRole('button', { name: /dark mode/i }).click();
+  await expect(page.locator('html')).toHaveClass(/dark/);
+
+  // Add mobile-specific assertions if needed
+  if (isMobile) {
+    // Verify touch-friendly button size, etc.
+  }
+});
+```
+
+### Skip Tests by Platform
+
+```typescript
+test('hover tooltip shows', async ({ page, isMobile }) => {
+  test.skip(isMobile, 'Hover not available on touch devices');
+  // Desktop-only test
+});
+
+test('touch gesture works', async ({ page, isMobile }) => {
+  test.skip(!isMobile, 'Touch gesture only on mobile');
+  // Mobile-only test
+});
+```
+
+### Common Patterns
+
+| Pattern        | Desktop   | Mobile          |
+| -------------- | --------- | --------------- |
+| Viewport width | 1280px    | 393px (Pixel 5) |
+| Touch events   | Click     | Tap             |
+| Hover states   | Supported | Not applicable  |
+
 ## Performance Testing
 
 Performance tests use [react-performance-tracking](https://github.com/mkaczkowski/react-performance-tracking) to measure:
@@ -129,3 +250,4 @@ Performance tests use [react-performance-tracking](https://github.com/mkaczkowsk
 - [ ] No arbitrary timeouts
 - [ ] Tests behavior, not implementation
 - [ ] Uses `setupPage` when testing persistence
+- [ ] Considers mobile viewport when relevant