@react-spa-scaffold/mcp 0.3.0

package/templates/src/lib/api.ts

@@ -0,0 +1,142 @@
+/**
+ * API client abstraction.
+ * Provides a centralized, typed API layer with error handling.
+ */
+
+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;
+
+/**
+ * Custom API error class
+ */
+export class ApiClientError extends Error {
+  status: number;
+  code?: string;
+
+  constructor(message: string, status: number, code?: string) {
+    super(message);
+    this.name = 'ApiClientError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/**
+ * Request options extending standard fetch options
+ */
+interface RequestOptions extends Omit<RequestInit, 'body'> {
+  body?: unknown;
+  timeout?: number;
+}
+
+/**
+ * Create an AbortController with timeout
+ */
+function createTimeoutController(timeout: number): { controller: AbortController; timeoutId: NodeJS.Timeout } {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  return { controller, timeoutId };
+}
+
+/**
+ * Parse API error response
+ */
+async function parseErrorResponse(response: Response): Promise<ApiError> {
+  try {
+    const data = await response.json();
+    return {
+      message: data.message || data.error || response.statusText,
+      code: data.code,
+      status: response.status,
+    };
+  } catch {
+    return {
+      message: response.statusText || 'An error occurred',
+      status: response.status,
+    };
+  }
+}
+
+/**
+ * Core request function
+ */
+async function request<T>(endpoint: string, options: RequestOptions = {}): Promise<T> {
+  const { body, timeout = API_CONFIG.timeout, ...fetchOptions } = options;
+
+  const url = endpoint.startsWith('http') ? endpoint : `${API_CONFIG.baseUrl}${endpoint}`;
+
+  const { controller, timeoutId } = createTimeoutController(timeout);
+
+  try {
+    const response = await fetch(url, {
+      ...fetchOptions,
+      body: body ? JSON.stringify(body) : undefined,
+      headers: {
+        'Content-Type': 'application/json',
+        ...fetchOptions.headers,
+      },
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      const error = await parseErrorResponse(response);
+      throw new ApiClientError(error.message, response.status, error.code);
+    }
+
+    // Handle 204 No Content
+    if (response.status === 204) {
+      return undefined as T;
+    }
+
+    return response.json();
+  } catch (error) {
+    clearTimeout(timeoutId);
+
+    if (error instanceof ApiClientError) {
+      throw error;
+    }
+
+    if (error instanceof Error) {
+      if (error.name === 'AbortError') {
+        throw new ApiClientError('Request timeout', 408, 'TIMEOUT');
+      }
+      throw new ApiClientError(error.message, 0, 'NETWORK_ERROR');
+    }
+
+    throw new ApiClientError('An unexpected error occurred', 0, 'UNKNOWN');
+  }
+}
+
+/**
+ * API client with HTTP method helpers
+ */
+export const api = {
+  get<T>(endpoint: string, options?: RequestOptions): Promise<T> {
+    return request<T>(endpoint, { ...options, method: 'GET' });
+  },
+
+  post<T>(endpoint: string, body?: unknown, options?: RequestOptions): Promise<T> {
+    return request<T>(endpoint, { ...options, method: 'POST', body });
+  },
+
+  put<T>(endpoint: string, body?: unknown, options?: RequestOptions): Promise<T> {
+    return request<T>(endpoint, { ...options, method: 'PUT', body });
+  },
+
+  patch<T>(endpoint: string, body?: unknown, options?: RequestOptions): Promise<T> {
+    return request<T>(endpoint, { ...options, method: 'PATCH', body });
+  },
+
+  delete<T>(endpoint: string, options?: RequestOptions): Promise<T> {
+    return request<T>(endpoint, { ...options, method: 'DELETE' });
+  },
+};

package/templates/src/lib/config.ts

@@ -0,0 +1,15 @@
+/**
+ * Application configuration.
+ * Centralized config for feature flags, etc.
+ */
+
+export const APP_CONFIG = {
+  name: import.meta.env.VITE_APP_NAME || 'My App',
+  url: import.meta.env.VITE_APP_URL || 'http://localhost:5173',
+} as const;
+
+export const SENTRY_CONFIG = {
+  enabled: import.meta.env.VITE_SENTRY_ENABLED !== 'false',
+  dsn: import.meta.env.VITE_SENTRY_DSN,
+  tracesSampleRate: 0.1,
+} as const;

package/templates/src/lib/constants.ts

@@ -0,0 +1,8 @@
+export const TIMING = {
+  DEBOUNCE_MS: 300,
+  TOAST_DURATION_MS: 5000,
+} as const;
+
+export const UI = {
+  MAX_WIDTH: 1280,
+} as const;

package/templates/src/lib/env.ts

@@ -0,0 +1,53 @@
+/**
+ * Environment variable validation using Zod.
+ * Validates at runtime to catch missing/invalid env vars early.
+ */
+
+import { z } from 'zod';
+
+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),
+});
+
+export type Env = z.infer<typeof envSchema>;
+
+/**
+ * Validate environment variables and return typed env object.
+ * Throws if validation fails in production.
+ */
+export function validateEnv(): Env {
+  const env = {
+    VITE_APP_NAME: import.meta.env.VITE_APP_NAME,
+    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,
+    MODE: import.meta.env.MODE,
+    DEV: import.meta.env.DEV,
+    PROD: import.meta.env.PROD,
+  };
+
+  const result = envSchema.safeParse(env);
+
+  if (!result.success) {
+    const errors = result.error.format();
+    console.error('Environment validation failed:', errors);
+
+    if (import.meta.env.PROD) {
+      throw new Error('Invalid environment configuration');
+    }
+  }
+
+  return result.success ? result.data : (env as Env);
+}
+
+/**
+ * Validated environment variables.
+ * Access this instead of import.meta.env for type safety.
+ */
+export const env = validateEnv();

