@react-spa-scaffold/mcp 0.3.0

package/templates/src/locales/es.po

@@ -0,0 +1,65 @@
+msgid ""
+msgstr ""
+"Language: es\n"
+"Project-Id-Version: \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: \n"
+"PO-Revision-Date: \n"
+"Last-Translator: \n"
+"Language-Team: \n"
+"Content-Type: \n"
+"Content-Transfer-Encoding: \n"
+"Plural-Forms: \n"
+
+#. Button label to navigate back to the home page from 404 error
+#: src/pages/NotFound.tsx:23
+msgid "Back to Home"
+msgstr ""
+
+#. Accessibility label for the language selector dropdown button
+#: src/components/shared/LanguageSwitcher/LanguageSwitcher.tsx:24
+msgid "Change language"
+msgstr "Cambiar idioma"
+
+#. Instructions for developers on how to start customizing the app
+#: src/pages/Home.tsx:10
+msgid "Get started by editing <0>src/App.tsx</0>"
+msgstr "Comienza editando <0>src/App.tsx</0>"
+
+#: src/components/ui/loading.tsx:54
+msgid "Loading..."
+msgstr ""
+
+#. Application name displayed in the header navigation
+#: src/components/layout/Header.tsx:10
+msgid "My App"
+msgstr "Mi App"
+
+#. Heading shown on 404 error page when URL doesn't exist
+#: src/pages/NotFound.tsx:13
+msgid "Page Not Found"
+msgstr ""
+
+#. Accessibility label when clicking will switch to dark theme
+#. Accessibility label when clicking will switch to dark theme
+#: src/components/shared/ThemeToggle/ThemeToggle.tsx:26
+#: src/components/shared/ThemeToggle/ThemeToggle.tsx:29
+msgid "Switch to dark mode"
+msgstr "Cambiar a modo oscuro"
+
+#. Accessibility label when clicking will switch to light theme
+#. Accessibility label when clicking will switch to light theme
+#: src/components/shared/ThemeToggle/ThemeToggle.tsx:22
+#: src/components/shared/ThemeToggle/ThemeToggle.tsx:30
+msgid "Switch to light mode"
+msgstr "Cambiar a modo claro"
+
+#. Explanation message on 404 error page
+#: src/pages/NotFound.tsx:16
+msgid "The page you're looking for doesn't exist or has been moved."
+msgstr ""
+
+#. Main heading on the home page
+#: src/pages/Home.tsx:7
+msgid "Welcome to My App"
+msgstr "Bienvenido a Mi App"

package/templates/src/main.tsx

@@ -0,0 +1,107 @@
+import { I18nProvider } from '@lingui/react';
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router';
+
+import './index.css';
+import { ErrorBoundary } from '@/components/shared';
+import { Toaster } from '@/components/ui/sonner';
+import { MobileProvider } from '@/contexts/mobileContext';
+import { QueryProvider } from '@/contexts/queryContext';
+import { i18n, initI18n } from '@/i18n';
+import { SENTRY_CONFIG } from '@/lib/config';
+import { initPreferencesSync } from '@/stores/preferencesStore';
+
+import App from './App';
+
+/**
+ * Lazy load Sentry after initial render to avoid blocking web vitals.
+ * Returns the Sentry module for use in global error handlers.
+ */
+async function initSentry() {
+  if (import.meta.env.PROD && SENTRY_CONFIG.enabled && SENTRY_CONFIG.dsn) {
+    try {
+      const Sentry = await import('@sentry/react');
+      Sentry.init({
+        dsn: SENTRY_CONFIG.dsn,
+        sendDefaultPii: true,
+        integrations: [Sentry.browserTracingIntegration()],
+        tracesSampleRate: SENTRY_CONFIG.tracesSampleRate,
+      });
+      return Sentry;
+    } catch (error) {
+      console.error('Failed to initialize Sentry:', error);
+    }
+  }
+  return null;
+}
+
+/**
+ * Setup global error handlers for uncaught errors and promise rejections.
+ * @param Sentry - The Sentry module or null if not available
+ */
+function setupGlobalErrorHandlers(Sentry: Awaited<ReturnType<typeof initSentry>>) {
+  // Handle uncaught errors
+  window.onerror = (message, source, lineno, colno, error) => {
+    console.error('Uncaught error:', { message, source, lineno, colno, error });
+
+    if (Sentry && error) {
+      Sentry.captureException(error);
+    }
+
+    // Return false to allow default browser handling
+    return false;
+  };
+
+  // Handle unhandled promise rejections
+  window.onunhandledrejection = (event) => {
+    console.error('Unhandled promise rejection:', event.reason);
+
+    if (Sentry) {
+      Sentry.captureException(event.reason);
+    }
+  };
+}
+
+// Initialize i18n before rendering
+initI18n().then(() => {
+  // Initialize multi-tab sync for preferences
+  const cleanupPreferencesSync = initPreferencesSync();
+
+  createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+      <QueryProvider>
+        <I18nProvider i18n={i18n}>
+          <BrowserRouter>
+            <MobileProvider>
+              <ErrorBoundary>
+                <App />
+                <Toaster />
+              </ErrorBoundary>
+            </MobileProvider>
+          </BrowserRouter>
+        </I18nProvider>
+      </QueryProvider>
+    </StrictMode>,
+  );
+
+  // Initialize Sentry after render, using idle callback for best web vitals
+  const initSentryAndHandlers = () => {
+    initSentry().then((Sentry) => {
+      setupGlobalErrorHandlers(Sentry);
+    });
+  };
+
+  if ('requestIdleCallback' in window) {
+    requestIdleCallback(initSentryAndHandlers);
+  } else {
+    setTimeout(initSentryAndHandlers, 1);
+  }
+
+  // Cleanup on HMR (development only)
+  if (import.meta.hot) {
+    import.meta.hot.dispose(() => {
+      cleanupPreferencesSync();
+    });
+  }
+});

