@react-spa-scaffold/mcp 2.2.0 → 2.3.0

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

@@ -0,0 +1,150 @@
+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,
+  createProfile,
+  setMockSupabaseData,
+  setMockSupabaseError,
+  resetSupabaseMocks,
+} from '@/test';
+import type { Profile } from '@/types/database';
+
+import { useSupabaseQuery } from './useSupabaseQuery';
+
+function createWrapper() {
+  const queryClient = createTestQueryClient();
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+  };
+}
+
+describe('useSupabaseQuery', () => {
+  beforeEach(() => {
+    resetSupabaseMocks();
+  });
+
+  it('returns empty array when no data', async () => {
+    setMockSupabaseData([]);
+
+    const { result } = renderHook(
+      () =>
+        useSupabaseQuery<Profile>({
+          table: 'profiles',
+          queryKey: ['test'],
+        }),
+      { wrapper: createWrapper() },
+    );
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(result.current.data).toEqual([]);
+  });
+
+  it('returns data when available', async () => {
+    const profile = createProfile({ id: 'user-1', full_name: 'Test User' });
+    setMockSupabaseData([profile]);
+
+    const { result } = renderHook(
+      () =>
+        useSupabaseQuery<Profile>({
+          table: 'profiles',
+          queryKey: ['test'],
+        }),
+      { 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('returns error when query fails', async () => {
+    setMockSupabaseError({ message: 'Database error', code: 'DB_ERROR' });
+
+    const { result } = renderHook(
+      () =>
+        useSupabaseQuery<Profile>({
+          table: 'profiles',
+          queryKey: ['test-error'],
+          queryOptions: { retry: false },
+        }),
+      { wrapper: createWrapper() },
+    );
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    expect(result.current.error?.message).toBe('Database error');
+  });
+
+  it('applies custom select', async () => {
+    const profile = createProfile({ id: 'user-1' });
+    setMockSupabaseData([profile]);
+
+    const { result } = renderHook(
+      () =>
+        useSupabaseQuery<Profile>({
+          table: 'profiles',
+          select: 'id, full_name',
+          queryKey: ['test-select'],
+        }),
+      { wrapper: createWrapper() },
+    );
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(result.current.data).toBeDefined();
+  });
+
+  it('applies filter function', async () => {
+    const profile = createProfile({ id: 'user-1' });
+    setMockSupabaseData([profile]);
+
+    const { result } = renderHook(
+      () =>
+        useSupabaseQuery<Profile>({
+          table: 'profiles',
+          filter: (query) => query.eq('id', 'user-1'),
+          queryKey: ['test-filter'],
+        }),
+      { wrapper: createWrapper() },
+    );
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(result.current.data).toHaveLength(1);
+  });
+
+  it('respects enabled option', async () => {
+    const profile = createProfile();
+    setMockSupabaseData([profile]);
+
+    const { result } = renderHook(
+      () =>
+        useSupabaseQuery<Profile>({
+          table: 'profiles',
+          queryKey: ['test-disabled'],
+          queryOptions: { enabled: false },
+        }),
+      { wrapper: createWrapper() },
+    );
+
+    // Query should not run when disabled
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.isFetching).toBe(false);
+    expect(result.current.data).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,91 @@
+/**
+ * Generic Supabase query hook with TanStack Query integration.
+ *
+ * Provides type-safe database queries with automatic Clerk authentication
+ * and RLS policy enforcement.
+ */
+
+import { useQuery, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
+import type { PostgrestError } from '@supabase/supabase-js';
+
+import { useSupabase } from '@/contexts/supabaseContext';
+import type { TableName } from '@/types/database';
+
+/**
+ * Options for useSupabaseQuery hook.
+ */
+export interface UseSupabaseQueryOptions<TData> {
+  /** The database table to query */
+  table: TableName;
+  /** Columns to select (defaults to '*') */
+  select?: string;
+  /** Optional filter function to apply conditions */
+  filter?: (query: ReturnType<ReturnType<typeof useSupabase>['from']>) => unknown;
+  /** Unique query key for caching (will be prefixed with ['supabase', table]) */
+  queryKey: string[];
+  /** Additional TanStack Query options */
+  queryOptions?: Omit<UseQueryOptions<TData[], PostgrestError>, 'queryKey' | 'queryFn'>;
+}
+
+/**
+ * Generic hook for Supabase SELECT queries with TanStack Query.
+ *
+ * Automatically applies Clerk authentication via the Supabase context,
+ * ensuring RLS policies are enforced based on the current user.
+ *
+ * @example
+ * ```tsx
+ * // Simple query - fetch all user's profiles
+ * const { data, isLoading } = useSupabaseQuery<Profile>({
+ *   table: 'profiles',
+ *   queryKey: ['all'],
+ * });
+ *
+ * // Query with filter
+ * const { data } = useSupabaseQuery<Profile>({
+ *   table: 'profiles',
+ *   select: 'id, full_name, avatar_url',
+ *   filter: (query) => query.eq('id', userId),
+ *   queryKey: ['single', userId],
+ * });
+ *
+ * // Query with custom options
+ * const { data } = useSupabaseQuery<Profile>({
+ *   table: 'profiles',
+ *   queryKey: ['current'],
+ *   queryOptions: {
+ *     staleTime: 1000 * 60 * 10, // 10 minutes
+ *     enabled: !!userId,
+ *   },
+ * });
+ * ```
+ */
+export function useSupabaseQuery<TData>({
+  table,
+  select = '*',
+  filter,
+  queryKey,
+  queryOptions,
+}: UseSupabaseQueryOptions<TData>): UseQueryResult<TData[], PostgrestError> {
+  const supabase = useSupabase();
+
+  return useQuery<TData[], PostgrestError>({
+    queryKey: ['supabase', table, ...queryKey],
+    queryFn: async () => {
+      let query = supabase.from(table).select(select);
+
+      if (filter) {
+        query = filter(query) as typeof query;
+      }
+
+      const { data, error } = await query;
+
+      if (error) {
+        throw error;
+      }
+
+      return (data ?? []) as TData[];
+    },
+    ...queryOptions,
+  });
+}

package/templates/src/lib/api.test.ts

@@ -1,18 +1,21 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { api, ApiClientError } from '@/lib/api';
+import {
+  mockFetchError,
+  mockFetchNetworkError,
+  mockFetchNoContent,
+  mockFetchSuccess,
+  mockFetchUnknownError,
+} from '@/test';
 
 describe('api client', () => {
-  const mockFetch = vi.fn();
-  const originalFetch = global.fetch;
-
   beforeEach(() => {
-    global.fetch = mockFetch;
-    vi.clearAllMocks();
+    vi.spyOn(global, 'fetch');
   });
 
   afterEach(() => {
-    global.fetch = originalFetch;
+    vi.restoreAllMocks();
   });
 
   describe('HTTP methods', () => {
@@ -23,15 +26,11 @@ describe('api client', () => {
       { method: 'patch', httpMethod: 'PATCH' },
       { method: 'delete', httpMethod: 'DELETE' },
     ] as const)('$method makes $httpMethod request', async ({ method, httpMethod }) => {
-      mockFetch.mockResolvedValueOnce({
-        ok: true,
-        status: 200,
-        json: () => Promise.resolve({ id: 1 }),
-      });
+      mockFetchSuccess({ id: 1 });
 
       await api[method]('/test');
 
-      expect(mockFetch).toHaveBeenCalledWith(
+      expect(global.fetch).toHaveBeenCalledWith(
         expect.stringContaining('/test'),
         expect.objectContaining({ method: httpMethod }),
       );
@@ -39,30 +38,22 @@ describe('api client', () => {
 
     it('sends request body for POST/PUT/PATCH', async () => {
       const body = { name: 'Test' };
-      mockFetch.mockResolvedValueOnce({
-        ok: true,
-        status: 200,
-        json: () => Promise.resolve({ id: 1 }),
-      });
+      mockFetchSuccess({ id: 1 });
 
       await api.post('/test', body);
 
-      expect(mockFetch).toHaveBeenCalledWith(
+      expect(global.fetch).toHaveBeenCalledWith(
         expect.anything(),
         expect.objectContaining({ body: JSON.stringify(body) }),
       );
     });
 
     it('handles full URL without prepending base URL', async () => {
-      mockFetch.mockResolvedValueOnce({
-        ok: true,
-        status: 200,
-        json: () => Promise.resolve({}),
-      });
+      mockFetchSuccess({});
 
       await api.get('https://external.api/data');
 
-      expect(mockFetch).toHaveBeenCalledWith('https://external.api/data', expect.anything());
+      expect(global.fetch).toHaveBeenCalledWith('https://external.api/data', expect.anything());
     });
   });
 
@@ -71,12 +62,7 @@ describe('api client', () => {
       { status: 404, message: 'Resource not found', hasJson: true },
       { status: 500, message: 'Internal Server Error', hasJson: false },
     ])('handles $status error response', async ({ status, message, hasJson }) => {
-      mockFetch.mockResolvedValueOnce({
-        ok: false,
-        status,
-        statusText: message,
-        json: hasJson ? () => Promise.resolve({ message }) : () => Promise.reject(new Error('No JSON')),
-      });
+      mockFetchError(status, message, hasJson);
 
       const error = (await api.get('/error').catch((e) => e)) as ApiClientError;
 
@@ -87,7 +73,7 @@ describe('api client', () => {
 
     it('handles timeout with TIMEOUT code', async () => {
       vi.useFakeTimers();
-      mockFetch.mockImplementationOnce(
+      vi.mocked(global.fetch).mockImplementationOnce(
         () =>
           new Promise((_, reject) => {
             const error = new Error('Aborted');
@@ -106,20 +92,26 @@ describe('api client', () => {
       vi.useRealTimers();
     });
 
-    it.each([
-      { rejection: new Error('Network failure'), code: 'NETWORK_ERROR' },
-      { rejection: 'string error', code: 'UNKNOWN' },
-    ])('handles $code errors', async ({ rejection, code }) => {
-      mockFetch.mockRejectedValueOnce(rejection);
+    it('handles NETWORK_ERROR', async () => {
+      mockFetchNetworkError();
+
+      const error = (await api.get('/error').catch((e) => e)) as ApiClientError;
+
+      expect(error).toBeInstanceOf(ApiClientError);
+      expect(error.code).toBe('NETWORK_ERROR');
+    });
+
+    it('handles UNKNOWN errors', async () => {
+      mockFetchUnknownError('string error');
 
       const error = (await api.get('/error').catch((e) => e)) as ApiClientError;
 
       expect(error).toBeInstanceOf(ApiClientError);
-      expect(error.code).toBe(code);
+      expect(error.code).toBe('UNKNOWN');
     });
 
     it('returns undefined for 204 No Content', async () => {
-      mockFetch.mockResolvedValueOnce({ ok: true, status: 204 });
+      mockFetchNoContent();
 
       const result = await api.delete('/test/1');
 

package/templates/src/lib/api.ts

@@ -5,13 +5,7 @@
 
 import type { ApiError } from '@/types/api';
 
-/**
- * API configuration.
- */
-export const API_CONFIG = {
-  baseUrl: import.meta.env.VITE_API_URL || 'https://jsonplaceholder.typicode.com',
-  timeout: 30000,
-} as const;
+import { API_CONFIG } from './config';
 
 /**
  * Custom API error class

package/templates/src/lib/config.ts

@@ -1,15 +1,65 @@
 /**
  * Application configuration.
  * Centralized config for feature flags, etc.
+ *
+ * All environment variables flow through the validated `env` object from env.ts.
  */
 
+import { env } from './env';
+
+// =============================================================================
+// App Configuration
+// =============================================================================
+
 export const APP_CONFIG = {
-  name: import.meta.env.VITE_APP_NAME || 'My App',
-  url: import.meta.env.VITE_APP_URL || 'http://localhost:5173',
+  name: env.VITE_APP_NAME,
+  url: env.VITE_APP_URL,
+} as const;
+
+// =============================================================================
+// API Configuration
+// =============================================================================
+
+export const API_CONFIG = {
+  baseUrl: env.VITE_API_URL,
+  timeout: 30000,
 } as const;
 
+// =============================================================================
+// Sentry Configuration
+// =============================================================================
+
 export const SENTRY_CONFIG = {
-  enabled: import.meta.env.VITE_SENTRY_ENABLED !== 'false',
-  dsn: import.meta.env.VITE_SENTRY_DSN,
+  enabled: env.VITE_SENTRY_ENABLED,
+  dsn: env.VITE_SENTRY_DSN,
+  environment: env.MODE,
   tracesSampleRate: 0.1,
 } as const;
+
+// =============================================================================
+// Clerk Configuration
+// =============================================================================
+
+export const CLERK_CONFIG = {
+  publishableKey: env.VITE_CLERK_PUBLISHABLE_KEY,
+} as const;
+
+// =============================================================================
+// Supabase Configuration
+// =============================================================================
+
+export const SUPABASE_CONFIG = {
+  url: env.VITE_SUPABASE_DATABASE_URL,
+  anonKey: env.VITE_SUPABASE_ANON_KEY,
+  /** Whether both URL and anon key are configured */
+  isConfigured: Boolean(env.VITE_SUPABASE_DATABASE_URL && env.VITE_SUPABASE_ANON_KEY),
+} as const;
+
+// =============================================================================
+// Performance Configuration
+// =============================================================================
+
+export const PERFORMANCE_CONFIG = {
+  /** Enable performance tracking in dev or when VITE_PERF_TEST is set */
+  enabled: env.DEV || env.VITE_PERF_TEST,
+} as const;

package/templates/src/lib/env.ts

@@ -1,25 +1,40 @@
 /**
  * Environment variable validation using Zod.
  * Validates at runtime to catch missing/invalid env vars early.
+ *
+ * All env vars are REQUIRED. The MCP scaffold tool strips unused vars
+ * when scaffolding builds without certain features.
  */
 
 import { z } from 'zod';
 
+/**
+ * Transforms string env var to boolean.
+ * - 'true', '1' → true
+ * - 'false', '0' → false
+ */
+const booleanEnv = z.enum(['true', 'false', '1', '0']).transform((val) => val === 'true' || val === '1');
+
 const envSchema = z.object({
-  VITE_APP_NAME: z.string().min(1).optional(),
-  VITE_APP_URL: z.string().url().optional(),
-  VITE_API_URL: z.string().url().optional(),
-  VITE_SENTRY_DSN: z.string().url().optional(),
-  MODE: z.enum(['development', 'production', 'test']).default('development'),
-  DEV: z.boolean().default(false),
-  PROD: z.boolean().default(false),
+  VITE_APP_NAME: z.string().min(1),
+  VITE_APP_URL: z.string().url(),
+  VITE_API_URL: z.string().url(),
+  VITE_SENTRY_DSN: z.string().url(),
+  VITE_SENTRY_ENABLED: booleanEnv,
+  VITE_CLERK_PUBLISHABLE_KEY: z.string().min(1),
+  VITE_SUPABASE_DATABASE_URL: z.string().url(),
+  VITE_SUPABASE_ANON_KEY: z.string().min(1),
+  VITE_PERF_TEST: booleanEnv,
+  MODE: z.enum(['development', 'production', 'test']),
+  DEV: z.boolean(),
+  PROD: z.boolean(),
 });
 
 export type Env = z.infer<typeof envSchema>;
 
 /**
  * Validate environment variables and return typed env object.
- * Throws if validation fails in production.
+ * Throws if any required env var is missing or invalid.
  */
 export function validateEnv(): Env {
   const env = {
@@ -27,6 +42,11 @@ export function validateEnv(): Env {
     VITE_APP_URL: import.meta.env.VITE_APP_URL,
     VITE_API_URL: import.meta.env.VITE_API_URL,
     VITE_SENTRY_DSN: import.meta.env.VITE_SENTRY_DSN,
+    VITE_SENTRY_ENABLED: import.meta.env.VITE_SENTRY_ENABLED,
+    VITE_CLERK_PUBLISHABLE_KEY: import.meta.env.VITE_CLERK_PUBLISHABLE_KEY,
+    VITE_SUPABASE_DATABASE_URL: import.meta.env.VITE_SUPABASE_DATABASE_URL,
+    VITE_SUPABASE_ANON_KEY: import.meta.env.VITE_SUPABASE_ANON_KEY,
+    VITE_PERF_TEST: import.meta.env.VITE_PERF_TEST,
     MODE: import.meta.env.MODE,
     DEV: import.meta.env.DEV,
     PROD: import.meta.env.PROD,
@@ -35,15 +55,17 @@ export function validateEnv(): Env {
   const result = envSchema.safeParse(env);
 
   if (!result.success) {
-    const errors = result.error.format();
-    console.error('Environment validation failed:', errors);
+    const errors = result.error.flatten();
+    const fieldErrors = Object.entries(errors.fieldErrors)
+      .map(([key, msgs]) => `${key}: ${(msgs as string[]).join(', ')}`)
+      .join('; ');
+    const formErrors = errors.formErrors.join('; ');
+    const allErrors = [fieldErrors, formErrors].filter(Boolean).join('; ');
 
-    if (import.meta.env.PROD) {
-      throw new Error('Invalid environment configuration');
-    }
+    throw new Error(`Environment validation failed: ${allErrors}`);
   }
 
-  return result.success ? result.data : (env as Env);
+  return result.data;
 }
 
 /**

package/templates/src/lib/index.ts

@@ -5,11 +5,13 @@
 
 export { cn } from './utils';
 export { STORAGE_KEYS, isAppKey } from './storageKeys';
-export { APP_CONFIG, SENTRY_CONFIG } from './config';
-export { API_CONFIG } from './api';
+export { APP_CONFIG, API_CONFIG, SENTRY_CONFIG, CLERK_CONFIG, SUPABASE_CONFIG, PERFORMANCE_CONFIG } from './config';
 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 { registerFormSchema, type RegisterFormData } from './validations';
 export { createSelectors } from './createSelectors';
+
+// Supabase
+export { createSupabaseClient, type TypedSupabaseClient, type GetTokenFn } from './supabase';

package/templates/src/lib/routes.ts

@@ -5,6 +5,7 @@
 
 export const ROUTES = {
   HOME: '/',
+  PROFILE: '/profile',
   NOT_FOUND: '*',
 } as const;
 

package/templates/src/lib/sentry.ts

@@ -1,29 +1,32 @@
 import type * as SentryType from '@sentry/react';
 
+import { SENTRY_CONFIG } from './config';
+import { env } from './env';
+
 let sentryInstance: typeof SentryType | null = null;
 
 /**
  * Initialize Sentry error tracking.
- * Only runs in production when VITE_SENTRY_DSN is configured.
+ * Only runs in production when enabled and VITE_SENTRY_DSN is configured.
  */
-export async function initSentry(): Promise<void> {
-  // Skip in development or if already initialized
-  if (import.meta.env.DEV || sentryInstance) return;
-
-  const dsn = import.meta.env.VITE_SENTRY_DSN;
-  if (!dsn) return;
+export async function initSentry(): Promise<typeof SentryType | null> {
+  // Skip if disabled, in development, already initialized, or no DSN
+  if (!SENTRY_CONFIG.enabled || env.DEV || sentryInstance || !SENTRY_CONFIG.dsn) {
+    return sentryInstance;
+  }
 
   const sentry = await import('@sentry/react');
 
   sentry.init({
-    dsn,
-    environment: import.meta.env.MODE,
+    dsn: SENTRY_CONFIG.dsn,
+    environment: SENTRY_CONFIG.environment,
     sendDefaultPii: true,
     integrations: [sentry.browserTracingIntegration()],
-    tracesSampleRate: 0.1,
+    tracesSampleRate: SENTRY_CONFIG.tracesSampleRate,
   });
 
   sentryInstance = sentry;
+  return sentryInstance;
 }
 
 /**

package/templates/src/lib/supabase/client.ts

@@ -0,0 +1,58 @@
+/**
+ * Supabase client factory with Clerk authentication integration.
+ *
+ * Uses the modern `accessToken` pattern for third-party auth providers.
+ * The Clerk session token is automatically injected into Supabase requests.
+ *
+ * @see https://supabase.com/docs/guides/auth/third-party/clerk
+ */
+
+import { createClient, type SupabaseClient } from '@supabase/supabase-js';
+
+import type { Database } from '@/types/database';
+
+import { SUPABASE_CONFIG } from '../config';
+
+/**
+ * Typed Supabase client with database schema.
+ */
+export type TypedSupabaseClient = SupabaseClient<Database>;
+
+/**
+ * Token getter function type.
+ * Returns the Clerk session token or null if not authenticated.
+ */
+export type GetTokenFn = () => Promise<string | null>;
+
+/**
+ * Creates a Supabase client configured with Clerk authentication.
+ *
+ * Uses the `accessToken` configuration option which is the recommended
+ * approach for third-party auth providers like Clerk.
+ *
+ * @param getToken - Async function that returns the Clerk session token
+ * @returns Typed Supabase client
+ * @throws Error if Supabase environment variables are not configured
+ *
+ * @example
+ * ```tsx
+ * const { session } = useSession();
+ * const supabase = createSupabaseClient(() => session?.getToken() ?? null);
+ *
+ * // Now use supabase with Clerk auth
+ * const { data } = await supabase.from('profiles').select();
+ * ```
+ */
+export function createSupabaseClient(getToken: GetTokenFn): TypedSupabaseClient {
+  if (!SUPABASE_CONFIG.isConfigured) {
+    throw new Error(
+      'Missing Supabase environment variables. ' +
+        'Set VITE_SUPABASE_DATABASE_URL and VITE_SUPABASE_ANON_KEY in your .env file.',
+    );
+  }
+
+  // Type assertion safe here - isConfigured guarantees both are defined
+  return createClient<Database>(SUPABASE_CONFIG.url!, SUPABASE_CONFIG.anonKey!, {
+    accessToken: getToken,
+  });
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Supabase client exports.
+ */
+
+export { createSupabaseClient, type TypedSupabaseClient, type GetTokenFn } from './client';