create-blitzpack 0.1.0

package/template/apps/web/src/hooks/api/use-users.ts

@@ -0,0 +1,149 @@
+import type {
+  PaginatedResponse,
+  QueryUsers,
+} from '@repo/packages-types/pagination';
+import type { CreateUser, UpdateUser, User } from '@repo/packages-types/user';
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type UseQueryOptions,
+} from '@tanstack/react-query';
+
+import { api } from '@/lib/api';
+
+/**
+ * Query Keys
+ * Centralized query keys for cache management and invalidation
+ */
+export const userKeys = {
+  all: ['users'] as const,
+  lists: () => [...userKeys.all, 'list'] as const,
+  list: (params: QueryUsers) => [...userKeys.lists(), params] as const,
+  details: () => [...userKeys.all, 'detail'] as const,
+  detail: (id: string) => [...userKeys.details(), id] as const,
+};
+
+/**
+ * Fetch paginated users with filtering and sorting
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error } = useFetchUsers({
+ *   page: 1,
+ *   limit: 10,
+ *   search: 'john',
+ *   sortBy: 'createdAt',
+ *   sortOrder: 'desc'
+ * });
+ * ```
+ */
+export function useFetchUsers(
+  params: QueryUsers,
+  options?: Omit<
+    UseQueryOptions<PaginatedResponse<User>>,
+    'queryKey' | 'queryFn'
+  >
+) {
+  return useQuery({
+    queryKey: userKeys.list(params),
+    queryFn: () =>
+      api.get<PaginatedResponse<User>>('/users', {
+        params: params as Record<string, string | number | boolean>,
+      }),
+    ...options,
+  });
+}
+
+/**
+ * Fetch a single user by ID
+ *
+ * @example
+ * ```tsx
+ * const { data: user, isLoading } = useFetchUser('123e4567-e89b-12d3-a456-426614174000');
+ * ```
+ */
+export function useFetchUser(
+  id: string,
+  options?: Omit<UseQueryOptions<User>, 'queryKey' | 'queryFn'>
+) {
+  return useQuery({
+    queryKey: userKeys.detail(id),
+    queryFn: () => api.get<User>(`/users/${id}`),
+    enabled: !!id,
+    ...options,
+  });
+}
+
+/**
+ * Create a new user
+ *
+ * @example
+ * ```tsx
+ * const { mutate: createUser, isPending } = useCreateUser();
+ *
+ * const handleSubmit = (data: CreateUser) => {
+ *   createUser(data);
+ * };
+ * ```
+ */
+export function useCreateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: CreateUser) => api.post<User>('/users', data),
+    onSuccess: (user) => {
+      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
+      queryClient.setQueryData(userKeys.detail(user.id), user);
+    },
+  });
+}
+
+/**
+ * Update an existing user
+ *
+ * @example
+ * ```tsx
+ * const { mutate: updateUser, isPending } = useUpdateUser();
+ *
+ * const handleUpdate = (id: string, data: UpdateUser) => {
+ *   updateUser({ id, data });
+ * };
+ * ```
+ */
+export function useUpdateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: UpdateUser }) =>
+      api.patch<User>(`/users/${id}`, data),
+    onSuccess: (user) => {
+      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
+      queryClient.setQueryData(userKeys.detail(user.id), user);
+    },
+  });
+}
+
+/**
+ * Delete a user
+ *
+ * @example
+ * ```tsx
+ * const { mutate: deleteUser, isPending } = useDeleteUser();
+ *
+ * const handleDelete = (id: string) => {
+ *   deleteUser(id);
+ * };
+ * ```
+ */
+export function useDeleteUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (id: string) => api.delete(`/users/${id}`),
+    onSuccess: (_, id) => {
+      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
+      queryClient.removeQueries({ queryKey: userKeys.detail(id) });
+    },
+  });
+}

package/template/apps/web/src/hooks/use-mobile.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+
+const MOBILE_BREAKPOINT = 768;
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(
+    undefined
+  );
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    };
+    mql.addEventListener('change', onChange);
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    return () => mql.removeEventListener('change', onChange);
+  }, []);
+
+  return !!isMobile;
+}

package/template/apps/web/src/hooks/use-realtime-metrics.ts

