@react-spa-scaffold/mcp 0.3.0 → 1.1.0

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

@@ -0,0 +1,156 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  release:
+    types: [published]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/master' }}
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ./.github/actions/setup-node-deps
+      - run: npm run lint
+      - run: npm run format:check
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ./.github/actions/setup-node-deps
+      - run: npm run typecheck
+
+  security:
+    name: Security Audit
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ./.github/actions/setup-node-deps
+      - run: npm audit --audit-level=moderate
+
+  build:
+    name: Build
+    needs: [lint, typecheck]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    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 }}
+      - uses: actions/upload-artifact@v6
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  test:
+    name: Unit Tests
+    needs: [lint, typecheck]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ./.github/actions/setup-node-deps
+      - run: npm run test:coverage
+      - uses: actions/upload-artifact@v6
+        with:
+          name: coverage
+          path: coverage/
+          retention-days: 14
+
+  e2e:
+    name: E2E Tests
+    needs: [lint, typecheck]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ./.github/actions/setup-node-deps
+      - name: Cache Playwright browsers
+        uses: actions/cache@v5
+        id: playwright-cache
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+      - name: Install Playwright browsers
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: npx playwright install chromium --with-deps
+      - name: Install Playwright deps (cached)
+        if: steps.playwright-cache.outputs.cache-hit == 'true'
+        run: npx playwright install-deps chromium
+      - run: npm run e2e
+      - uses: actions/upload-artifact@v6
+        if: failure()
+        with:
+          name: playwright-report
+          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"

package/templates/.husky/commit-msg

@@ -0,0 +1 @@
+npx commitlint --edit $1

package/templates/.husky/pre-commit

@@ -0,0 +1,2 @@
+npm run typecheck
+npx lint-staged

package/templates/.nvmrc

@@ -0,0 +1 @@
+22

package/templates/CLAUDE.md

@@ -113,14 +113,16 @@ Need general info?     → WebSearch (fallback only)
 
 ## Translations (CRITICAL)
 
-All user-facing text MUST have translator comments. ESLint enforces this.
+All user-facing text MUST be wrapped and include translator comments. ESLint enforces this.
 
 ```tsx
 <Trans comment="Dashboard heading">Welcome back</Trans>;
 t({ message: 'Close', comment: 'Close button' });
 ```
 
-See [docs/INTERNATIONALIZATION.md](docs/INTERNATIONALIZATION.md).
+Technical identifiers (`id`, `htmlFor`, `autoComplete`, `register()`) are auto-ignored.
+
+See [docs/INTERNATIONALIZATION.md](docs/INTERNATIONALIZATION.md) for full details.
 
 ## Testing
 

package/templates/commitlint.config.js

@@ -0,0 +1 @@
+export default { extends: ['@commitlint/config-conventional'] };

package/templates/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "radix-nova",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "zinc",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}

package/templates/docs/API_REFERENCE.md

@@ -9,7 +9,6 @@ Quick reference for what's available. For architectural decisions, see [Architec
 | `api.ts`         | HTTP client           | Any API calls - handles errors, timeouts, JSON. Includes API_CONFIG |
 | `config.ts`      | App configuration     | Access APP_CONFIG, SENTRY_CONFIG                                    |
 | `env.ts`         | Environment variables | Type-safe `env.VITE_*` access                                       |
-| `format.ts`      | Formatters            | Dates, numbers, currency, bytes - all locale-aware                  |
 | `routes.ts`      | Route constants       | Type-safe navigation, avoid magic strings                           |
 | `storage.ts`     | localStorage wrapper  | SSR-safe, typed storage with error handling                         |
 | `storageKeys.ts` | Storage key constants | Centralized key management                                          |

package/templates/docs/INTERNATIONALIZATION.md

@@ -62,6 +62,32 @@ The `eslint-plugin-lingui` enforces translations:
 
 Excluded from checks: tests, mocks, UI primitives, config files.
 