package/templates/src/lib/format.ts

@@ -0,0 +1,119 @@
+/**
+ * Formatting utilities for dates, numbers, and currencies.
+ * All formatters are locale-aware.
+ */
+
+/**
+ * Format a date with locale support
+ */
+export function formatDate(
+  date: Date | string | number,
+  options: Intl.DateTimeFormatOptions = {},
+  locale?: string,
+): string {
+  const dateObj = date instanceof Date ? date : new Date(date);
+
+  if (isNaN(dateObj.getTime())) {
+    return 'Invalid date';
+  }
+
+  const defaultOptions: Intl.DateTimeFormatOptions = {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    ...options,
+  };
+
+  return new Intl.DateTimeFormat(locale, defaultOptions).format(dateObj);
+}
+
+/**
+ * Format a date with time
+ */
+export function formatDateTime(
+  date: Date | string | number,
+  options: Intl.DateTimeFormatOptions = {},
+  locale?: string,
+): string {
+  return formatDate(
+    date,
+    {
+      hour: '2-digit',
+      minute: '2-digit',
+      ...options,
+    },
+    locale,
+  );
+}
+
+/**
+ * Format relative time (e.g., "2 hours ago", "in 3 days")
+ */
+export function formatRelativeTime(date: Date | string | number, locale?: string): string {
+  const dateObj = date instanceof Date ? date : new Date(date);
+
+  if (isNaN(dateObj.getTime())) {
+    return 'Invalid date';
+  }
+
+  const now = new Date();
+  const diffInSeconds = Math.floor((dateObj.getTime() - now.getTime()) / 1000);
+  const absoluteDiff = Math.abs(diffInSeconds);
+
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+
+  if (absoluteDiff < 60) {
+    return rtf.format(diffInSeconds, 'second');
+  } else if (absoluteDiff < 3600) {
+    return rtf.format(Math.floor(diffInSeconds / 60), 'minute');
+  } else if (absoluteDiff < 86400) {
+    return rtf.format(Math.floor(diffInSeconds / 3600), 'hour');
+  } else if (absoluteDiff < 2592000) {
+    return rtf.format(Math.floor(diffInSeconds / 86400), 'day');
+  } else if (absoluteDiff < 31536000) {
+    return rtf.format(Math.floor(diffInSeconds / 2592000), 'month');
+  } else {
+    return rtf.format(Math.floor(diffInSeconds / 31536000), 'year');
+  }
+}
+
+/**
+ * Format a number with locale support
+ */
+export function formatNumber(value: number, options: Intl.NumberFormatOptions = {}, locale?: string): string {
+  return new Intl.NumberFormat(locale, options).format(value);
+}
+
+/**
+ * Format a number as currency
+ */
+export function formatCurrency(value: number, currency = 'USD', locale?: string): string {
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+  }).format(value);
+}
+
+/**
+ * Format a number as percentage
+ */
+export function formatPercent(value: number, decimals = 0, locale?: string): string {
+  return new Intl.NumberFormat(locale, {
+    style: 'percent',
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(value);
+}
+
+/**
+ * Format bytes to human readable string
+ */
+export function formatBytes(bytes: number, decimals = 2): string {
+  if (bytes === 0) return '0 Bytes';
+
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(decimals))} ${sizes[i]}`;
+}

package/templates/src/lib/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Central lib exports.
+ * Import from '@/lib' instead of individual files.
+ */
+
+export { cn } from './utils';
+export { TIMING, UI } from './constants';
+export { STORAGE_KEYS, isAppKey } from './storageKeys';
+export { APP_CONFIG, SENTRY_CONFIG } from './config';
+export { API_CONFIG } from './api';
+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 {
+  formatDate,
+  formatDateTime,
+  formatRelativeTime,
+  formatNumber,
+  formatCurrency,
+  formatPercent,
+  formatBytes,
+} from './format';
+export { contactFormSchema, registerFormSchema, type ContactFormData, type RegisterFormData } from './validations';

package/templates/src/lib/routes.ts

@@ -0,0 +1,11 @@
+/**
+ * Typed route constants.
+ * Use these instead of hardcoded strings for type-safe navigation.
+ */
+
+export const ROUTES = {
+  HOME: '/',
+  NOT_FOUND: '*',
+} as const;
+
+export type AppRoute = (typeof ROUTES)[keyof typeof ROUTES];

package/templates/src/lib/storage.ts

@@ -0,0 +1,91 @@
+/**
+ * Type-safe localStorage abstraction with SSR safety and error handling.
+ */
+
+import { STORAGE_KEYS } from './storageKeys';
+
+type StorageKey = (typeof STORAGE_KEYS)[keyof typeof STORAGE_KEYS];
+
+/**
+ * Check if we're in a browser environment
+ */
+function isBrowser(): boolean {
+  return typeof window !== 'undefined' && typeof localStorage !== 'undefined';
+}
+
+/**
+ * Get a value from localStorage with type safety
+ */
+export function getStorageItem<T>(key: StorageKey, defaultValue: T): T {
+  if (!isBrowser()) {
+    return defaultValue;
+  }
+
+  try {
+    const item = localStorage.getItem(key);
+    if (item === null) {
+      return defaultValue;
+    }
+    return JSON.parse(item) as T;
+  } catch {
+    // If parsing fails, try returning the raw string if T is string
+    const item = localStorage.getItem(key);
+    if (item !== null) {
+      return item as unknown as T;
+    }
+    return defaultValue;
+  }
+}
+
+/**
+ * Set a value in localStorage with error handling
+ */
+export function setStorageItem<T>(key: StorageKey, value: T): boolean {
+  if (!isBrowser()) {
+    return false;
+  }
+
+  try {
+    localStorage.setItem(key, JSON.stringify(value));
+    return true;
+  } catch (error) {
+    console.error(`Failed to set localStorage key "${key}":`, error);
+    return false;
+  }
+}
+
+/**
+ * Remove a value from localStorage
+ */
+export function removeStorageItem(key: StorageKey): boolean {
+  if (!isBrowser()) {
+    return false;
+  }
+
+  try {
+    localStorage.removeItem(key);
+    return true;
+  } catch (error) {
+    console.error(`Failed to remove localStorage key "${key}":`, error);
+    return false;
+  }
+}
+
+/**
+ * Clear all app-related storage keys
+ */
+export function clearAppStorage(): boolean {
+  if (!isBrowser()) {
+    return false;
+  }
+
+  try {
+    Object.values(STORAGE_KEYS).forEach((key) => {
+      localStorage.removeItem(key);
+    });
+    return true;
+  } catch (error) {
+    console.error('Failed to clear app storage:', error);
+    return false;
+  }
+}

package/templates/src/lib/storageKeys.ts

@@ -0,0 +1,10 @@
+const PREFIX = 'myapp';
+
+export const STORAGE_KEYS = {
+  preferences: `${PREFIX}-preferences`,
+  locale: `${PREFIX}-locale`,
+} as const;
+
+export function isAppKey(key: string): boolean {
+  return key.startsWith(`${PREFIX}-`);
+}

package/templates/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/templates/src/lib/validations.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+
+/**
+ * Example validation schema for a contact form.
+ * Extend or replace with your own schemas.
+ */
+export const contactFormSchema = z.object({
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+  email: z.string().email('Please enter a valid email address'),
+  message: z.string().min(10, 'Message must be at least 10 characters'),
+});
+
+export type ContactFormData = z.infer<typeof contactFormSchema>;
+
+/**
+ * Example validation schema for user registration.
+ */
+export const registerFormSchema = z
+  .object({
+    username: z
+      .string()
+      .min(3, 'Username must be at least 3 characters')
+      .max(20, 'Username must be at most 20 characters')
+      .regex(/^[a-zA-Z0-9_]+$/, 'Username can only contain letters, numbers, and underscores'),
+    email: z.string().email('Please enter a valid email address'),
+    password: z
+      .string()
+      .min(8, 'Password must be at least 8 characters')
+      .regex(/[A-Z]/, 'Password must contain at least one uppercase letter')
+      .regex(/[a-z]/, 'Password must contain at least one lowercase letter')
+      .regex(/[0-9]/, 'Password must contain at least one number'),
+    confirmPassword: z.string(),
+  })
+  .refine((data) => data.password === data.confirmPassword, {
+    message: "Passwords don't match",
+    path: ['confirmPassword'],
+  });
+
+export type RegisterFormData = z.infer<typeof registerFormSchema>;

package/templates/src/locales/de.po

@@ -0,0 +1,65 @@
+msgid ""
+msgstr ""
+"Language: de\n"
+"Project-Id-Version: \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: \n"
+"PO-Revision-Date: \n"
+"Last-Translator: \n"
+"Language-Team: \n"
+"Content-Type: \n"
+"Content-Transfer-Encoding: \n"
+"Plural-Forms: \n"
+
+#. Button label to navigate back to the home page from 404 error
+#: src/pages/NotFound.tsx:23
+msgid "Back to Home"
+msgstr ""
+
+#. Accessibility label for the language selector dropdown button
+#: src/components/shared/LanguageSwitcher/LanguageSwitcher.tsx:24
+msgid "Change language"
+msgstr "Sprache ändern"
+
+#. Instructions for developers on how to start customizing the app
+#: src/pages/Home.tsx:10
+msgid "Get started by editing <0>src/App.tsx</0>"
+msgstr "Beginne mit der Bearbeitung von <0>src/App.tsx</0>"
+
+#: src/components/ui/loading.tsx:54
+msgid "Loading..."
+msgstr ""
+
+#. Application name displayed in the header navigation
+#: src/components/layout/Header.tsx:10
+msgid "My App"
+msgstr "Meine App"
+
+#. Heading shown on 404 error page when URL doesn't exist
+#: src/pages/NotFound.tsx:13
+msgid "Page Not Found"
+msgstr ""
+
+#. Accessibility label when clicking will switch to dark theme
+#. Accessibility label when clicking will switch to dark theme
+#: src/components/shared/ThemeToggle/ThemeToggle.tsx:26
+#: src/components/shared/ThemeToggle/ThemeToggle.tsx:29
+msgid "Switch to dark mode"
+msgstr "Zum Dunkelmodus wechseln"
+
+#. Accessibility label when clicking will switch to light theme
+#. Accessibility label when clicking will switch to light theme
+#: src/components/shared/ThemeToggle/ThemeToggle.tsx:22
+#: src/components/shared/ThemeToggle/ThemeToggle.tsx:30
+msgid "Switch to light mode"
+msgstr "Zum Hellmodus wechseln"
+
+#. Explanation message on 404 error page
+#: src/pages/NotFound.tsx:16
+msgid "The page you're looking for doesn't exist or has been moved."
+msgstr ""
+
+#. Main heading on the home page
+#: src/pages/Home.tsx:7
+msgid "Welcome to My App"
+msgstr "Willkommen bei Meine App"

package/templates/src/locales/en.po

@@ -0,0 +1,65 @@
+msgid ""
+msgstr ""
+"Language: en\n"
+"Project-Id-Version: \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: \n"
+"PO-Revision-Date: \n"
+"Last-Translator: \n"
+"Language-Team: \n"
+"Content-Type: \n"
+"Content-Transfer-Encoding: \n"
+"Plural-Forms: \n"
+
+#. Button label to navigate back to the home page from 404 error
+#: src/pages/NotFound.tsx:23
+msgid "Back to Home"
+msgstr "Back to Home"
+
+#. Accessibility label for the language selector dropdown button
+#: src/components/shared/LanguageSwitcher/LanguageSwitcher.tsx:24
+msgid "Change language"
+msgstr "Change language"
+
+#. Instructions for developers on how to start customizing the app
+#: src/pages/Home.tsx:10
+msgid "Get started by editing <0>src/App.tsx</0>"
+msgstr "Get started by editing <0>src/App.tsx</0>"
+
+#: src/components/ui/loading.tsx:54
+msgid "Loading..."
+msgstr "Loading..."
+
+#. Application name displayed in the header navigation
+#: src/components/layout/Header.tsx:10
+msgid "My App"
+msgstr "My App"
+
+#. Heading shown on 404 error page when URL doesn't exist
+#: src/pages/NotFound.tsx:13
+msgid "Page Not Found"
+msgstr "Page Not Found"
+
+#. Accessibility label when clicking will switch to dark theme
+#. Accessibility label when clicking will switch to dark theme
+#: src/components/shared/ThemeToggle/ThemeToggle.tsx:26
+#: src/components/shared/ThemeToggle/ThemeToggle.tsx:29
+msgid "Switch to dark mode"
+msgstr "Switch to dark mode"
+
+#. Accessibility label when clicking will switch to light theme
+#. Accessibility label when clicking will switch to light theme
+#: src/components/shared/ThemeToggle/ThemeToggle.tsx:22
+#: src/components/shared/ThemeToggle/ThemeToggle.tsx:30
+msgid "Switch to light mode"
+msgstr "Switch to light mode"
+
+#. Explanation message on 404 error page
+#: src/pages/NotFound.tsx:16
+msgid "The page you're looking for doesn't exist or has been moved."
+msgstr "The page you're looking for doesn't exist or has been moved."
+
+#. Main heading on the home page
+#: src/pages/Home.tsx:7
+msgid "Welcome to My App"
+msgstr "Welcome to My App"