@react-spa-scaffold/mcp 2.2.0 → 2.3.0

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

@@ -26,3 +26,20 @@ export { useExampleQuery } from './useExampleQuery';
 
 // Form hooks
 export { useRegisterForm } from './useRegisterForm';
+
+// 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';

package/templates/src/hooks/supabase/useProfiles.test.tsx

@@ -0,0 +1,207 @@
+import { QueryClientProvider } from '@tanstack/react-query';
+import { renderHook, waitFor } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import {
+  createTestQueryClient,
+  setMockClerkSignedIn,
+  setMockClerkUser,
+  resetClerkMocks,
+  createProfile,
+  setMockSupabaseData,
+  resetSupabaseMocks,
+} from '@/test';
+
+import { useCurrentProfile, useProfile, useUpsertProfile, useUpdateProfile, useDeleteProfile } from './useProfiles';
+
+function createWrapper() {
+  const queryClient = createTestQueryClient();
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+  };
+}
+
+describe('useCurrentProfile', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+    resetSupabaseMocks();
+  });
+
+  it('fetches profile when user is signed in', async () => {
+    const profile = createProfile({ id: 'user-123', full_name: 'Test User' });
+    setMockSupabaseData([profile]);
+    setMockClerkUser({ id: 'user-123' });
+
+    const { result } = renderHook(() => useCurrentProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(result.current.data).toHaveLength(1);
+    expect(result.current.data?.[0].full_name).toBe('Test User');
+  });
+
+  it('does not fetch when user is not signed in', async () => {
+    setMockClerkSignedIn(false);
+
+    const { result } = renderHook(() => useCurrentProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    // Query should be disabled
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.data).toBeUndefined();
+  });
+});
+
+describe('useProfile', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+    resetSupabaseMocks();
+  });
+
+  it('returns profile object and exists flag', async () => {
+    const profile = createProfile({ id: 'user-123', full_name: 'Test User' });
+    setMockSupabaseData([profile]);
+    setMockClerkUser({ id: 'user-123' });
+
+    const { result } = renderHook(() => useProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(result.current.profile?.full_name).toBe('Test User');
+    expect(result.current.exists).toBe(true);
+  });
+
+  it('returns null profile when not found', async () => {
+    setMockSupabaseData([]);
+    setMockClerkUser({ id: 'user-123' });
+
+    const { result } = renderHook(() => useProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(result.current.profile).toBeNull();
+    expect(result.current.exists).toBe(false);
+  });
+
+  it('exposes isFetching and refetch', async () => {
+    const profile = createProfile({ id: 'user-123' });
+    setMockSupabaseData([profile]);
+    setMockClerkUser({ id: 'user-123' });
+
+    const { result } = renderHook(() => useProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(typeof result.current.isFetching).toBe('boolean');
+    expect(typeof result.current.refetch).toBe('function');
+  });
+});
+
+describe('useUpsertProfile', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+    resetSupabaseMocks();
+  });
+
+  it('returns mutation function', () => {
+    const { result } = renderHook(() => useUpsertProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    expect(typeof result.current.mutate).toBe('function');
+    expect(typeof result.current.mutateAsync).toBe('function');
+    expect(result.current.isIdle).toBe(true);
+  });
+});
+
+describe('useUpdateProfile', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+    resetSupabaseMocks();
+  });
+
+  it('returns mutation function', () => {
+    setMockClerkUser({ id: 'user-123' });
+
+    const { result } = renderHook(() => useUpdateProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    expect(typeof result.current.mutate).toBe('function');
+    expect(typeof result.current.mutateAsync).toBe('function');
+    expect(result.current.isIdle).toBe(true);
+  });
+
+  it('throws when user is not authenticated', async () => {
+    setMockClerkSignedIn(false);
+
+    const { result } = renderHook(() => useUpdateProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    let errorThrown = false;
+    try {
+      await result.current.mutateAsync({ full_name: 'Test' });
+    } catch (error) {
+      errorThrown = true;
+      expect((error as Error).message).toBe('No authenticated user');
+    }
+
+    expect(errorThrown).toBe(true);
+  });
+});
+
+describe('useDeleteProfile', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+    resetSupabaseMocks();
+  });
+
+  it('returns mutation function', () => {
+    setMockClerkUser({ id: 'user-123' });
+
+    const { result } = renderHook(() => useDeleteProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    expect(typeof result.current.mutate).toBe('function');
+    expect(typeof result.current.mutateAsync).toBe('function');
+    expect(result.current.isIdle).toBe(true);
+  });
+
+  it('throws when user is not authenticated', async () => {
+    setMockClerkSignedIn(false);
+
+    const { result } = renderHook(() => useDeleteProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    let errorThrown = false;
+    try {
+      await result.current.mutateAsync();
+    } catch (error) {
+      errorThrown = true;
+      expect((error as Error).message).toBe('No authenticated user');
+    }
+
+    expect(errorThrown).toBe(true);
+  });
+});

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

