@react-spa-scaffold/mcp 0.3.0 → 1.1.0

package/templates/package.json

@@ -0,0 +1,125 @@
+{
+  "name": "react-spa-scaffold",
+  "private": true,
+  "description": "Production-ready React 19 + TypeScript + Vite 7 starter template",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mkaczkowski/react-spa-scaffold.git"
+  },
+  "homepage": "https://github.com/mkaczkowski/react-spa-scaffold#readme",
+  "bugs": {
+    "url": "https://github.com/mkaczkowski/react-spa-scaffold/issues"
+  },
+  "keywords": [
+    "react",
+    "typescript",
+    "vite",
+    "starter",
+    "template",
+    "boilerplate",
+    "react-19",
+    "shadcn",
+    "tailwind"
+  ],
+  "version": "0.5.0",
+  "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "npm run typecheck && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc -p tsconfig.app.json && tsc -p tsconfig.node.json",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "e2e": "playwright test",
+    "e2e:ui": "playwright test --ui",
+    "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"
+  },
+  "dependencies": {
+    "@fontsource-variable/inter": "^5.2.5",
+    "@hookform/resolvers": "^5.0.1",
+    "@lingui/core": "^5.7.0",
+    "@lingui/react": "^5.7.0",
+    "@radix-ui/react-slot": "^1.2.3",
+    "@sentry/react": "^10.32.1",
+    "@tanstack/react-query": "^5.90.14",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.562.0",
+    "radix-ui": "^1.4.3",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-hook-form": "^7.58.0",
+    "react-router": "^7.11.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.3.0",
+    "tw-animate-css": "^1.2.9",
+    "zod": "^4.2.1",
+    "zustand": "^5.0.9"
+  },
+  "devDependencies": {
+    "@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",
+    "@sentry/vite-plugin": "^4.6.1",
+    "@tailwindcss/vite": "^4.1.17",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^22.15.0",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "@vitejs/plugin-react": "^5.1.2",
+    "@vitest/coverage-v8": "^4.0.16",
+    "babel-plugin-macros": "^3.1.0",
+    "commitlint": "^20.2.0",
+    "eslint": "^9.28.0",
+    "eslint-config-prettier": "^10.1.0",
+    "eslint-plugin-lingui": "^0.11.0",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "husky": "^9.1.7",
+    "jsdom": "^27.4.0",
+    "lint-staged": "^16.1.0",
+    "msw": "^2.12.7",
+    "prettier": "^3.5.3",
+    "prettier-plugin-tailwindcss": "^0.7.2",
+    "tailwindcss": "^4.1.17",
+    "typescript": "~5.9.0",
+    "typescript-eslint": "^8.33.0",
+    "vite": "^7.0.0",
+    "vitest": "^4.0.16"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml,css}": [
+      "prettier --write"
+    ]
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/templates/playwright.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e/tests',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: process.env.CI ? 'github' : [['list'], ['html']],
+  use: {
+    baseURL: 'http://localhost:5173',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  expect: {
+    timeout: 10000,
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});

package/templates/prettier.config.js

@@ -0,0 +1 @@
+export { default } from '@react-spa-scaffold/prettier-config/tailwind';

package/templates/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <rect width="32" height="32" rx="6" fill="#3B82F6"/>
+  <path d="M8 12h16M8 16h12M8 20h8" stroke="white" stroke-width="2" stroke-linecap="round"/>
+</svg>

package/templates/src/components/shared/RegisterForm/RegisterForm.tsx