@@ -0,0 +1,120 @@
+import type { RealtimeMetricsPoint } from '@repo/packages-types/stats';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { env } from '@/lib/env';
+
+interface UseRealtimeMetricsOptions {
+  enabled?: boolean;
+  maxDataPoints?: number;
+}
+
+interface UseRealtimeMetricsResult {
+  data: RealtimeMetricsPoint[];
+  isConnected: boolean;
+  error: Error | null;
+  reconnect: () => void;
+}
+
+export function useRealtimeMetrics(
+  options: UseRealtimeMetricsOptions = {}
+): UseRealtimeMetricsResult {
+  const { enabled = true, maxDataPoints = 60 } = options;
+
+  const [data, setData] = useState<RealtimeMetricsPoint[]>([]);
+  const [isConnected, setIsConnected] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const eventSourceRef = useRef<EventSource | null>(null);
+  const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const reconnectAttempts = useRef(0);
+  const connectRef = useRef<(() => void) | null>(null);
+
+  const connect = useCallback(() => {
+    if (eventSourceRef.current) {
+      eventSourceRef.current.close();
+    }
+
+    const url = `${env.apiUrl}/admin/metrics/stream`;
+
+    const es = new EventSource(url, { withCredentials: true });
+    eventSourceRef.current = es;
+
+    es.onopen = () => {
+      setIsConnected(true);
+      setError(null);
+      reconnectAttempts.current = 0;
+    };
+
+    es.addEventListener('history', (event: MessageEvent) => {
+      try {
+        const history = JSON.parse(event.data) as RealtimeMetricsPoint[];
+        setData(history.slice(-maxDataPoints));
+      } catch (e) {
+        console.error('Failed to parse history:', e);
+      }
+    });
+
+    es.addEventListener('metrics', (event: MessageEvent) => {
+      try {
+        const metrics = JSON.parse(event.data) as RealtimeMetricsPoint;
+        setData((prev) => {
+          const updated = [...prev, metrics];
+          return updated.slice(-maxDataPoints);
+        });
+      } catch (e) {
+        console.error('Failed to parse metrics:', e);
+      }
+    });
+
+    es.onerror = () => {
+      setIsConnected(false);
+      es.close();
+      eventSourceRef.current = null;
+
+      const backoff = Math.min(
+        1000 * Math.pow(2, reconnectAttempts.current),
+        30000
+      );
+      reconnectAttempts.current++;
+
+      setError(new Error('Connection lost. Reconnecting...'));
+
+      reconnectTimeoutRef.current = setTimeout(() => {
+        if (enabled) {
+          connectRef.current?.();
+        }
+      }, backoff);
+    };
+  }, [enabled, maxDataPoints]);
+
+  useEffect(() => {
+    connectRef.current = connect;
+  }, [connect]);
+
+  const reconnect = useCallback(() => {
+    reconnectAttempts.current = 0;
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current);
+    }
+    connect();
+  }, [connect]);
+
+  useEffect(() => {
+    if (enabled) {
+      connect();
+    }
+
+    return () => {
+      if (eventSourceRef.current) {
+        eventSourceRef.current.close();
+        eventSourceRef.current = null;
+      }
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+        reconnectTimeoutRef.current = null;
+      }
+    };
+  }, [enabled, connect]);
+
+  return { data, isConnected, error, reconnect };
+}

package/template/apps/web/src/lib/__tests__/utils.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import { cn } from '@/lib/utils';
+
+describe('cn', () => {
+  it('should merge class names', () => {
+    expect(cn('px-2 py-1', 'bg-red-500')).toBe('px-2 py-1 bg-red-500');
+  });
+
+  it('should handle conflicting Tailwind classes', () => {
+    expect(cn('px-2', 'px-4')).toBe('px-4');
+  });
+
+  it('should handle conditional classes', () => {
+    const isActive = true;
+    const isDisabled = false;
+    expect(cn('base', isActive && 'active', isDisabled && 'disabled')).toBe(
+      'base active'
+    );
+  });
+
+  it('should handle undefined and null', () => {
+    expect(cn('base', undefined, null)).toBe('base');
+  });
+
+  it('should handle arrays', () => {
+    expect(cn(['px-2', 'py-1'])).toBe('px-2 py-1');
+  });
+});

package/template/apps/web/src/lib/api.ts