+### Auto-Ignored Technical Identifiers
+
+The ESLint config automatically ignores strings that are technical identifiers:
+
+**Prop names** (values don't need translation):
+
+- HTML: `id`, `htmlFor`, `autoComplete`, `aria-invalid`
+- Styling: `className`, `styleName`
+- Components: `type`, `variant`, `size`, `role`, `name`
+- Routing: `href`, `to`, `path`
+- Data: `queryKey`, `data-testid`
+
+**Function arguments**:
+
+- `register('fieldName')` - React Hook Form field names
+- `console.*`, `Error()` - Debug/error messages
+
+```tsx
+// These are fine - no translation needed
+<Label htmlFor="email">
+<Input id="email" autoComplete="email" {...register('email')} />
+
+// This DOES need translation (user-facing placeholder)
+placeholder={t({ message: 'Enter email', comment: 'Email input hint' })}
+```
+
 ## Adding a New Locale
 
 Edit `lingui.config.js` and add the locale code to the `locales` array.

package/templates/e2e/fixtures/index.ts

@@ -0,0 +1,10 @@
+import type { Page } from '@playwright/test';
+
+/**
+ * Navigate to page with clean state (clears localStorage)
+ */
+export async function setupPage(page: Page, path = '/') {
+  await page.goto(path);
+  await page.evaluate(() => localStorage.clear());
+  await page.reload();
+}

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

@@ -0,0 +1,42 @@
+import { expect, test } from '@playwright/test';
+
+test.describe('Home Page', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/');
+  });
+
+  test('displays welcome heading', async ({ page }) => {
+    await expect(page.getByRole('heading', { name: /welcome/i })).toBeVisible();
+  });
+
+  test('has correct page structure', async ({ page }) => {
+    // Header present
+    await expect(page.getByRole('banner')).toBeVisible();
+
+    // Main content area
+    await expect(page.getByRole('main')).toBeVisible();
+
+    // App title in header
+    await expect(page.getByRole('heading', { level: 1 })).toBeVisible();
+  });
+
+  test('skip link navigates to main content', async ({ page }) => {
+    const skipLink = page.getByRole('link', { name: /skip to main content/i });
+
+    // Ensure skip link exists in DOM
+    await expect(skipLink).toBeAttached();
+
+    // Focus the skip link explicitly (more reliable than Tab in E2E)
+    await skipLink.focus();
+    await expect(skipLink).toBeFocused();
+
+    // Verify skip link becomes visible when focused
+    await expect(skipLink).toBeVisible();
+
+    // Click skip link to navigate to main content
+    await skipLink.click();
+
+    // Main should be scrolled into view
+    await expect(page.locator('#main')).toBeInViewport();
+  });
+});

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

@@ -0,0 +1,42 @@
+import { expect, test } from '@playwright/test';
+
+import { setupPage } from '../fixtures';
+
+test.describe('Language Switcher', () => {
+  test.beforeEach(async ({ page }) => {
+    await setupPage(page);
+  });
+
+  test('displays language switcher button', async ({ page }) => {
+    await expect(page.getByRole('button', { name: /change language/i })).toBeVisible();
+  });
+
+  test('opens dropdown with language options', async ({ page }) => {
+    await page.getByRole('button', { name: /change language/i }).click();
+
+    await expect(page.getByText('English')).toBeVisible();
+    await expect(page.getByText('Español')).toBeVisible();
+    await expect(page.getByText('Deutsch')).toBeVisible();
+  });
+
+  test('closes dropdown after selection', async ({ page }) => {
+    await page.getByRole('button', { name: /change language/i }).click();
+    await page.getByText('Español').click();
+
+    // Dropdown should close - other options not visible
+    await expect(page.getByText('Deutsch')).not.toBeVisible();
+  });
+
+  test('persists language preference across reload', async ({ page }) => {
+    // Change to Spanish
+    await page.getByRole('button', { name: /change language/i }).click();
+    await page.getByText('Español').click();
+
+    // Wait for language change to apply
+    await expect(page.getByRole('heading', { name: /bienvenido/i })).toBeVisible();
+
+    // Reload and verify Spanish persisted
+    await page.reload();
+    await expect(page.getByRole('heading', { name: /bienvenido/i })).toBeVisible();
+  });
+});

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

@@ -0,0 +1,18 @@
+import { expect, test } from '@playwright/test';
+
+test.describe('Navigation', () => {
+  test('shows 404 page for unknown routes', async ({ page }) => {
+    await page.goto('/non-existent-page');
+    await expect(page.getByRole('heading', { name: '404' })).toBeVisible();
+  });
+
+  test('header is present on all pages', async ({ page }) => {
+    // Home page
+    await page.goto('/');
+    await expect(page.getByRole('banner')).toBeVisible();
+
+    // 404 page
+    await page.goto('/unknown');
+    await expect(page.getByRole('banner')).toBeVisible();
+  });
+});

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