@@ -0,0 +1,91 @@
+import { Trans, useLingui } from '@lingui/react/macro';
+
+import { Button } from '@/components/ui/button';
+import { FieldErrorMessage } from '@/components/ui/form-error';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { useRegisterForm } from '@/hooks';
+
+/**
+ * Registration form component demonstrating cross-field validation.
+ * Shows password confirmation with Zod's refine() for matching passwords.
+ */
+export function RegisterForm() {
+  const { t } = useLingui();
+  const { form, onSubmit, isSubmitting, errors } = useRegisterForm();
+  const { register } = form;
+
+  return (
+    <form onSubmit={onSubmit} className="space-y-4">
+      <div className="space-y-2">
+        <Label htmlFor="username">
+          <Trans comment="Register form username field label">Username</Trans>
+        </Label>
+        <Input
+          id="username"
+          placeholder={t({ message: 'johndoe', comment: 'Username placeholder example' })}
+          autoComplete="username"
+          aria-invalid={!!errors.username}
+          {...register('username')}
+        />
+        <FieldErrorMessage error={errors.username} />
+      </div>
+
+      <div className="space-y-2">
+        <Label htmlFor="register-email">
+          <Trans comment="Register form email field label">Email</Trans>
+        </Label>
+        <Input
+          id="register-email"
+          type="email"
+          placeholder={t({ message: 'john@example.com', comment: 'Email placeholder example' })}
+          autoComplete="email"
+          aria-invalid={!!errors.email}
+          {...register('email')}
+        />
+        <FieldErrorMessage error={errors.email} />
+      </div>
+
+      <div className="space-y-2">
+        <Label htmlFor="password">
+          <Trans comment="Register form password field label">Password</Trans>
+        </Label>
+        <Input
+          id="password"
+          type="password"
+          placeholder={t({
+            message: 'Min 8 chars, uppercase, lowercase, number',
+            comment: 'Password requirements hint',
+          })}
+          autoComplete="new-password"
+          aria-invalid={!!errors.password}
+          {...register('password')}
+        />
+        <FieldErrorMessage error={errors.password} />
+      </div>
+
+      <div className="space-y-2">
+        <Label htmlFor="confirmPassword">
+          <Trans comment="Register form confirm password field label">Confirm Password</Trans>
+        </Label>
+        <Input
+          id="confirmPassword"
+          type="password"
+          placeholder={t({ message: 'Re-enter your password', comment: 'Confirm password placeholder' })}
+          autoComplete="new-password"
+          aria-invalid={!!errors.confirmPassword}
+          {...register('confirmPassword')}
+        />
+        <FieldErrorMessage error={errors.confirmPassword} />
+      </div>
+
+      <Button type="submit" disabled={isSubmitting} className="w-full">
+        {isSubmitting ? (
+          <Trans comment="Register form submitting state">Creating account...</Trans>
+        ) : (
+          <Trans comment="Register form submit button">Create Account</Trans>
+        )}
+      </Button>
+    </form>
+  );
+}

package/templates/src/components/shared/RegisterForm/index.ts

@@ -0,0 +1 @@
+export { RegisterForm } from './RegisterForm';

package/templates/src/components/shared/index.ts

@@ -2,3 +2,4 @@ export { ThemeToggle } from './ThemeToggle';
 export { ErrorBoundary } from './ErrorBoundary';
 export { SEO } from './SEO';
 export { LanguageSwitcher } from './LanguageSwitcher';
+export { RegisterForm } from './RegisterForm';

package/templates/src/components/ui/card.tsx

@@ -0,0 +1,70 @@
+import * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+function Card({ className, size = 'default', ...props }: React.ComponentProps<'div'> & { size?: 'default' | 'sm' }) {
+  return (
+    <div
+      data-slot="card"
+      data-size={size}
+      className={cn(
+        'ring-foreground/10 bg-card text-card-foreground group/card flex flex-col gap-4 overflow-hidden rounded-xl py-4 text-sm ring-1 has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:gap-3 data-[size=sm]:py-3 data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        'group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-4 group-data-[size=sm]/card:px-3 has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-4 group-data-[size=sm]/card:[.border-b]:pb-3',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn('text-base leading-snug font-medium group-data-[size=sm]/card:text-sm', className)}
+      {...props}
+    />
+  );
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<'div'>) {
+  return <div data-slot="card-description" className={cn('text-muted-foreground text-sm', className)} {...props} />;
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn('col-start-2 row-span-2 row-start-1 self-start justify-self-end', className)}
+      {...props}
+    />
+  );
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<'div'>) {
+  return <div data-slot="card-content" className={cn('px-4 group-data-[size=sm]/card:px-3', className)} {...props} />;
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn('bg-muted/50 flex items-center rounded-b-xl border-t p-4 group-data-[size=sm]/card:p-3', className)}
+      {...props}
+    />
+  );
+}
+
+export { Card, CardHeader, CardFooter, CardTitle, CardAction, CardDescription, CardContent };

package/templates/src/components/ui/input.tsx

@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+function Input({ className, type, ...props }: React.ComponentProps<'input'>) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        'dark:bg-input/30 border-input focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:aria-invalid:border-destructive/50 disabled:bg-input/50 dark:disabled:bg-input/80 file:text-foreground placeholder:text-muted-foreground h-8 w-full min-w-0 rounded-lg border bg-transparent px-2.5 py-1 text-base transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium focus-visible:ring-[3px] disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:ring-[3px] md:text-sm',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Input };