package/templates/src/mocks/fixtures/index.ts

@@ -0,0 +1 @@
+export { mockTodos, createTodo, createTodos, type Todo } from './todos';

package/templates/src/mocks/fixtures/todos.ts

@@ -0,0 +1,40 @@
+/**
+ * Mock data and factory functions for todos.
+ * Matches the JSONPlaceholder API structure used by useExampleQuery.
+ */
+
+import type { Todo } from '@/types/api';
+
+export type { Todo };
+
+/**
+ * Sample todos for testing.
+ * These match the structure from https://jsonplaceholder.typicode.com/todos
+ */
+export const mockTodos: Todo[] = [
+  { userId: 1, id: 1, title: 'Setup MSW for testing', completed: true },
+  { userId: 1, id: 2, title: 'Write integration tests', completed: false },
+  { userId: 1, id: 3, title: 'Add error handling', completed: false },
+  { userId: 2, id: 4, title: 'Review PR', completed: false },
+  { userId: 2, id: 5, title: 'Deploy to staging', completed: false },
+];
+
+/**
+ * Factory function to create a single todo with optional overrides.
+ */
+export function createTodo(overrides: Partial<Todo> = {}): Todo {
+  return {
+    userId: 1,
+    id: Date.now(),
+    title: 'New Todo',
+    completed: false,
+    ...overrides,
+  };
+}
+
+/**
+ * Factory function to create multiple todos.
+ */
+export function createTodos(count: number, overrides: Partial<Todo> = {}): Todo[] {
+  return Array.from({ length: count }, (_, i) => createTodo({ id: i + 1, title: `Todo ${i + 1}`, ...overrides }));
+}

package/templates/src/mocks/handlers/index.ts

@@ -0,0 +1,7 @@
+import { todosHandlers } from './todos';
+
+/**
+ * All MSW request handlers.
+ * Add new feature handlers here as the application grows.
+ */
+export const handlers = [...todosHandlers];

package/templates/src/mocks/handlers/todos.ts

@@ -0,0 +1,59 @@
+/**
+ * MSW handlers for JSONPlaceholder todos API.
+ * These intercept requests to the API used by useExampleQuery.
+ */
+import { delay, http, HttpResponse } from 'msw';
+
+import { API_CONFIG } from '@/lib/api';
+import type { Todo } from '@/types/api';
+
+import { mockTodos } from '../fixtures/todos';
+
+const BASE_URL = API_CONFIG.baseUrl;
+
+export const todosHandlers = [
+  // GET /todos - List todos with optional limit
+  http.get(`${BASE_URL}/todos`, async ({ request }) => {
+    const url = new URL(request.url);
+    const limit = url.searchParams.get('_limit');
+
+    // Small delay to simulate network latency
+    await delay(50);
+
+    const todos = limit ? mockTodos.slice(0, parseInt(limit, 10)) : mockTodos;
+
+    return HttpResponse.json(todos);
+  }),
+
+  // GET /todos/:id - Get single todo
+  http.get(`${BASE_URL}/todos/:id`, async ({ params }) => {
+    const { id } = params;
+    const todo = mockTodos.find((t) => t.id === Number(id));
+
+    await delay(50);
+
+    if (!todo) {
+      return new HttpResponse(null, { status: 404 });
+    }
+
+    return HttpResponse.json(todo);
+  }),
+
+  // POST /todos - Create todo
+  http.post(`${BASE_URL}/todos`, async ({ request }) => {
+    const body = (await request.json()) as Partial<Todo>;
+
+    await delay(50);
+
+    return HttpResponse.json(
+      {
+        id: mockTodos.length + 1,
+        userId: 1,
+        title: '',
+        completed: false,
+        ...body,
+      },
+      { status: 201 },
+    );
+  }),
+];

