create-react-forge 1.0.1 → 1.0.3

package/src/templates/overlays/base/src/lib/api-client.ts

@@ -0,0 +1,101 @@
+/**
+ * API Client - Centralized HTTP client following bulletproof-react patterns
+ * Replace with your actual API configuration
+ */
+
+export type RequestConfig = {
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  headers?: Record<string, string>;
+  body?: unknown;
+  params?: Record<string, string | number | boolean>;
+};
+
+export type ApiResponse<T> = {
+  data: T;
+  status: number;
+};
+
+const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:3001';
+
+/**
+ * Build URL with query parameters
+ */
+function buildUrl(endpoint: string, params?: Record<string, string | number | boolean>): string {
+  const url = new URL(endpoint, API_URL);
+  
+  if (params) {
+    Object.entries(params).forEach(([key, value]) => {
+      url.searchParams.append(key, String(value));
+    });
+  }
+  
+  return url.toString();
+}
+
+/**
+ * Get authorization headers (customize based on your auth strategy)
+ */
+function getAuthHeaders(): Record<string, string> {
+  const token = localStorage.getItem('token');
+  
+  if (token) {
+    return { Authorization: `Bearer ${token}` };
+  }
+  
+  return {};
+}
+
+/**
+ * Main API client function
+ */
+export async function apiClient<T>(
+  endpoint: string,
+  config: RequestConfig = {}
+): Promise<ApiResponse<T>> {
+  const { method = 'GET', headers = {}, body, params } = config;
+
+  const url = buildUrl(endpoint, params);
+
+  const response = await fetch(url, {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      ...getAuthHeaders(),
+      ...headers,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}));
+    throw new Error(error.message || `HTTP error! status: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  return {
+    data,
+    status: response.status,
+  };
+}
+
+/**
+ * Convenience methods
+ */
+export const api = {
+  get: <T>(endpoint: string, params?: Record<string, string | number | boolean>) =>
+    apiClient<T>(endpoint, { method: 'GET', params }),
+
+  post: <T>(endpoint: string, body: unknown) =>
+    apiClient<T>(endpoint, { method: 'POST', body }),
+
+  put: <T>(endpoint: string, body: unknown) =>
+    apiClient<T>(endpoint, { method: 'PUT', body }),
+
+  patch: <T>(endpoint: string, body: unknown) =>
+    apiClient<T>(endpoint, { method: 'PATCH', body }),
+
+  delete: <T>(endpoint: string) =>
+    apiClient<T>(endpoint, { method: 'DELETE' }),
+};
+

package/src/templates/overlays/base/src/lib/utils.ts

@@ -0,0 +1,34 @@
+import { clsx, type ClassValue } from 'clsx';
+
+/**
+ * Utility function for constructing className strings conditionally
+ */
+export function cn(...inputs: ClassValue[]) {
+  return clsx(inputs);
+}
+
+/**
+ * Format a date to a human-readable string
+ */
+export function formatDate(date: Date | string): string {
+  return new Intl.DateTimeFormat('en-US', {
+    month: 'long',
+    day: 'numeric',
+    year: 'numeric',
+  }).format(new Date(date));
+}
+
+/**
+ * Delay execution for a specified number of milliseconds
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Generate a unique ID
+ */
+export function generateId(): string {
+  return Math.random().toString(36).substring(2, 9);
+}
+

package/src/templates/overlays/base/src/types/api.ts

@@ -0,0 +1,47 @@
+/**
+ * Common API types following bulletproof-react patterns
+ */
+
+export type BaseEntity = {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type PaginatedResponse<T> = {
+  data: T[];
+  meta: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+  };
+};
+
+export type ApiError = {
+  message: string;
+  statusCode: number;
+  errors?: Record<string, string[]>;
+};
+
+export type User = BaseEntity & {
+  email: string;
+  name: string;
+  avatar?: string;
+  role: 'admin' | 'user';
+};
+
+export type AuthResponse = {
+  user: User;
+  token: string;
+};
+
+export type LoginCredentials = {
+  email: string;
+  password: string;
+};
+
+export type RegisterCredentials = LoginCredentials & {
+  name: string;
+};
+

package/src/templates/overlays/features/tanstack-query/manifest.json

@@ -0,0 +1,17 @@
+{
+  "name": "feature-tanstack-query",
+  "version": "1.0.0",
+  "description": "TanStack Query (React Query) data fetching setup",
+  "compatibleWith": ["runtime-vite", "runtime-nextjs"],
+  "dependencies": {
+    "@tanstack/react-query": "^5.60.0",
+    "@tanstack/react-query-devtools": "^5.60.0"
+  },
+  "devDependencies": {},
+  "scripts": {},
+  "filePatterns": {
+    "include": ["**/*"],
+    "exclude": ["manifest.json"]
+  }
+}
+

package/src/templates/overlays/features/tanstack-query/src/features/users/api/create-user.ts

@@ -0,0 +1,41 @@
+import { api } from '@/lib/api-client';
+import type { User } from '@/types/api';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { usersKeys } from './get-users';
+
+/**
+ * Mutation hook for creating a user
+ * Following bulletproof-react patterns with optimistic updates
+ */
+
+type CreateUserData = {
+  name: string;
+  email: string;
+};
+
+async function createUser(data: CreateUserData) {
+  const response = await api.post<User>('/api/users', data);
+  return response.data;
+}
+
+type UseCreateUserOptions = {
+  onSuccess?: (user: User) => void;
+  onError?: (error: Error) => void;
+};
+
+export function useCreateUser(options: UseCreateUserOptions = {}) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createUser,
+    onSuccess: (data) => {
+      // Invalidate and refetch users list
+      queryClient.invalidateQueries({ queryKey: usersKeys.lists() });
+      options.onSuccess?.(data);
+    },
+    onError: (error) => {
+      options.onError?.(error as Error);
+    },
+  });
+}
+

package/src/templates/overlays/features/tanstack-query/src/features/users/api/get-user.ts

@@ -0,0 +1,27 @@
+import { useQuery } from '@tanstack/react-query';
+import { api } from '@/lib/api-client';
+import type { User } from '@/types/api';
+import { usersKeys } from './get-users';
+
+/**
+ * Query hook for fetching a single user
+ */
+
+async function getUser(userId: string) {
+  const response = await api.get<User>(`/api/users/${userId}`);
+  return response.data;
+}
+
+type UseUserOptions = {
+  userId: string;
+  enabled?: boolean;
+};
+
+export function useUser({ userId, enabled = true }: UseUserOptions) {
+  return useQuery({
+    queryKey: usersKeys.detail(userId),
+    queryFn: () => getUser(userId),
+    enabled,
+  });
+}
+

package/src/templates/overlays/features/tanstack-query/src/features/users/api/get-users.ts

@@ -0,0 +1,39 @@
+import { useQuery } from '@tanstack/react-query';
+import { api } from '@/lib/api-client';
+import type { User, PaginatedResponse } from '@/types/api';
+
+/**
+ * Example query hook following bulletproof-react patterns
+ * Each feature has its own API folder with typed query hooks
+ */
+
+type GetUsersParams = {
+  page?: number;
+  limit?: number;
+};
+
+async function getUsers(params: GetUsersParams = {}) {
+  const { page = 1, limit = 10 } = params;
+  const response = await api.get<PaginatedResponse<User>>('/api/users', {
+    page,
+    limit,
+  });
+  return response.data;
+}
+
+export function useUsers(params: GetUsersParams = {}) {
+  return useQuery({
+    queryKey: ['users', params],
+    queryFn: () => getUsers(params),
+  });
+}
+
+// Query key factory for better organization
+export const usersKeys = {
+  all: ['users'] as const,
+  lists: () => [...usersKeys.all, 'list'] as const,
+  list: (params: GetUsersParams) => [...usersKeys.lists(), params] as const,
+  details: () => [...usersKeys.all, 'detail'] as const,
+  detail: (id: string) => [...usersKeys.details(), id] as const,
+};
+

package/src/templates/overlays/features/tanstack-query/src/hooks/use-query-config.ts

@@ -0,0 +1,42 @@
+import { useQueryClient } from '@tanstack/react-query';
+
+/**
+ * Hook to access and manage the query client
+ * Following bulletproof-react patterns
+ */
+export function useQueryConfig() {
+  const queryClient = useQueryClient();
+
+  const invalidateQueries = (queryKey: string[]) => {
+    return queryClient.invalidateQueries({ queryKey });
+  };
+
+  const prefetchQuery = <T>(
+    queryKey: string[],
+    queryFn: () => Promise<T>
+  ) => {
+    return queryClient.prefetchQuery({ queryKey, queryFn });
+  };
+
+  const setQueryData = <T>(queryKey: string[], data: T) => {
+    return queryClient.setQueryData(queryKey, data);
+  };
+
+  const getQueryData = <T>(queryKey: string[]): T | undefined => {
+    return queryClient.getQueryData(queryKey);
+  };
+
+  const removeQueries = (queryKey: string[]) => {
+    return queryClient.removeQueries({ queryKey });
+  };
+
+  return {
+    queryClient,
+    invalidateQueries,
+    prefetchQuery,
+    setQueryData,
+    getQueryData,
+    removeQueries,
+  };
+}
+

package/src/templates/overlays/features/tanstack-query/src/lib/QueryProvider.tsx

@@ -0,0 +1,28 @@
+'use client';
+
+import { useState } from 'react';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+import { createQueryClient } from './react-query';
+
+type QueryProviderProps = {
+  children: React.ReactNode;
+};
+
+/**
+ * React Query Provider with DevTools
+ * Wrap your app with this component to enable data fetching
+ */
+export function QueryProvider({ children }: QueryProviderProps) {
+  // Create a new QueryClient instance for each request (for SSR)
+  // but reuse the same instance on client-side navigation
+  const [queryClient] = useState(() => createQueryClient());
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
+}
+

package/src/templates/overlays/features/tanstack-query/src/lib/react-query.ts

@@ -0,0 +1,46 @@
+import { DefaultOptions, QueryClient } from '@tanstack/react-query';
+
+/**
+ * React Query configuration following bulletproof-react patterns
+ */
+
+const queryConfig: DefaultOptions = {
+  queries: {
+    // Stale time: 1 minute
+    staleTime: 1000 * 60,
+    // Don't refetch on window focus by default
+    refetchOnWindowFocus: false,
+    // Retry failed requests once
+    retry: 1,
+    // Retry delay
+    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
+  },
+  mutations: {
+    // Don't retry mutations by default
+    retry: false,
+  },
+};
+
+export function createQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: queryConfig,
+  });
+}
+
+// Singleton query client for client-side usage
+let browserQueryClient: QueryClient | undefined = undefined;
+
+export function getQueryClient(): QueryClient {
+  if (typeof window === 'undefined') {
+    // Server: always create a new query client
+    return createQueryClient();
+  }
+
+  // Browser: create once and reuse
+  if (!browserQueryClient) {
+    browserQueryClient = createQueryClient();
+  }
+
+  return browserQueryClient;
+}
+

package/src/templates/overlays/runtime/nextjs/manifest.json

@@ -0,0 +1,27 @@
+{
+  "name": "runtime-nextjs",
+  "version": "1.0.0",
+  "description": "Next.js App Router runtime following bulletproof-react patterns",
+  "compatibleWith": ["base"],
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "next": "^14.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@types/node": "^20.0.0"
+  },
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "filePatterns": {
+    "include": ["**/*"],
+    "exclude": ["manifest.json"]
+  }
+}
+

package/src/templates/overlays/runtime/nextjs/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/basic-features/typescript for more information.
+

package/src/templates/overlays/runtime/nextjs/next.config.js

@@ -0,0 +1,12 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  poweredByHeader: false,
+  // Enable experimental features if needed
+  // experimental: {
+  //   serverActions: true,
+  // },
+};
+
+module.exports = nextConfig;
+

package/src/templates/overlays/runtime/nextjs/src/app/error.tsx

@@ -0,0 +1,34 @@
+'use client';
+
+import { useEffect } from 'react';
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  useEffect(() => {
+    // Log the error to an error reporting service
+    console.error(error);
+  }, [error]);
+
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center" role="alert">
+      <div className="text-center">
+        <h1 className="text-2xl font-bold text-red-600">Something went wrong</h1>
+        <p className="mt-4 text-gray-600">
+          {error.message || 'An unexpected error occurred'}
+        </p>
+        <button
+          onClick={reset}
+          className="mt-6 rounded-md bg-indigo-600 px-3.5 py-2.5 text-sm font-semibold text-white shadow-sm hover:bg-indigo-500"
+        >
+          Try again
+        </button>
+      </div>
+    </div>
+  );
+}
+

package/src/templates/overlays/runtime/nextjs/src/app/layout.tsx

@@ -0,0 +1,23 @@
+import '@/styles/globals.css';
+import type { Metadata } from 'next';
+import { Providers } from './providers';
+
+export const metadata: Metadata = {
+  title: '{{PROJECT_NAME}}',
+  description: 'A production-ready Next.js application',
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+

package/src/templates/overlays/runtime/nextjs/src/app/loading.tsx

@@ -0,0 +1,12 @@
+export default function Loading() {
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <div
+        className="h-8 w-8 animate-spin rounded-full border-2 border-gray-300 border-t-indigo-600"
+        role="status"
+        aria-label="Loading"
+      />
+    </div>
+  );
+}
+

package/src/templates/overlays/runtime/nextjs/src/app/not-found.tsx

@@ -0,0 +1,26 @@
+import Link from 'next/link';
+
+export default function NotFound() {
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center">
+      <div className="text-center">
+        <p className="text-base font-semibold text-indigo-600">404</p>
+        <h1 className="mt-4 text-3xl font-bold tracking-tight sm:text-5xl">
+          Page not found
+        </h1>
+        <p className="mt-6 text-base leading-7 text-gray-600">
+          Sorry, we couldn't find the page you're looking for.
+        </p>
+        <div className="mt-10 flex items-center justify-center gap-x-6">
+          <Link
+            href="/"
+            className="rounded-md bg-indigo-600 px-3.5 py-2.5 text-sm font-semibold text-white shadow-sm hover:bg-indigo-500 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600"
+          >
+            Go back home
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}
+

package/src/templates/overlays/runtime/nextjs/src/app/page.tsx

@@ -0,0 +1,33 @@
+import Link from 'next/link';
+
+export default function HomePage() {
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-4xl font-bold tracking-tight sm:text-6xl">
+          Welcome to Your App
+        </h1>
+        <p className="mt-6 text-lg leading-8 text-gray-600">
+          A production-ready Next.js application scaffolded with create-react-forge.
+        </p>
+        <div className="mt-10 flex items-center justify-center gap-x-6">
+          <Link
+            href="/dashboard"
+            className="rounded-md bg-indigo-600 px-3.5 py-2.5 text-sm font-semibold text-white shadow-sm hover:bg-indigo-500 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600"
+          >
+            Get started
+          </Link>
+          <a
+            href="https://github.com/alan2207/bulletproof-react"
+            className="text-sm font-semibold leading-6"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Learn more <span aria-hidden="true">→</span>
+          </a>
+        </div>
+      </div>
+    </div>
+  );
+}
+

package/src/templates/overlays/runtime/nextjs/src/app/providers.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import { ReactNode } from 'react';
+
+type ProvidersProps = {
+  children: ReactNode;
+};
+
+export function Providers({ children }: ProvidersProps) {
+  // Add providers here (React Query, Theme, etc.)
+  // They will be added by feature overlays
+  return <>{children}</>;
+}
+

package/src/templates/overlays/runtime/nextjs/src/styles/globals.css

@@ -0,0 +1,50 @@
+/* Base styles - will be enhanced by styling overlay (tailwind/css-modules) */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+* {
+  margin: 0;
+}
+
+html,
+body {
+  height: 100%;
+}
+
+body {
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+    'Helvetica Neue', Arial, sans-serif;
+}
+
+img,
+picture,
+video,
+canvas,
+svg {
+  display: block;
+  max-width: 100%;
+}
+
+input,
+button,
+textarea,
+select {
+  font: inherit;
+}
+
+p,
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  overflow-wrap: break-word;
+}
+