@@ -0,0 +1,213 @@
+/**
+ * User profile hooks for Supabase with Clerk authentication.
+ *
+ * All operations are automatically scoped to the current user via RLS policies.
+ * The profile `id` field corresponds to the Clerk user_id (`auth.uid()`).
+ */
+
+import { useUser } from '@clerk/react-router';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import type { PostgrestError } from '@supabase/supabase-js';
+
+import { useSupabase } from '@/contexts/supabaseContext';
+import type { Profile, ProfileInsert, ProfileUpdate } from '@/types/database';
+
+import { useSupabaseQuery } from './useSupabaseQuery';
+
+/**
+ * Hook to fetch the current user's profile (returns array).
+ *
+ * Uses Clerk's user ID to query the profile and automatically
+ * respects RLS policies. For convenience, consider using `useProfile()`
+ * which returns a single profile instead of an array.
+ *
+ * @example
+ * ```tsx
+ * function ProfilePage() {
+ *   const { data: profiles, isLoading, error } = useCurrentProfile();
+ *   const profile = profiles?.[0];
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return <Error message={error.message} />;
+ *   if (!profile) return <CreateProfileForm />;
+ *
+ *   return <ProfileDisplay profile={profile} />;
+ * }
+ * ```
+ */
+export function useCurrentProfile() {
+  const { user, isLoaded } = useUser();
+  const userId = user?.id;
+
+  return useSupabaseQuery<Profile>({
+    table: 'profiles',
+    filter: (query) => query.eq('id', userId ?? ''),
+    queryKey: ['current', userId ?? ''],
+    queryOptions: {
+      enabled: isLoaded && !!userId,
+    },
+  });
+}
+
+/**
+ * Convenience hook to fetch the current user's profile as a single object.
+ *
+ * This is a wrapper around `useCurrentProfile()` that extracts the first
+ * profile from the array and provides a cleaner API for common use cases.
+ *
+ * @example
+ * ```tsx
+ * function ProfilePage() {
+ *   const { profile, isLoading, error, exists } = useProfile();
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return <Error message={error.message} />;
+ *   if (!exists) return <CreateProfileForm />;
+ *
+ *   return <ProfileDisplay profile={profile} />;
+ * }
+ * ```
+ */
+export function useProfile() {
+  const query = useCurrentProfile();
+  const profile = query.data?.[0] ?? null;
+
+  return {
+    /** The user's profile, or null if not found */
+    profile,
+    /** Whether a profile exists for the current user */
+    exists: profile !== null,
+    /** Whether the query is currently loading */
+    isLoading: query.isLoading,
+    /** Whether the query is fetching (includes background refetches) */
+    isFetching: query.isFetching,
+    /** Error from the query, if any */
+    error: query.error,
+    /** Refetch the profile data */
+    refetch: query.refetch,
+  };
+}
+
+/**
+ * Hook to create or update the current user's profile.
+ *
+ * Uses upsert to handle both creation and updates in a single operation.
+ * This is useful for syncing Clerk user data to Supabase on first login.
+ *
+ * @example
+ * ```tsx
+ * function ProfileSync() {
+ *   const { user } = useUser();
+ *   const upsertProfile = useUpsertProfile();
+ *
+ *   useEffect(() => {
+ *     if (user) {
+ *       upsertProfile.mutate({
+ *         id: user.id,
+ *         email: user.primaryEmailAddress?.emailAddress ?? '',
+ *         full_name: user.fullName,
+ *         avatar_url: user.imageUrl,
+ *       });
+ *     }
+ *   }, [user]);
+ * }
+ * ```
+ */
+export function useUpsertProfile() {
+  const supabase = useSupabase();
+  const queryClient = useQueryClient();
+
+  return useMutation<Profile, PostgrestError, ProfileInsert>({
+    mutationFn: async (profile) => {
+      const { data, error } = await supabase.from('profiles').upsert(profile, { onConflict: 'id' }).select().single();
+
+      if (error) throw error;
+      return data as Profile;
+    },
+    onSuccess: () => {
+      // Invalidate profile queries to refetch fresh data
+      queryClient.invalidateQueries({ queryKey: ['supabase', 'profiles'] });
+    },
+  });
+}
+
+/**
+ * Hook to update the current user's profile.
+ *
+ * Only updates the specified fields, leaving others unchanged.
+ *
+ * @example
+ * ```tsx
+ * function EditProfileForm() {
+ *   const updateProfile = useUpdateProfile();
+ *
+ *   const handleSubmit = (values: ProfileUpdate) => {
+ *     updateProfile.mutate(values, {
+ *       onSuccess: () => toast.success('Profile updated!'),
+ *       onError: (error) => toast.error(error.message),
+ *     });
+ *   };
+ * }
+ * ```
+ */
+export function useUpdateProfile() {
+  const { user } = useUser();
+  const supabase = useSupabase();
+  const queryClient = useQueryClient();
+
+  return useMutation<Profile, PostgrestError, ProfileUpdate>({
+    mutationFn: async (updates) => {
+      if (!user?.id) {
+        throw new Error('No authenticated user');
+      }
+
+      const { data, error } = await supabase.from('profiles').update(updates).eq('id', user.id).select().single();
+
+      if (error) throw error;
+      return data as Profile;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['supabase', 'profiles'] });
+    },
+  });
+}
+
+/**
+ * Hook to delete the current user's profile.
+ *
+ * Use with caution - this permanently removes the user's profile data.
+ *
+ * @example
+ * ```tsx
+ * function DeleteAccountButton() {
+ *   const deleteProfile = useDeleteProfile();
+ *
+ *   const handleDelete = async () => {
+ *     if (confirm('Are you sure? This cannot be undone.')) {
+ *       await deleteProfile.mutateAsync();
+ *       // User should be signed out after deletion
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export function useDeleteProfile() {
+  const { user } = useUser();
+  const supabase = useSupabase();
+  const queryClient = useQueryClient();
+
+  return useMutation<void, PostgrestError, void>({
+    mutationFn: async () => {
+      if (!user?.id) {
+        throw new Error('No authenticated user');
+      }
+
+      const { error } = await supabase.from('profiles').delete().eq('id', user.id);
+
+      if (error) throw error;
+    },
+    onSuccess: () => {
+      queryClient.removeQueries({ queryKey: ['supabase', 'profiles'] });
+    },
+  });
+}