package/templates/src/components/ui/label.tsx

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import { Label as LabelPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+function Label({ className, ...props }: React.ComponentProps<typeof LabelPrimitive.Root>) {
+  return (
+    <LabelPrimitive.Root
+      data-slot="label"
+      className={cn(
+        'flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Label };

package/templates/src/hooks/index.ts

@@ -3,5 +3,5 @@ export { useThemeEffect } from './useThemeEffect';
 export { useTouchSizes } from './useTouchSizes';
 export { useLanguage } from './useLanguage';
 export { useExampleQuery } from './useExampleQuery';
-export { useContactForm } from './useContactForm';
+export { useRegisterForm } from './useRegisterForm';
 export { useMobileContext } from '@/contexts/mobileContext';

package/templates/src/hooks/useRegisterForm.ts

@@ -0,0 +1,36 @@
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+
+import { type RegisterFormData, registerFormSchema } from '@/lib/validations';
+
+/**
+ * React Hook Form + Zod hook for registration.
+ * Demonstrates cross-field validation (password confirmation).
+ */
+export function useRegisterForm() {
+  const form = useForm<RegisterFormData>({
+    resolver: zodResolver(registerFormSchema),
+    defaultValues: {
+      username: '',
+      email: '',
+      password: '',
+      confirmPassword: '',
+    },
+  });
+
+  const onSubmit = async (data: RegisterFormData) => {
+    // Simulate API call delay
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    // Replace with your actual registration logic
+    // eslint-disable-next-line no-console
+    console.log('Registration submitted:', data);
+  };
+
+  return {
+    form,
+    onSubmit: form.handleSubmit(onSubmit),
+    isSubmitting: form.formState.isSubmitting,
+    errors: form.formState.errors,
+    reset: form.reset,
+  };
+}

package/templates/src/lib/index.ts

@@ -4,7 +4,6 @@
  */
 
 export { cn } from './utils';
-export { TIMING, UI } from './constants';
 export { STORAGE_KEYS, isAppKey } from './storageKeys';
 export { APP_CONFIG, SENTRY_CONFIG } from './config';
 export { API_CONFIG } from './api';
@@ -12,13 +11,4 @@ export { ROUTES, type AppRoute } from './routes';
 export { env, validateEnv, type Env } from './env';
 export { api, ApiClientError } from './api';
 export { getStorageItem, setStorageItem, removeStorageItem, clearAppStorage } from './storage';
-export {
-  formatDate,
-  formatDateTime,
-  formatRelativeTime,
-  formatNumber,
-  formatCurrency,
-  formatPercent,
-  formatBytes,
-} from './format';
-export { contactFormSchema, registerFormSchema, type ContactFormData, type RegisterFormData } from './validations';
+export { registerFormSchema, type RegisterFormData } from './validations';

package/templates/src/lib/validations.ts

@@ -1,19 +1,12 @@
 import { z } from 'zod';
 
 /**
- * Example validation schema for a contact form.
- * Extend or replace with your own schemas.
- */
-export const contactFormSchema = z.object({
-  name: z.string().min(2, 'Name must be at least 2 characters'),
-  email: z.string().email('Please enter a valid email address'),
-  message: z.string().min(10, 'Message must be at least 10 characters'),
-});
-
-export type ContactFormData = z.infer<typeof contactFormSchema>;
-
-/**
- * Example validation schema for user registration.
+ * Registration form validation schema.
+ * Demonstrates Zod validation patterns:
+ * - Basic validations: min, max, email, regex
+ * - Cross-field validation with refine() (password confirmation)
+ * - Custom error messages
+ * - Type inference with z.infer<>
  */
 export const registerFormSchema = z
   .object({

package/templates/src/pages/Home.tsx

@@ -1,12 +1,13 @@
 import { Trans, useLingui } from '@lingui/react/macro';
 
-import { SEO } from '@/components/shared';
+import { RegisterForm, SEO } from '@/components/shared';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 
 export function HomePage() {
   const { t } = useLingui();
 
   return (
-    <div className="container mx-auto px-4 py-8">
+    <div className="container mx-auto max-w-lg px-4 py-8">
       <SEO
         title={t({ message: 'Home', comment: 'Home page title for SEO' })}
         description={t({
@@ -14,14 +15,32 @@ export function HomePage() {
           comment: 'Home page meta description for SEO',
         })}
       />
-      <h1 className="text-3xl font-bold">
-        <Trans comment="Main heading on the home page">Welcome to My App</Trans>
-      </h1>
-      <p className="text-muted-foreground mt-2">
-        <Trans comment="Instructions for developers on how to start customizing the app">
-          Get started by editing <code className="bg-muted rounded px-1">src/App.tsx</code>
-        </Trans>
-      </p>
+
+      <div className="mb-8 text-center">
+        <h1 className="text-3xl font-bold">
+          <Trans comment="Main heading on the home page">Welcome to My App</Trans>
+        </h1>
+        <p className="text-muted-foreground mt-2">
+          <Trans comment="Instructions for developers on how to start customizing the app">
+            Get started by editing <code className="bg-muted rounded px-1">src/App.tsx</code>
+          </Trans>
+        </p>
+      </div>
+
+      {/* Form validation demo */}
+      <Card>
+        <CardHeader>
+          <CardTitle>
+            <Trans comment="Register form card title">Registration Form</Trans>
+          </CardTitle>
+          <CardDescription>
+            <Trans comment="Register form card description">React Hook Form + Zod validation demo</Trans>
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <RegisterForm />
+        </CardContent>
+      </Card>
     </div>
   );
 }

package/templates/tests/unit/components/RegisterForm.test.tsx

@@ -0,0 +1,105 @@
+import { screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+
+import { RegisterForm } from '@/components/shared/RegisterForm';
+import { render } from '@/test';
+
+describe('RegisterForm', () => {
+  it('renders all form fields', () => {
+    render(<RegisterForm />);
+
+    expect(screen.getByLabelText(/username/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/^password$/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/confirm password/i)).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /create account/i })).toBeInTheDocument();
+  });
+
+  it('shows validation errors for empty fields on submit', async () => {
+    const user = userEvent.setup();
+    render(<RegisterForm />);
+
+    await user.click(screen.getByRole('button', { name: /create account/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText(/username must be at least 3 characters/i)).toBeInTheDocument();
+    });
+
+    expect(screen.getByText(/please enter a valid email address/i)).toBeInTheDocument();
+    expect(screen.getByText(/password must be at least 8 characters/i)).toBeInTheDocument();
+  });
+
+  it('shows password mismatch error when passwords differ', async () => {
+    const user = userEvent.setup();
+    render(<RegisterForm />);
+
+    await user.type(screen.getByLabelText(/username/i), 'testuser');
+    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
+    await user.type(screen.getByLabelText(/^password$/i), 'Password1');
+    await user.type(screen.getByLabelText(/confirm password/i), 'Password2');
+    await user.click(screen.getByRole('button', { name: /create account/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText(/passwords don't match/i)).toBeInTheDocument();
+    });
+  });
+
+  it('submits form with valid data', async () => {
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const user = userEvent.setup();
+    render(<RegisterForm />);
+
+    await user.type(screen.getByLabelText(/username/i), 'testuser');
+    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
+    await user.type(screen.getByLabelText(/^password$/i), 'Password1');
+    await user.type(screen.getByLabelText(/confirm password/i), 'Password1');
+    await user.click(screen.getByRole('button', { name: /create account/i }));
+
+    await waitFor(() => {
+      expect(screen.getByRole('button', { name: /creating account/i })).toBeInTheDocument();
+    });
+
+    await waitFor(
+      () => {
+        expect(consoleSpy).toHaveBeenCalledWith('Registration submitted:', {
+          username: 'testuser',
+          email: 'test@example.com',
+          password: 'Password1',
+          confirmPassword: 'Password1',
+        });
+      },
+      { timeout: 2000 },
+    );
+
+    consoleSpy.mockRestore();
+  });
+
+  it('disables submit button while submitting', async () => {
+    const user = userEvent.setup();
+    render(<RegisterForm />);
+
+    await user.type(screen.getByLabelText(/username/i), 'testuser');
+    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
+    await user.type(screen.getByLabelText(/^password$/i), 'Password1');
+    await user.type(screen.getByLabelText(/confirm password/i), 'Password1');
+    await user.click(screen.getByRole('button', { name: /create account/i }));
+
+    await waitFor(() => {
+      expect(screen.getByRole('button', { name: /creating account/i })).toBeDisabled();
+    });
+  });
+
+  it('sets aria-invalid on fields with errors', async () => {
+    const user = userEvent.setup();
+    render(<RegisterForm />);
+
+    await user.click(screen.getByRole('button', { name: /create account/i }));
+
+    await waitFor(() => {
+      expect(screen.getByLabelText(/username/i)).toHaveAttribute('aria-invalid', 'true');
+      expect(screen.getByLabelText(/email/i)).toHaveAttribute('aria-invalid', 'true');
+      expect(screen.getByLabelText(/^password$/i)).toHaveAttribute('aria-invalid', 'true');
+    });
+  });
+});