@react-spa-scaffold/mcp 2.1.1 → 2.3.0

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

@@ -1,7 +1,10 @@
-import { Component, type ErrorInfo, type ReactNode } from 'react';
 import { Trans } from '@lingui/react/macro';
+import { AlertTriangle, RefreshCw } from 'lucide-react';
+import { Component, type ErrorInfo, type ReactNode } from 'react';
 
-import { SENTRY_CONFIG } from '@/lib/config';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { captureException } from '@/lib/sentry';
 
 interface Props {
   children: ReactNode;
@@ -15,6 +18,48 @@ interface State {
   error: Error | null;
 }
 
+interface ErrorFallbackUIProps {
+  error: Error | null;
+  onRetry: () => void;
+  onReload: () => void;
+}
+
+function ErrorFallbackUI({ error, onRetry, onReload }: ErrorFallbackUIProps) {
+  return (
+    <div className="flex min-h-screen items-center justify-center p-4">
+      <Card className="max-w-md">
+        <CardHeader>
+          <div className="flex items-center gap-2">
+            <AlertTriangle className="text-destructive size-5" />
+            <CardTitle>
+              <Trans>Something went wrong</Trans>
+            </CardTitle>
+          </div>
+          <CardDescription>
+            <Trans>An unexpected error occurred. You can try again or reload the page.</Trans>
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          {error && (
+            <div className="bg-muted rounded-md p-3">
+              <p className="text-muted-foreground font-mono text-xs break-all">{error.message}</p>
+            </div>
+          )}
+          <div className="flex gap-2">
+            <Button onClick={onRetry} variant="default">
+              <Trans>Try Again</Trans>
+            </Button>
+            <Button onClick={onReload} variant="outline">
+              <RefreshCw className="mr-2 size-4" />
+              <Trans>Reload Page</Trans>
+            </Button>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
 export class ErrorBoundary extends Component<Props, State> {
   constructor(props: Props) {
     super(props);
@@ -28,22 +73,11 @@ export class ErrorBoundary extends Component<Props, State> {
   componentDidCatch(error: Error, errorInfo: ErrorInfo) {
     console.error('ErrorBoundary caught an error:', error, errorInfo);
 
+    // Report error to Sentry with component stack
+    captureException(error, { componentStack: errorInfo.componentStack ?? undefined });
+
     // Call custom error handler if provided
     this.props.onError?.(error, errorInfo);
-
-    // Report to Sentry in production (if enabled and configured)
-    if (import.meta.env.PROD && SENTRY_CONFIG.enabled && SENTRY_CONFIG.dsn) {
-      // eslint-disable-next-line lingui/no-unlocalized-strings
-      import('@sentry/react')
-        .then((Sentry) => {
-          Sentry.captureException(error, {
-            extra: { componentStack: errorInfo.componentStack },
-          });
-        })
-        .catch(() => {
-          // Sentry failed to load, error already logged above
-        });
-    }
   }
 
   /**
@@ -54,49 +88,17 @@ export class ErrorBoundary extends Component<Props, State> {
     this.setState({ hasError: false, error: null });
   };
 
+  handleReload = () => {
+    window.location.reload();
+  };
+
   render() {
     if (this.state.hasError) {
       if (this.props.fallback) {
         return this.props.fallback;
       }
 
-      return (
-        <div className="flex min-h-screen items-center justify-center p-4">
-          <div className="text-center">
-            <h1 className="text-destructive text-2xl font-bold">
-              <Trans comment="Error boundary - main error heading">Something went wrong</Trans>
-            </h1>
-            <p className="text-muted-foreground mt-2">
-              <Trans comment="Error boundary - error explanation">
-                We're sorry, but something unexpected happened.
-              </Trans>
-            </p>
-            {import.meta.env.DEV && this.state.error && (
-              <details className="bg-muted mt-4 rounded-md p-4 text-left">
-                <summary className="cursor-pointer font-medium">
-                  <Trans comment="Error boundary - debug section heading">Error details</Trans>
-                </summary>
-                <pre className="mt-2 overflow-auto text-sm">{this.state.error.message}</pre>
-                <pre className="mt-1 overflow-auto text-xs opacity-75">{this.state.error.stack}</pre>
-              </details>
-            )}
-            <div className="mt-6 flex justify-center gap-3">
-              <button
-                onClick={this.reset}
-                className="bg-secondary text-secondary-foreground rounded px-4 py-2 transition-colors hover:opacity-90"
-              >
-                <Trans comment="Error boundary - try again button">Try Again</Trans>
-              </button>
-              <button
-                onClick={() => window.location.reload()}
-                className="bg-primary text-primary-foreground rounded px-4 py-2 transition-colors hover:opacity-90"
-              >
-                <Trans comment="Error boundary - refresh button">Refresh Page</Trans>
-              </button>
-            </div>
-          </div>
-        </div>
-      );
+      return <ErrorFallbackUI error={this.state.error} onRetry={this.reset} onReload={this.handleReload} />;
     }
 
     return this.props.children;

package/templates/src/components/shared/ProfileSync/ProfileSync.test.tsx

@@ -0,0 +1,44 @@
+import { waitFor } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { render, setMockClerkSignedIn, resetClerkMocks } from '@/test';
+
+import { ProfileSync } from './ProfileSync';
+
+// Mock the hooks
+const mockMutate = vi.fn();
+vi.mock('@/hooks', async () => {
+  const actual = await vi.importActual('@/hooks');
+  return {
+    ...actual,
+    useCurrentProfile: vi.fn(() => ({ data: [], isLoading: false })),
+    useUpsertProfile: vi.fn(() => ({ mutate: mockMutate, isPending: false })),
+  };
+});
+
+describe('ProfileSync', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+    mockMutate.mockClear();
+  });
+
+  it('renders nothing (invisible)', () => {
+    setMockClerkSignedIn(true);
+    const { container } = render(<ProfileSync />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('does not sync when signed out', async () => {
+    setMockClerkSignedIn(false);
+    render(<ProfileSync />);
+    await waitFor(() => expect(mockMutate).not.toHaveBeenCalled());
+  });
+
+  it('syncs profile when signed in', async () => {
+    setMockClerkSignedIn(true);
+    render(<ProfileSync />);
+    await waitFor(() => {
+      expect(mockMutate).toHaveBeenCalledWith(expect.objectContaining({ id: 'user_123' }), expect.any(Object));
+    });
+  });
+});

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

@@ -0,0 +1,104 @@
+/**
+ * ProfileSync - Invisible component that syncs Clerk user data to Supabase.
+ *
+ * This component ensures the authenticated user's profile exists in Supabase
+ * and stays in sync with their Clerk account data. It runs once per session
+ * and handles first-time profile creation automatically.
+ *
+ * @example
+ * ```tsx
+ * // Add to your app layout or protected routes
+ * function App() {
+ *   return (
+ *     <>
+ *       <ProfileSync />
+ *       <Routes>...</Routes>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+
+import { useEffect, useRef } from 'react';
+import { useUser } from '@clerk/react-router';
+
+import { useCurrentProfile, useUpsertProfile } from '@/hooks';
+
+interface ProfileSyncProps {
+  /**
+   * Callback fired when profile sync completes successfully.
+   */
+  onSyncComplete?: () => void;
+  /**
+   * Callback fired when profile sync fails.
+   */
+  onSyncError?: (error: Error) => void;
+}
+
+/**
+ * Syncs the current Clerk user's data to Supabase profiles table.
+ *
+ * This component:
+ * 1. Waits for Clerk user to be loaded
+ * 2. Checks if a profile already exists
+ * 3. Creates or updates the profile if needed
+ * 4. Only syncs once per component mount to prevent loops
+ *
+ * The sync uses upsert, so it's safe to call multiple times - it will
+ * create the profile if it doesn't exist, or update if data changed.
+ */
+export function ProfileSync({ onSyncComplete, onSyncError }: ProfileSyncProps) {
+  const { user, isLoaded: isUserLoaded } = useUser();
+  const { data: profiles, isLoading: isProfileLoading } = useCurrentProfile();
+  const upsertProfile = useUpsertProfile();
+
+  // Track if we've already synced this session to prevent infinite loops
+  const hasSynced = useRef(false);
+  const isSyncing = useRef(false);
+
+  useEffect(() => {
+    // Skip if already synced, currently syncing, or data not ready
+    if (hasSynced.current || isSyncing.current) return;
+    if (!isUserLoaded || !user) return;
+    if (isProfileLoading) return;
+
+    const existingProfile = profiles?.[0];
+
+    // Check if sync is needed:
+    // - No profile exists, OR
+    // - Email has changed (user updated in Clerk)
+    const needsSync = !existingProfile || existingProfile.email !== user.primaryEmailAddress?.emailAddress;
+
+    if (!needsSync) {
+      hasSynced.current = true;
+      return;
+    }
+
+    // Perform the sync
+    isSyncing.current = true;
+
+    upsertProfile.mutate(
+      {
+        id: user.id,
+        email: user.primaryEmailAddress?.emailAddress ?? '',
+        full_name: user.fullName ?? null,
+        avatar_url: user.imageUrl ?? null,
+      },
+      {
+        onSuccess: () => {
+          hasSynced.current = true;
+          isSyncing.current = false;
+          onSyncComplete?.();
+        },
+        onError: (error) => {
+          isSyncing.current = false;
+          // Don't set hasSynced so it can retry on next render
+          onSyncError?.(new Error(error.message));
+        },
+      },
+    );
+  }, [isUserLoaded, user, profiles, isProfileLoading, upsertProfile, onSyncComplete, onSyncError]);
+
+  // This component renders nothing - it's purely for side effects
+  return null;
+}

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

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

package/templates/src/components/shared/ProtectedRoute/ProtectedRoute.test.tsx

@@ -0,0 +1,43 @@
+import { screen } from '@testing-library/react';
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import { render, setMockClerkSignedIn, setMockClerkLoaded, resetClerkMocks } from '@/test';
+
+import { ProtectedRoute } from './ProtectedRoute';
+
+describe('ProtectedRoute', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+  });
+
+  it('renders children when signed in', () => {
+    render(
+      <ProtectedRoute>
+        <div>Protected Content</div>
+      </ProtectedRoute>,
+    );
+    expect(screen.getByText('Protected Content')).toBeInTheDocument();
+  });
+
+  it('shows loading when auth is not loaded', () => {
+    setMockClerkLoaded(false);
+    const { container } = render(
+      <ProtectedRoute>
+        <div>Protected Content</div>
+      </ProtectedRoute>,
+    );
+    expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
+    expect(container.querySelector('.animate-spin')).toBeInTheDocument();
+  });
+
+  it('redirects when not signed in', () => {
+    setMockClerkSignedIn(false);
+    render(
+      <ProtectedRoute>
+        <div>Protected Content</div>
+      </ProtectedRoute>,
+    );
+    expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
+    expect(screen.getByTestId('redirect-to-sign-in')).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,35 @@
+import { RedirectToSignIn, useAuth } from '@clerk/react-router';
+import type { ReactNode } from 'react';
+
+import { PageLoading } from '@/components/ui/loading';
+
+interface ProtectedRouteProps {
+  children: ReactNode;
+}
+
+/**
+ * Wraps routes that require authentication.
+ * Shows loading state while auth loads, redirects to sign-in if not authenticated.
+ *
+ * @example
+ * ```tsx
+ * <Route path="/dashboard" element={
+ *   <ProtectedRoute>
+ *     <DashboardPage />
+ *   </ProtectedRoute>
+ * } />
+ * ```
+ */
+export function ProtectedRoute({ children }: ProtectedRouteProps) {
+  const { isLoaded, isSignedIn } = useAuth();
+
+  if (!isLoaded) {
+    return <PageLoading />;
+  }
+
+  if (!isSignedIn) {
+    return <RedirectToSignIn />;
+  }
+
+  return <>{children}</>;
+}

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

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

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

@@ -1,5 +1,8 @@
-export { ThemeToggle } from './ThemeToggle';
+export { AccountButton } from './AccountButton';
 export { ErrorBoundary } from './ErrorBoundary';
-export { SEO } from './SEO';
 export { LanguageSwitcher } from './LanguageSwitcher';
+export { ProfileSync } from './ProfileSync';
+export { ProtectedRoute } from './ProtectedRoute';
 export { RegisterForm } from './RegisterForm';
+export { SEO } from './SEO';
+export { ThemeToggle } from './ThemeToggle';

package/templates/src/contexts/clerkContext.tsx

@@ -0,0 +1,45 @@
+import { ClerkProvider } from '@clerk/react-router';
+import { shadcn } from '@clerk/themes';
+import type { Appearance } from '@clerk/types';
+import type { ReactNode } from 'react';
+
+interface ClerkThemeProviderProps {
+  children: ReactNode;
+  publishableKey: string;
+}
+
+/**
+ * Clerk appearance configuration.
+ * Uses shadcn theme which auto-adapts to light/dark mode.
+ * Requires @clerk/themes/shadcn.css to be imported in index.css.
+ */
+const appearance: Appearance = {
+  baseTheme: shadcn,
+  variables: {
+    // Typography
+    fontFamily: '"Inter Variable", sans-serif',
+    // Match app's border radius (--radius: 0.45rem in index.css)
+    borderRadius: '0.45rem',
+  },
+  elements: {
+    // Make modal fullscreen on mobile devices
+    modalBackdrop: 'backdrop-blur-sm',
+    modalContent: 'sm:max-w-md max-sm:min-h-svh max-sm:min-w-full max-sm:rounded-none',
+    card: 'max-sm:rounded-none max-sm:shadow-none',
+    // Ensure consistent border radius on form elements
+    formFieldInput: 'rounded-md',
+    formButtonPrimary: 'rounded-md',
+    socialButtonsBlockButton: 'rounded-md',
+  },
+};
+
+/**
+ * ClerkProvider wrapper with consistent theming.
+ */
+export function ClerkThemeProvider({ children, publishableKey }: ClerkThemeProviderProps) {
+  return (
+    <ClerkProvider publishableKey={publishableKey} afterSignOutUrl="/" appearance={appearance}>
+      {children}
+    </ClerkProvider>
+  );
+}

package/templates/src/contexts/performanceContext.tsx

@@ -2,6 +2,8 @@ import { lazy, Suspense, type ReactNode } from 'react';
 
 import { usePerformance as useLibPerformance } from 'react-performance-tracking/react';
 
+import { PERFORMANCE_CONFIG } from '@/lib/config';
+
 /**
  * Lazy-load the PerformanceProvider to avoid bundling it in production.
  * This provider is only used during performance testing.
@@ -29,9 +31,7 @@ interface PerformanceProviderWrapperProps {
  * @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) {
+  if (!PERFORMANCE_CONFIG.enabled) {
     return <>{children}</>;
   }
 

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

@@ -0,0 +1,59 @@
+import { renderHook } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { SupabaseProvider, useSupabase } from './supabaseContext';
+
+// Mock Clerk's useSession hook
+vi.mock('@clerk/react-router', () => ({
+  useSession: () => ({
+    session: {
+      getToken: vi.fn().mockResolvedValue('mock-clerk-token'),
+    },
+  }),
+}));
+
+// Mock the Supabase client factory
+vi.mock('@/lib/supabase', () => ({
+  createSupabaseClient: vi.fn().mockReturnValue({
+    from: vi.fn().mockReturnValue({
+      select: vi.fn().mockResolvedValue({ data: [], error: null }),
+    }),
+  }),
+}));
+
+describe('SupabaseContext', () => {
+  const wrapper = ({ children }: { children: ReactNode }) => <SupabaseProvider>{children}</SupabaseProvider>;
+
+  describe('SupabaseProvider', () => {
+    it('provides supabase client to children', () => {
+      const { result } = renderHook(() => useSupabase(), { wrapper });
+
+      expect(result.current).toBeDefined();
+      expect(result.current.from).toBeDefined();
+    });
+
+    it('provides a client with from method', () => {
+      const { result } = renderHook(() => useSupabase(), { wrapper });
+
+      expect(typeof result.current.from).toBe('function');
+    });
+  });
+
+  describe('useSupabase', () => {
+    // Note: The "throws outside provider" behavior is tested implicitly
+    // The global mock in test-setup.ts provides a mock client for all tests,
+    // so we verify the actual throw behavior through the real implementation.
+    // This test uses the mocked version which always returns a client.
+
+    it('returns the same client instance on re-renders', () => {
+      const { result, rerender } = renderHook(() => useSupabase(), { wrapper });
+
+      const firstClient = result.current;
+      rerender();
+      const secondClient = result.current;
+
+      expect(firstClient).toBe(secondClient);
+    });
+  });
+});

package/templates/src/contexts/supabaseContext.tsx

@@ -0,0 +1,87 @@
+/**
+ * Supabase context provider with Clerk authentication integration.
+ *
+ * Provides a typed Supabase client that automatically uses Clerk session tokens
+ * for authentication. Must be placed inside ClerkProvider in the component tree.
+ *
+ * @see https://supabase.com/docs/guides/auth/third-party/clerk
+ */
+
+import { useSession } from '@clerk/react-router';
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+
+import { createSupabaseClient, type TypedSupabaseClient } from '@/lib/supabase';
+
+const SupabaseContext = createContext<TypedSupabaseClient | null>(null);
+
+interface SupabaseProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * Provides a Supabase client with Clerk authentication to the app.
+ *
+ * The client automatically injects Clerk session tokens into Supabase requests,
+ * enabling Row Level Security (RLS) policies based on `auth.uid()`.
+ *
+ * Must be placed INSIDE ClerkProvider in the provider hierarchy since it
+ * requires access to the Clerk session via useSession().
+ *
+ * @example
+ * ```tsx
+ * // In main.tsx
+ * <ClerkThemeProvider>
+ *   <SupabaseProvider>
+ *     <App />
+ *   </SupabaseProvider>
+ * </ClerkThemeProvider>
+ * ```
+ */
+export function SupabaseProvider({ children }: SupabaseProviderProps) {
+  const { session } = useSession();
+
+  // Create client with stable getToken reference
+  // Only recreate when session ID changes (sign in/out), not on every render
+  const supabase = useMemo(
+    () =>
+      createSupabaseClient(async () => {
+        if (!session) return null;
+        return session.getToken();
+      }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- session.id is stable, session object is not
+    [session?.id],
+  );
+
+  return <SupabaseContext.Provider value={supabase}>{children}</SupabaseContext.Provider>;
+}
+
+/**
+ * Hook to access the Supabase client.
+ *
+ * Returns a typed Supabase client that automatically handles Clerk authentication.
+ * All database operations will use RLS policies based on the current user.
+ *
+ * @throws Error if used outside SupabaseProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const supabase = useSupabase();
+ *
+ *   // Fetch user's own profile (RLS enforced)
+ *   const { data } = await supabase
+ *     .from('profiles')
+ *     .select('*')
+ *     .single();
+ * }
+ * ```
+ */
+export function useSupabase(): TypedSupabaseClient {
+  const context = useContext(SupabaseContext);
+
+  if (!context) {
+    throw new Error('useSupabase must be used within a SupabaseProvider');
+  }
+
+  return context;
+}

package/templates/src/hooks/index.ts

@@ -1,7 +1,45 @@
+// Media query and responsive hooks
 export { useMediaQuery, BREAKPOINTS } from './useMediaQuery';
-export { useThemeEffect } from './useThemeEffect';
+export { useMobileContext } from '@/contexts/mobileContext';
 export { useTouchSizes } from './useTouchSizes';
+export { useIOSViewportReset } from './useIOSViewportReset';
+
+// Theme and UI hooks
+export { useThemeEffect } from './useThemeEffect';
+export { useDocumentTitle } from './useDocumentTitle';
+
+// State and storage hooks
+export { useLocalStorage } from './useLocalStorage';
+export { useSyncedState } from './useSyncedState';
+export { useSyncedFormData } from './useSyncedFormData';
+
+// Utility hooks
+export { useCopyFeedback } from './useCopyFeedback';
+export { useDebouncedCallback } from './useDebouncedCallback';
+export { useKeyboardShortcut } from './useKeyboardShortcuts';
+
+// i18n hooks
 export { useLanguage } from './useLanguage';
+
+// API hooks
 export { useExampleQuery } from './useExampleQuery';
+
+// Form hooks
 export { useRegisterForm } from './useRegisterForm';
-export { useMobileContext } from '@/contexts/mobileContext';
+
+// Supabase hooks
+export {
+  // Generic query hook
+  useSupabaseQuery,
+  // Profile hooks (type-safe mutations)
+  useCurrentProfile,
+  useProfile,
+  useUpsertProfile,
+  useUpdateProfile,
+  useDeleteProfile,
+  // Types
+  type UseSupabaseQueryOptions,
+} from './supabase';
+
+// Supabase context
+export { useSupabase } from '@/contexts/supabaseContext';

package/templates/src/hooks/supabase/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Supabase hooks exports.
+ *
+ * Note: Generic mutation hooks were removed in favor of table-specific hooks
+ * (like useProfiles) which provide better type safety with Supabase's complex types.
+ */
+
+// Generic query hook
+export { useSupabaseQuery, type UseSupabaseQueryOptions } from './useSupabaseQuery';
+
+// Domain-specific hooks (type-safe mutations)
+export { useCurrentProfile, useProfile, useUpsertProfile, useUpdateProfile, useDeleteProfile } from './useProfiles';