@@ -0,0 +1,35 @@
+import { expect, test } from '@playwright/test';
+
+import { setupPage } from '../fixtures';
+
+test.describe('Theme Toggle', () => {
+  test.beforeEach(async ({ page }) => {
+    await setupPage(page);
+  });
+
+  test('defaults to light theme', async ({ page }) => {
+    await expect(page.locator('html')).not.toHaveClass(/dark/);
+  });
+
+  test('toggles between light and dark theme', async ({ page }) => {
+    const html = page.locator('html');
+
+    // Toggle to dark
+    await page.getByRole('button', { name: /switch to dark mode/i }).click();
+    await expect(html).toHaveClass(/dark/);
+
+    // Toggle back to light
+    await page.getByRole('button', { name: /switch to light mode/i }).click();
+    await expect(html).not.toHaveClass(/dark/);
+  });
+
+  test('persists theme preference across reload', async ({ page }) => {
+    // Set dark theme
+    await page.getByRole('button', { name: /switch to dark mode/i }).click();
+    await expect(page.locator('html')).toHaveClass(/dark/);
+
+    // Reload and verify
+    await page.reload();
+    await expect(page.locator('html')).toHaveClass(/dark/);
+  });
+});

package/templates/eslint.config.js

@@ -0,0 +1,42 @@
+/**
+ * ESLint configuration for react-spa-scaffold
+ *
+ * Uses @react-spa-scaffold/eslint-config with local overrides for monorepo packages.
+ */
+
+import config from '@react-spa-scaffold/eslint-config';
+
+export default [
+  // Main app uses React config
+  ...config,
+
+  // Additional ignore for monorepo packages dist
+  { ignores: ['packages/**/dist'] },
+
+  // UI components from shadcn and context/provider files - don't modify
+  {
+    files: ['**/components/ui/**/*.{ts,tsx}', '**/contexts/**/*.{ts,tsx}', '**/test/**/*.{ts,tsx}'],
+    rules: {
+      'react-refresh/only-export-components': 'off',
+    },
+  },
+
+  // Packages use Node.js rules (override the React/i18n rules from main config)
+  {
+    files: ['packages/**/*.ts'],
+    rules: {
+      // Disable React-specific rules (not a React app)
+      'react-hooks/rules-of-hooks': 'off',
+      'react-hooks/exhaustive-deps': 'off',
+      'react-refresh/only-export-components': 'off',
+      // Disable i18n rules (server-side code)
+      'lingui/no-unlocalized-strings': 'off',
+      'lingui/t-call-in-function': 'off',
+      'lingui/no-single-variables-to-translate': 'off',
+      'lingui/no-expression-in-message': 'off',
+      'lingui/no-trans-inside-trans': 'off',
+      // Allow console for server logging
+      'no-console': 'off',
+    },
+  },
+];

package/templates/gitignore

@@ -0,0 +1,33 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+dist-ssr/
+*.tsbuildinfo
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Stores
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Testing
+coverage/
+playwright-report/
+test-results/
+playwright/.cache/
+
+# i18n compiled catalogs (generated by Vite plugin during build)
+src/locales/*.mjs
+
+# Misc
+tmp
+*.log
+npm-debug.log*

package/templates/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/lighthouse-budget.json

@@ -0,0 +1,17 @@
+[
+  {
+    "path": "/*",
+    "resourceSizes": [
+      { "resourceType": "script", "budget": 500 },
+      { "resourceType": "stylesheet", "budget": 100 },
+      { "resourceType": "total", "budget": 1000 }
+    ],
+    "resourceCounts": [{ "resourceType": "third-party", "budget": 10 }],
+    "timings": [
+      { "metric": "first-contentful-paint", "budget": 2000 },
+      { "metric": "interactive", "budget": 5000 },
+      { "metric": "largest-contentful-paint", "budget": 3000 },
+      { "metric": "cumulative-layout-shift", "budget": 0.1 }
+    ]
+  }
+]

package/templates/lighthouserc.json

@@ -0,0 +1,23 @@
+{
+  "ci": {
+    "collect": {
+      "staticDistDir": "./dist",
+      "numberOfRuns": 3,
+      "settings": {
+        "preset": "desktop",
+        "budgetPath": "./lighthouse-budget.json"
+      }
+    },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["warn", { "minScore": 0.9 }],
+        "categories:accessibility": ["warn", { "minScore": 0.9 }],
+        "categories:best-practices": ["warn", { "minScore": 0.9 }],
+        "categories:seo": ["warn", { "minScore": 0.9 }]
+      }
+    },
+    "upload": {
+      "target": "temporary-public-storage"
+    }
+  }
+}

package/templates/lingui.config.js

@@ -0,0 +1,18 @@
+import { defineConfig } from '@lingui/cli';
+
+export default defineConfig({
+  locales: ['en', 'es', 'de'],
+  sourceLocale: 'en',
+  fallbackLocales: {
+    default: 'en',
+  },
+  catalogs: [
+    {
+      path: '<rootDir>/src/locales/{locale}',
+      include: ['src'],
+      exclude: ['**/node_modules/**', '**/*.test.{ts,tsx}'],
+    },
+  ],
+  format: 'po',
+  compileNamespace: 'es',
+});