@@ -0,0 +1,151 @@
+import { env } from './env';
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public data?: unknown
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+interface FetcherOptions extends RequestInit {
+  params?: Record<string, string | number | boolean>;
+  timeout?: number;
+}
+
+export async function fetcher<T>(
+  endpoint: string,
+  options: FetcherOptions = {}
+): Promise<T> {
+  const { params, timeout, signal, ...init } = options;
+
+  // Build URL with query params
+  const url = new URL(`${env.apiUrl}${endpoint}`);
+  if (params) {
+    Object.entries(params).forEach(([key, value]) => {
+      url.searchParams.append(key, String(value));
+    });
+  }
+
+  // Handle timeout with AbortController
+  const controller = new AbortController();
+  const timeoutId = timeout
+    ? setTimeout(() => controller.abort(), timeout)
+    : null;
+
+  // Combine with external signal if provided
+  if (signal) {
+    signal.addEventListener('abort', () => controller.abort());
+  }
+
+  try {
+    const response = await fetch(url.toString(), {
+      ...init,
+      signal: controller.signal,
+      headers: {
+        ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+        ...init.headers,
+      },
+      credentials: 'include',
+    });
+
+    if (timeoutId) clearTimeout(timeoutId);
+
+    // Parse response based on content type
+    let data: unknown;
+    const contentType = response.headers.get('content-type');
+
+    if (contentType?.includes('application/json')) {
+      data = await response.json();
+    } else {
+      data = await response.text();
+    }
+
+    if (!response.ok) {
+      const errorData = data as {
+        error?: { message?: string; code?: string; details?: unknown };
+        message?: string;
+      };
+
+      const errorMessage =
+        errorData.error?.message ||
+        errorData.message ||
+        `HTTP ${response.status}`;
+
+      throw new ApiError(errorMessage, response.status, data);
+    }
+
+    // Unwrap { data: T } or { message: string } wrappers from backend
+    // BUT preserve pagination responses ({ data: T[], pagination: {...} })
+    const wrappedData = data as
+      | { data: T; pagination?: unknown }
+      | { message: string }
+      | T
+      | undefined;
+
+    if (wrappedData && typeof wrappedData === 'object') {
+      // Don't unwrap if it has pagination metadata (paginated responses)
+      if ('data' in wrappedData && 'pagination' in wrappedData) {
+        return wrappedData as T;
+      }
+      // Unwrap single data responses
+      if ('data' in wrappedData) {
+        return wrappedData.data as T;
+      }
+      if ('message' in wrappedData) {
+        return wrappedData as T;
+      }
+    }
+
+    return data as T;
+  } catch (error) {
+    if (timeoutId) clearTimeout(timeoutId);
+
+    // Re-throw ApiError as-is
+    if (error instanceof ApiError) {
+      throw error;
+    }
+
+    // Handle timeout
+    if (error instanceof Error && error.name === 'AbortError') {
+      throw new Error('Request timeout');
+    }
+
+    throw error;
+  }
+}
+
+export const api = {
+  get: <T>(url: string, options?: FetcherOptions) =>
+    fetcher<T>(url, { ...options, method: 'GET' }),
+
+  post: <T>(url: string, body?: unknown, options?: FetcherOptions) =>
+    fetcher<T>(url, { ...options, method: 'POST', body: JSON.stringify(body) }),
+
+  put: <T>(url: string, body?: unknown, options?: FetcherOptions) =>
+    fetcher<T>(url, { ...options, method: 'PUT', body: JSON.stringify(body) }),
+
+  patch: <T>(url: string, body?: unknown, options?: FetcherOptions) =>
+    fetcher<T>(url, {
+      ...options,
+      method: 'PATCH',
+      body: JSON.stringify(body),
+    }),
+
+  delete: <T>(url: string, options?: FetcherOptions) =>
+    fetcher<T>(url, { ...options, method: 'DELETE' }),
+};
+
+// Error helpers
+export function isApiError(error: unknown): error is ApiError {
+  return error instanceof ApiError;
+}
+
+export function getErrorMessage(error: unknown): string {
+  if (isApiError(error)) return error.message;
+  if (error instanceof Error) return error.message;
+  return 'An unexpected error occurred';
+}

package/template/apps/web/src/lib/auth.ts

@@ -0,0 +1,13 @@
+import { adminClient } from 'better-auth/client/plugins';
+import { createAuthClient } from 'better-auth/react';
+
+import { env } from '@/lib/env';
+
+export const authClient = createAuthClient({
+  baseURL: `${env.apiUrl}/auth`,
+  plugins: [adminClient()],
+  // ! IMPORTANT: Enable credentials to send/receive cookies cross-domain
+  fetchOptions: {
+    credentials: 'include',
+  },
+});

