@react-spa-scaffold/mcp 1.1.0 → 1.1.2

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

@@ -5,8 +5,6 @@ on:
     branches: [main, master]
   pull_request:
     branches: [main, master]
-  release:
-    types: [published]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -76,81 +74,55 @@ jobs:
           path: coverage/
           retention-days: 14
 
-  e2e:
-    name: E2E Tests
-    needs: [lint, typecheck]
+  test-e2e:
+    name: E2E Tests (${{ matrix.type }})
+    needs: [build]
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    continue-on-error: ${{ matrix.type == 'performance' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - type: functional
+            project: functional
+            command: npx playwright test --project=functional
+            report-name: playwright-report
+            upload-on: failure
+          - type: performance
+            project: performance
+            command: PERF_TEST=true npx playwright test --project=performance
+            report-name: performance-report
+            upload-on: always
     steps:
       - uses: actions/checkout@v6
       - uses: ./.github/actions/setup-node-deps
+      - uses: actions/download-artifact@v6
+        with:
+          name: dist
+          path: dist/
+      - name: Get Playwright version
+        id: playwright-version
+        run: echo "version=$(npm ls @playwright/test --json | jq -r '.dependencies["@playwright/test"].version')" >> $GITHUB_OUTPUT
       - name: Cache Playwright browsers
         uses: actions/cache@v5
         id: playwright-cache
         with:
           path: ~/.cache/ms-playwright
-          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}
       - name: Install Playwright browsers
         if: steps.playwright-cache.outputs.cache-hit != 'true'
-        run: npx playwright install chromium --with-deps
-      - name: Install Playwright deps (cached)
+        run: npx playwright install --with-deps chromium
+      - name: Install Playwright deps (when cached)
         if: steps.playwright-cache.outputs.cache-hit == 'true'
         run: npx playwright install-deps chromium
-      - run: npm run e2e
+      - name: Run ${{ matrix.type }} tests
+        run: ${{ matrix.command }}
+        env:
+          CI: true
       - uses: actions/upload-artifact@v6
-        if: failure()
+        if: ${{ matrix.upload-on == 'always' || failure() }}
         with:
-          name: playwright-report
+          name: ${{ matrix.report-name }}
           path: playwright-report/
-          retention-days: 7
-
-  lighthouse:
-    name: Lighthouse CI
-    needs: [build]
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    continue-on-error: true
-    steps:
-      - uses: actions/checkout@v6
-      - uses: ./.github/actions/setup-node-deps
-      - uses: actions/download-artifact@v7
-        with:
-          name: dist
-          path: dist/
-      - name: Run Lighthouse CI
-        uses: treosh/lighthouse-ci-action@v12
-        with:
-          configPath: ./lighthouserc.json
-          uploadArtifacts: true
-          temporaryPublicStorage: true
-      - uses: actions/upload-artifact@v6
-        if: always()
-        with:
-          name: lighthouse-report
-          path: .lighthouseci/
-          retention-days: 14
-
-  publish:
-    name: Publish to npm
-    needs: [build, test]
-    if: github.event_name == 'release'
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - uses: actions/checkout@v6
-      - uses: ./.github/actions/setup-node-deps
-      - name: Configure npm authentication
-        run: echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
-        env:
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-      - name: Publish @react-spa-scaffold/tsconfig
-        run: npm publish -w @react-spa-scaffold/tsconfig --provenance --access public || echo "Package may already exist at this version"
-      - name: Publish @react-spa-scaffold/eslint-config
-        run: npm publish -w @react-spa-scaffold/eslint-config --provenance --access public || echo "Package may already exist at this version"
-      - name: Publish @react-spa-scaffold/prettier-config
-        run: npm publish -w @react-spa-scaffold/prettier-config --provenance --access public || echo "Package may already exist at this version"
-      - name: Publish @react-spa-scaffold/mcp
-        run: npm publish -w @react-spa-scaffold/mcp --provenance --access public || echo "Package may already exist at this version"
+          retention-days: ${{ matrix.type == 'performance' && 14 || 7 }}

package/templates/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - master
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup-node-deps
+
+      - name: Create Release Pull Request or Publish
+        uses: changesets/action@v1
+        with:
+          version: npm run version
+          publish: npm run release
+          commit: 'chore: version packages'
+          title: 'chore: version packages'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/templates/CLAUDE.md

@@ -14,7 +14,8 @@ 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 E2E
+npm run e2e              # Playwright functional E2E tests
+npm run e2e:perf         # Performance regression tests
 npm run i18n:extract     # Extract translations to .po
 ```
 
@@ -32,10 +33,11 @@ src/
 ├── stores/        # Zustand stores
 └── types/         # TypeScript definitions
 
-tests/unit/        # Vitest (mirrors src/)
 e2e/               # Playwright tests
 ```
 
+**Tests**: Co-located with source files (e.g., `foo.tsx` + `foo.test.tsx`)
+
 ## Code Patterns
 
 **Imports**: Always use `@/` path alias
@@ -128,7 +130,7 @@ See [docs/INTERNATIONALIZATION.md](docs/INTERNATIONALIZATION.md) for full detail
 
 See [docs/TESTING.md](docs/TESTING.md) and [docs/E2E_TESTING.md](docs/E2E_TESTING.md).
 
-Tests in `tests/unit/` mirror `src/` structure. 80% coverage required.
+Tests are co-located with source files (e.g., `foo.tsx` + `foo.test.tsx`). 80% coverage required.
 
 ```typescript
 import { describe, it, expect, vi } from 'vitest';

package/templates/docs/ARCHITECTURE.md

@@ -35,7 +35,6 @@ src/
 ├── test/           # Test utilities and providers
 └── types/          # Shared TypeScript definitions
 
-tests/unit/         # Vitest tests (mirrors src/ structure)
 e2e/                # Playwright end-to-end tests
 ```
 

package/templates/docs/COMPONENT_GUIDELINES.md

@@ -298,4 +298,4 @@ Before submitting a component:
 - [ ] Uses `cn()` for className merging
 - [ ] Accessible (roles, aria-labels, keyboard nav)
 - [ ] Barrel export in `index.ts` (except UI primitives)
-- [ ] Test file in `tests/unit/`
+- [ ] Test file co-located (e.g., `Button.test.tsx`)

package/templates/docs/E2E_TESTING.md

@@ -12,11 +12,14 @@
 e2e/
 ├── fixtures/
 │   └── index.ts           # setupPage, clearAppState
-└── tests/
-    ├── home.spec.ts       # Page structure, accessibility
-    ├── theme.spec.ts      # Theme toggle, persistence
-    ├── language.spec.ts   # Language switcher
-    └── navigation.spec.ts # Routing, 404
+├── 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
 ```
 
 ## Imports
@@ -104,10 +107,22 @@ await page.waitForTimeout(500);
 ## Running Tests
 
 ```bash
-npm run e2e        # Run all
-npm run e2e:ui     # Interactive UI
+npm run e2e           # Run functional tests
+npm run e2e:ui        # Functional tests with interactive UI
+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)
 ```
 
+## Performance Testing
+
+Performance tests use [react-performance-tracking](https://github.com/mkaczkowski/react-performance-tracking) to measure:
+
+- React Profiler metrics (render duration, re-renders)
+- Lighthouse audits (performance, accessibility)
+- Core Web Vitals (LCP, INP, CLS)
+- FPS monitoring (Chromium only)
+
 ## Checklist
 
 - [ ] Uses accessible selectors

package/templates/docs/TESTING.md

@@ -4,19 +4,7 @@
 
 - **Framework**: Vitest + React Testing Library
 - **Coverage threshold**: 80% (lines, branches, functions, statements)
-- **Test location**: `tests/unit/` mirroring `src/` structure
-
-## File Structure
-
-```
-tests/unit/
-├── components/     # Component tests
-├── hooks/          # Hook tests
-├── lib/            # Utility function tests
-├── stores/         # Zustand store tests
-├── contexts/       # Context provider tests
-└── i18n/           # Internationalization tests
-```
+- **Test location**: Co-located with source files (e.g., `Button.tsx` + `Button.test.tsx`)
 
 ## Naming Conventions
 
@@ -85,7 +73,7 @@ describe('useMediaQuery', () => {
 
 ### Component Testing
 
-```typescript
+```tsx
 import { screen } from '@testing-library/react';
 import { render } from '@/test';
 

package/templates/docs/WORKFLOW.md

@@ -71,12 +71,12 @@ The `tdd-workflow` skill (`.claude/skills/tdd-workflow/SKILL.md`) provides TDD g
 
 ### Test Location
 
-Tests go in `tests/unit/` mirroring `src/`:
+Tests are co-located with source files:
 
-| Source                      | Test                                    |
-| --------------------------- | --------------------------------------- |
-| `src/hooks/useAuth.ts`      | `tests/unit/hooks/useAuth.test.ts`      |
-| `src/components/Button.tsx` | `tests/unit/components/Button.test.tsx` |
+| Source                      | Test                             |
+| --------------------------- | -------------------------------- |
+| `src/hooks/useAuth.ts`      | `src/hooks/useAuth.test.ts`      |
+| `src/components/Button.tsx` | `src/components/Button.test.tsx` |
 
 ### Test Patterns
 

package/templates/e2e/performance/home.spec.ts

@@ -0,0 +1,94 @@
+import { expect, test } from './setup';
+
+test.describe('Home Page Performance', () => {
+  // React Profiler + FPS metrics (Chromium only for FPS - uses Chrome DevTools Protocol)
+  test.performance({
+    warmup: true,
+    iterations: 3,
+    thresholds: {
+      base: {
+        profiler: {
+          'home-page': { duration: 200, rerenders: 10 },
+        },
+        fps: 55,
+      },
+      ci: {
+        profiler: {
+          'home-page': { duration: 300 },
+        },
+        fps: 45,
+      },
+    },
+  })('initial page load', async ({ page, performance }) => {
+    await page.goto('/');
+    await performance.init();
+
+    await expect(page.getByRole('heading', { name: /welcome/i })).toBeVisible();
+  });
+
+  test.performance({
+    warmup: true,
+    throttleRate: 4, // 4x CPU slowdown
+    networkThrottling: 'fast-3g',
+    thresholds: {
+      base: {
+        profiler: {
+          'home-page': { duration: 1200, rerenders: 10 },
+        },
+      },
+    },
+  })('page load under throttled conditions', async ({ page, performance }) => {
+    await page.goto('/');
+    await performance.init();
+
+    await expect(page.getByRole('heading', { name: /welcome/i })).toBeVisible();
+  });
+
+  // Lighthouse audits (Chromium only - requires lighthouse peer dependency)
+  test.performance({
+    thresholds: {
+      base: {
+        lighthouse: {
+          performance: 80,
+          accessibility: 90,
+          bestPractices: 80,
+          seo: 90,
+        },
+      },
+      ci: {
+        lighthouse: {
+          performance: 70, // Relaxed for CI
+        },
+      },
+    },
+  })('meets Lighthouse quality standards', async ({ page, performance }) => {
+    await page.goto('/');
+    await performance.init();
+
+    await expect(page.getByRole('heading', { name: /welcome/i })).toBeVisible();
+  });
+
+  // Web Vitals with comprehensive metrics
+  test.performance({
+    thresholds: {
+      base: {
+        profiler: {
+          'home-page': { duration: 200, rerenders: 10 },
+        },
+        webVitals: {
+          lcp: 2500, // Largest Contentful Paint (ms)
+          inp: 200, // Interaction to Next Paint (ms)
+          cls: 0.1, // Cumulative Layout Shift
+        },
+      },
+    },
+  })('meets Core Web Vitals standards', async ({ page, performance }) => {
+    await page.goto('/');
+    await performance.init();
+
+    // Trigger interaction for INP measurement
+    await page.getByRole('heading', { name: /welcome/i }).click();
+
+    await expect(page.getByRole('heading', { name: /welcome/i })).toBeVisible();
+  });
+});

package/templates/e2e/performance/setup.ts

@@ -0,0 +1,9 @@
+import { test as base } from '@playwright/test';
+import { createPerformanceTest } from 'react-performance-tracking/playwright';
+
+/**
+ * Playwright test extended with performance fixture.
+ * @see https://github.com/mkaczkowski/react-performance-tracking
+ */
+export const test = createPerformanceTest(base);
+export { expect } from '@playwright/test';

package/templates/e2e/tests/home.spec.ts

@@ -33,8 +33,8 @@ test.describe('Home Page', () => {
     // Verify skip link becomes visible when focused
     await expect(skipLink).toBeVisible();
 
-    // Click skip link to navigate to main content
-    await skipLink.click();
+    // Activate skip link with keyboard (how real users interact with skip links)
+    await skipLink.press('Enter');
 
     // Main should be scrolled into view
     await expect(page.locator('#main')).toBeInViewport();

package/templates/gitignore

@@ -11,7 +11,7 @@ dist-ssr/
 .idea/
 *.swp
 *.swo
-.DS_Stores
+.DS_Store
 
 # Environment
 .env

package/templates/package.json

@@ -22,7 +22,7 @@
     "shadcn",
     "tailwind"
   ],
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "workspaces": [
     "packages/*"
@@ -39,14 +39,20 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "e2e": "playwright test",
-    "e2e:ui": "playwright test --ui",
+    "e2e": "playwright test --project=functional",
+    "e2e:ui": "playwright test --project=functional --ui",
+    "e2e:perf": "PERF_TEST=true playwright test --project=performance",
+    "e2e:perf:ui": "PERF_TEST=true playwright test --project=performance --ui",
+    "e2e:all": "PERF_TEST=true playwright test",
     "i18n:extract": "lingui extract",
     "prepare": "husky",
     "mcp:build": "npm run build -w @react-spa-scaffold/mcp",
     "mcp:dev": "npm run dev -w @react-spa-scaffold/mcp",
     "mcp:start": "npm run start -w @react-spa-scaffold/mcp",
-    "mcp:inspect": "npm run inspect -w @react-spa-scaffold/mcp"
+    "mcp:inspect": "npm run inspect -w @react-spa-scaffold/mcp",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
   },
   "dependencies": {
     "@fontsource-variable/inter": "^5.2.5",
@@ -63,6 +69,7 @@
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-hook-form": "^7.58.0",
+    "react-performance-tracking": "^1.2.1",
     "react-router": "^7.11.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.3.0",
@@ -71,16 +78,17 @@
     "zustand": "^5.0.9"
   },
   "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
     "@commitlint/config-conventional": "^20.2.0",
-    "@react-spa-scaffold/eslint-config": "*",
-    "@react-spa-scaffold/prettier-config": "*",
-    "@react-spa-scaffold/tsconfig": "*",
-    "shadcn": "^3.6.2",
     "@eslint/js": "^9.28.0",
     "@lingui/babel-plugin-lingui-macro": "^5.7.0",
     "@lingui/cli": "^5.7.0",
     "@lingui/vite-plugin": "^5.7.0",
     "@playwright/test": "^1.52.0",
+    "@react-spa-scaffold/eslint-config": "*",
+    "@react-spa-scaffold/prettier-config": "*",
+    "@react-spa-scaffold/tsconfig": "*",
     "@sentry/vite-plugin": "^4.6.1",
     "@tailwindcss/vite": "^4.1.17",
     "@testing-library/jest-dom": "^6.6.3",
@@ -92,6 +100,7 @@
     "@vitejs/plugin-react": "^5.1.2",
     "@vitest/coverage-v8": "^4.0.16",
     "babel-plugin-macros": "^3.1.0",
+    "chrome-launcher": "^1.2.1",
     "commitlint": "^20.2.0",
     "eslint": "^9.28.0",
     "eslint-config-prettier": "^10.1.0",
@@ -100,10 +109,12 @@
     "eslint-plugin-react-refresh": "^0.4.20",
     "husky": "^9.1.7",
     "jsdom": "^27.4.0",
+    "lighthouse": "^12.8.2",
     "lint-staged": "^16.1.0",
     "msw": "^2.12.7",
     "prettier": "^3.5.3",
     "prettier-plugin-tailwindcss": "^0.7.2",
+    "shadcn": "^3.6.2",
     "tailwindcss": "^4.1.17",
     "typescript": "~5.9.0",
     "typescript-eslint": "^8.33.0",

package/templates/playwright.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig, devices } from '@playwright/test';
 
 export default defineConfig({
-  testDir: './e2e/tests',
+  testDir: './e2e',
   fullyParallel: true,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
@@ -17,12 +17,24 @@ export default defineConfig({
   },
   projects: [
     {
-      name: 'chromium',
+      name: 'functional',
+      testDir: './e2e/tests',
       use: { ...devices['Desktop Chrome'] },
     },
+    {
+      name: 'performance',
+      testDir: './e2e/performance',
+      use: {
+        ...devices['Desktop Chrome'],
+        // CI containers require --no-sandbox; --disable-dev-shm-usage prevents memory issues
+        launchOptions: {
+          args: process.env.CI ? ['--no-sandbox', '--disable-dev-shm-usage'] : [],
+        },
+      },
+    },
   ],
   webServer: {
-    command: 'npm run dev',
+    command: process.env.PERF_TEST ? 'VITE_PERF_TEST=true npm run dev' : 'npm run dev',
     url: 'http://localhost:5173',
     reuseExistingServer: !process.env.CI,
     timeout: 120000,

package/templates/src/contexts/performanceContext.test.tsx

@@ -0,0 +1,51 @@
+import { renderHook } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { PerformanceProviderWrapper, usePerformance } from '@/contexts/performanceContext';
+
+const wrapper = ({ children }: { children: ReactNode }) => (
+  <PerformanceProviderWrapper>{children}</PerformanceProviderWrapper>
+);
+
+describe('usePerformance', () => {
+  it('returns no-op callback when used outside provider', () => {
+    // Should NOT throw, unlike usePerformanceRequired from the library
+    const { result } = renderHook(() => usePerformance());
+
+    expect(result.current).toBeDefined();
+    expect(result.current.onProfilerRender).toBeInstanceOf(Function);
+
+    // Verify no-op callback doesn't throw when called
+    expect(() => {
+      result.current.onProfilerRender('test-id', 'mount', 100, 50, 1000, 1001);
+    }).not.toThrow();
+  });
+
+  it('returns context value when used with provider', () => {
+    const { result } = renderHook(() => usePerformance(), { wrapper });
+
+    expect(result.current).toBeDefined();
+    expect(result.current.onProfilerRender).toBeInstanceOf(Function);
+  });
+});
+
+describe('PerformanceProviderWrapper', () => {
+  it('renders children when performance is disabled', () => {
+    // In test environment, DEV is false and VITE_PERF_TEST is not set
+    // So the provider should be disabled and just render children
+    const { result } = renderHook(() => usePerformance(), { wrapper });
+
+    expect(result.current).toBeDefined();
+  });
+
+  it('does not crash on mount or unmount', () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const { unmount } = renderHook(() => usePerformance(), { wrapper });
+
+    expect(() => unmount()).not.toThrow();
+
+    consoleSpy.mockRestore();
+  });
+});

package/templates/src/contexts/performanceContext.tsx

@@ -0,0 +1,64 @@
+import { lazy, Suspense, type ReactNode } from 'react';
+
+import { usePerformance as useLibPerformance } from 'react-performance-tracking/react';
+
+/**
+ * Lazy-load the PerformanceProvider to avoid bundling it in production.
+ * This provider is only used during performance testing.
+ */
+const PerformanceProvider = lazy(() =>
+  import('react-performance-tracking/react').then((m) => ({
+    default: m.PerformanceProvider,
+  })),
+);
+
+interface PerformanceProviderWrapperProps {
+  children: ReactNode;
+}
+
+/**
+ * Conditionally wraps children with PerformanceProvider for E2E performance testing.
+ *
+ * Only enabled when:
+ * - Running in development mode (DEV), OR
+ * - VITE_PERF_TEST environment variable is set to "true"
+ *
+ * In production builds without the env var, this is a pass-through component
+ * with zero runtime overhead.
+ *
+ * @see https://github.com/mkaczkowski/react-performance-tracking
+ */
+export function PerformanceProviderWrapper({ children }: PerformanceProviderWrapperProps) {
+  const isPerformanceEnabled = import.meta.env.DEV || import.meta.env.VITE_PERF_TEST === 'true';
+
+  if (!isPerformanceEnabled) {
+    return <>{children}</>;
+  }
+
+  return (
+    <Suspense fallback={<>{children}</>}>
+      <PerformanceProvider>{children}</PerformanceProvider>
+    </Suspense>
+  );
+}
+
+/**
+ * No-op profiler callback for when performance tracking is disabled.
+ * This prevents crashes in production when the PerformanceProvider is not mounted.
+ */
+const noopProfilerCallback: React.ProfilerOnRenderCallback = () => {
+  // Intentionally empty - performance tracking disabled
+};
+
+const noopContext = { onProfilerRender: noopProfilerCallback };
+
+/**
+ * Safe hook that returns performance context or a no-op fallback.
+ * Unlike usePerformanceRequired from the library, this NEVER throws.
+ */
+export function usePerformance() {
+  const context = useLibPerformance();
+
+  // Return no-op if context is null (provider not mounted)
+  return context ?? noopContext;
+}