package/templates/src/mocks/index.ts

@@ -0,0 +1,3 @@
+export { handlers } from './handlers';
+export { server } from './node';
+export * from './fixtures';

package/templates/src/mocks/node.ts

@@ -0,0 +1,9 @@
+/**
+ * MSW server for Node.js (testing environment).
+ * This is used by Vitest to intercept network requests during tests.
+ */
+import { setupServer } from 'msw/node';
+
+import { handlers } from './handlers';
+
+export const server = setupServer(...handlers);

package/templates/src/pages/Home.tsx

@@ -0,0 +1,27 @@
+import { Trans, useLingui } from '@lingui/react/macro';
+
+import { SEO } from '@/components/shared';
+
+export function HomePage() {
+  const { t } = useLingui();
+
+  return (
+    <div className="container mx-auto px-4 py-8">
+      <SEO
+        title={t({ message: 'Home', comment: 'Home page title for SEO' })}
+        description={t({
+          message: 'Welcome to our modern React application',
+          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>
+  );
+}

package/templates/src/pages/NotFound.tsx

@@ -0,0 +1,28 @@
+import { Trans } from '@lingui/react/macro';
+import { Home } from 'lucide-react';
+import { Link } from 'react-router';
+
+import { Button } from '@/components/ui/button';
+import { ROUTES } from '@/lib/routes';
+
+export function NotFoundPage() {
+  return (
+    <div className="container mx-auto flex min-h-[60vh] flex-col items-center justify-center px-4 py-16 text-center">
+      <h1 className="text-foreground text-6xl font-bold">404</h1>
+      <h2 className="text-muted-foreground mt-4 text-2xl">
+        <Trans comment="Heading shown on 404 error page when URL doesn't exist">Page Not Found</Trans>
+      </h2>
+      <p className="text-muted-foreground mt-2 max-w-md">
+        <Trans comment="Explanation message on 404 error page">
+          The page you're looking for doesn't exist or has been moved.
+        </Trans>
+      </p>
+      <Button asChild className="mt-8">
+        <Link to={ROUTES.HOME}>
+          <Home className="mr-2 size-4" />
+          <Trans comment="Button label to navigate back to the home page from 404 error">Back to Home</Trans>
+        </Link>
+      </Button>
+    </div>
+  );
+}

package/templates/src/pages/index.ts

@@ -0,0 +1,2 @@
+export { HomePage } from './Home';
+export { NotFoundPage } from './NotFound';

package/templates/src/stores/index.ts

@@ -0,0 +1,2 @@
+export { usePreferencesStore, initPreferencesSync } from './preferencesStore';
+export type { Theme, Preferences } from './preferencesStore';

package/templates/src/stores/preferencesStore.ts

@@ -0,0 +1,85 @@
+import { create } from 'zustand';
+import { devtools, persist } from 'zustand/middleware';
+
+import { STORAGE_KEYS } from '@/lib/storageKeys';
+
+export type Theme = 'light' | 'dark' | 'system';
+
+export interface Preferences {
+  theme: Theme;
+}
+
+interface PreferencesState extends Preferences {
+  setTheme: (theme: Theme) => void;
+  toggleTheme: () => void;
+  reset: () => void;
+  /**
+   * Get the resolved theme (light/dark) based on system preference when theme is 'system'
+   */
+  getResolvedTheme: () => 'light' | 'dark';
+}
+
+const initialState: Preferences = {
+  theme: 'system',
+};
+
+/**
+ * Get the system's preferred color scheme
+ */
+function getSystemTheme(): 'light' | 'dark' {
+  if (typeof window === 'undefined') return 'light';
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+export const usePreferencesStore = create<PreferencesState>()(
+  devtools(
+    persist(
+      (set, get) => ({
+        ...initialState,
+        setTheme: (theme) => set({ theme }),
+        toggleTheme: () =>
+          set((state) => {
+            const resolved = state.theme === 'system' ? getSystemTheme() : state.theme;
+            return { theme: resolved === 'light' ? 'dark' : 'light' };
+          }),
+        reset: () => set(initialState),
+        getResolvedTheme: () => {
+          const { theme } = get();
+          return theme === 'system' ? getSystemTheme() : theme;
+        },
+      }),
+      {
+        name: STORAGE_KEYS.preferences,
+        partialize: (state) => ({ theme: state.theme }),
+      },
+    ),
+    { name: 'preferences' },
+  ),
+);
+
+/**
+ * Initialize multi-tab sync for preferences.
+ * Call this once at app startup.
+ */
+export function initPreferencesSync(): () => void {
+  if (typeof window === 'undefined') return () => {};
+
+  const handleStorage = (e: StorageEvent) => {
+    if (e.key === STORAGE_KEYS.preferences && e.newValue) {
+      try {
+        const parsed = JSON.parse(e.newValue);
+        if (parsed.state) {
+          usePreferencesStore.setState(parsed.state);
+        }
+      } catch {
+        // Ignore parse errors
+      }
+    }
+  };
+
+  window.addEventListener('storage', handleStorage);
+
+  return () => {
+    window.removeEventListener('storage', handleStorage);
+  };
+}

package/templates/src/test/index.ts

@@ -0,0 +1,8 @@
+// Custom render with all providers
+export { createTestQueryClient, render } from './providers';
+
+// Mock utilities
+export { mockMatchMedia } from './mocks';
+
+// MSW server instance
+export { server } from '@/mocks/node';

package/templates/src/test/mocks.ts

@@ -0,0 +1,17 @@
+import { vi } from 'vitest';
+
+/**
+ * Creates a mock for window.matchMedia.
+ * Usage: window.matchMedia = mockMatchMedia(true) // matches
+ */
+export const mockMatchMedia = (matches: boolean) =>
+  vi.fn().mockImplementation((query: string) => ({
+    matches,
+    media: query,
+    onchange: null,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  }));

package/templates/src/test/providers.tsx

@@ -0,0 +1,54 @@
+import { i18n } from '@lingui/core';
+import { I18nProvider } from '@lingui/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { render, type RenderOptions } from '@testing-library/react';
+import { type ReactElement, type ReactNode } from 'react';
+import { MemoryRouter } from 'react-router';
+
+import { MobileProvider } from '@/contexts/mobileContext';
+
+// Setup empty English catalog for tests
+i18n.loadAndActivate({ locale: 'en', messages: {} });
+
+/**
+ * Creates a fresh QueryClient for each test with test-optimized settings.
+ * Best practices from TanStack Query docs:
+ * - retry: false - Faster failure tests, no retry delays
+ * - gcTime: 0 - Prevents caching between tests
+ * - staleTime: 0 - Data always considered stale in tests
+ */
+export function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        gcTime: 0,
+        staleTime: 0,
+      },
+    },
+  });
+}
+
+interface WrapperProps {
+  children: ReactNode;
+}
+
+function AllProviders({ children }: WrapperProps) {
+  const queryClient = createTestQueryClient();
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <I18nProvider i18n={i18n}>
+        <MemoryRouter>
+          <MobileProvider>{children}</MobileProvider>
+        </MemoryRouter>
+      </I18nProvider>
+    </QueryClientProvider>
+  );
+}
+
+function customRender(ui: ReactElement, options?: Omit<RenderOptions, 'wrapper'>) {
+  return render(ui, { wrapper: AllProviders, ...options });
+}
+
+export { customRender as render };