package/template/apps/web/src/lib/env.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+
+/**
+ * Client-side environment variable validation
+ *
+ * IMPORTANT: Only NEXT_PUBLIC_* variables are exposed to the browser
+ * All other env vars are server-side only and should NOT be included here
+ */
+const envSchema = z.object({
+  NEXT_PUBLIC_API_URL: z
+    .string()
+    .url('NEXT_PUBLIC_API_URL must be a valid URL')
+    .min(1, 'NEXT_PUBLIC_API_URL is required'),
+  NODE_ENV: z
+    .enum(['development', 'production', 'test'])
+    .default('development'),
+});
+
+/**
+ * Validate and parse environment variables
+ * Throws if validation fails, preventing the app from running with invalid config
+ */
+function validateEnv() {
+  try {
+    return envSchema.parse({
+      NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
+      NODE_ENV: process.env.NODE_ENV,
+    });
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error('❌ Invalid environment variables:', error.issues);
+      throw new Error(
+        `Environment validation failed: ${error.issues.map((e) => `${e.path.join('.')}: ${e.message}`).join(', ')}`
+      );
+    }
+    throw error;
+  }
+}
+
+// Validate on module load (fails fast if config is wrong)
+const validatedEnv = validateEnv();
+
+// Environment helpers
+export const isDevelopment = () => validatedEnv.NODE_ENV === 'development';
+export const isProduction = () => validatedEnv.NODE_ENV === 'production';
+export const isTest = () => validatedEnv.NODE_ENV === 'test';
+
+// Client-side environment variables (type-safe and validated)
+export const env = {
+  apiUrl: validatedEnv.NEXT_PUBLIC_API_URL,
+  nodeEnv: validatedEnv.NODE_ENV,
+} as const;

package/template/apps/web/src/lib/form-utils.ts

@@ -0,0 +1,11 @@
+import { zodResolver } from '@hookform/resolvers/zod';
+
+/**
+ * Create a type-safe form resolver from a Zod schema
+ * Usage: const form = useForm({ resolver: createFormResolver(MySchema) })
+ */
+export function createFormResolver<T extends Parameters<typeof zodResolver>[0]>(
+  schema: T
+) {
+  return zodResolver(schema);
+}

package/template/apps/web/src/lib/utils.ts

@@ -0,0 +1 @@
+export { cn } from '@repo/packages-ui/lib/utils';

package/template/apps/web/src/providers.tsx

@@ -0,0 +1,34 @@
+'use client';
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ThemeProvider } from 'next-themes';
+import { useState } from 'react';
+
+function QueryProvider({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            staleTime: 60 * 1000,
+            refetchOnWindowFocus: false,
+            retry: 1,
+          },
+        },
+      })
+  );
+
+  return (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <QueryProvider>
+      <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+        {children}
+      </ThemeProvider>
+    </QueryProvider>
+  );
+}

package/template/apps/web/src/store/atoms.ts

@@ -0,0 +1,15 @@
+import { atom } from 'jotai';
+
+// Example atoms - you can extend these based on your needs
+
+// User preference example
+export const userPreferenceAtom = atom<{
+  sidebarCollapsed: boolean;
+  notificationsEnabled: boolean;
+}>({
+  sidebarCollapsed: false,
+  notificationsEnabled: true,
+});
+
+// Counter example (for demonstration)
+export const counterAtom = atom(0);

package/template/apps/web/src/test/helpers/test-utils.tsx

@@ -0,0 +1,44 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import {
+  render,
+  type RenderOptions,
+  type RenderResult,
+} from '@testing-library/react';
+import { type ReactElement, type ReactNode } from 'react';
+
+interface AllTheProvidersProps {
+  children: ReactNode;
+}
+
+function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+      },
+      mutations: {
+        retry: false,
+      },
+    },
+  });
+}
+
+export function AllTheProviders({ children }: AllTheProvidersProps) {
+  const testQueryClient = createTestQueryClient();
+
+  return (
+    <QueryClientProvider client={testQueryClient}>
+      {children}
+    </QueryClientProvider>
+  );
+}
+
+export function renderWithProviders(
+  ui: ReactElement,
+  options?: Omit<RenderOptions, 'wrapper'>
+): RenderResult {
+  return render(ui, { wrapper: AllTheProviders, ...options });
+}
+
+export * from '@testing-library/react';
+export { renderWithProviders as render };

package/template/apps/web/src/test/setup.ts

@@ -0,0 +1,8 @@
+import '@testing-library/jest-dom/vitest';
+
+import { cleanup } from '@testing-library/react';
+import { afterEach } from 'vitest';
+
+afterEach(() => {
+  cleanup();
+});

package/template/apps/web/tailwind.config.ts

@@ -0,0 +1,5 @@
+import type { Config } from 'tailwindcss';
+
+const config: Config = {};
+
+export default config;

package/template/apps/web/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "jsx": "preserve",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "baseUrl": "../../",
+    "paths": {
+      "@/*": ["apps/web/src/*"]
+    },
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "incremental": true
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}