package/templates/src/test-setup.ts

@@ -0,0 +1,54 @@
+import '@testing-library/jest-dom/vitest';
+import { afterAll, afterEach, beforeAll } from 'vitest';
+
+import { server } from '@/mocks/node';
+
+// =============================================================================
+// MSW Server Setup
+// =============================================================================
+
+// Start MSW server before all tests
+beforeAll(() => {
+  server.listen({
+    onUnhandledRequest: 'warn', // Warn about unhandled requests during tests
+  });
+});
+
+// Reset handlers after each test to ensure test isolation
+afterEach(() => {
+  server.resetHandlers();
+});
+
+// Close MSW server after all tests complete
+afterAll(() => {
+  server.close();
+});
+
+// =============================================================================
+// Browser API Mocks
+// =============================================================================
+
+// Mock ResizeObserver
+global.ResizeObserver = class ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
+
+// Mock matchMedia
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: (query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false,
+  }),
+});
+
+// Mock scrollTo
+window.scrollTo = () => {};

package/templates/src/types/api.ts

@@ -0,0 +1,31 @@
+/**
+ * API response types.
+ * Shared between hooks, mocks, and components.
+ */
+
+export interface Todo {
+  userId: number;
+  id: number;
+  title: string;
+  completed: boolean;
+}
+
+/**
+ * Generic API error response
+ */
+export interface ApiError {
+  message: string;
+  code?: string;
+  status?: number;
+}
+
+/**
+ * Paginated response wrapper
+ */
+export interface PaginatedResponse<T> {
+  data: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  hasMore: boolean;
+}

package/templates/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './preferences';
+export * from './api';

package/templates/src/types/preferences.ts

@@ -0,0 +1,5 @@
+export type Theme = 'light' | 'dark' | 'system';
+
+export interface Preferences {
+  theme: Theme;
+}

package/templates/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_APP_NAME: string;
+  readonly VITE_APP_URL: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}