ai-flow-dev 1.0.1

package/templates/frontend/docs/error-handling.template.md

@@ -0,0 +1,385 @@
+# Error Handling
+
+> Error handling strategies and best practices for {{PROJECT_NAME}}
+
+---
+
+## 🎯 Error Handling Strategy
+
+**Approach:** {{ERROR_HANDLING_STRATEGY}}
+**Error Logging:** {{ERROR_LOGGING_TOOL}}
+**Recovery Strategy:** {{ERROR_RECOVERY_STRATEGY}}
+
+---
+
+## 🛡️ Error Boundaries (React)
+
+### Basic Error Boundary
+
+```typescript
+// components/ErrorBoundary.tsx
+import React, { Component, ErrorInfo, ReactNode } from 'react';
+
+interface Props {
+  children: ReactNode;
+  fallback?: ReactNode;
+}
+
+interface State {
+  hasError: boolean;
+  error: Error | null;
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    // Log error to error tracking service
+    console.error('Error caught by boundary:', error, errorInfo);
+    
+    // Send to Sentry/LogRocket
+    if (window.Sentry) {
+      window.Sentry.captureException(error, { contexts: { react: errorInfo } });
+    }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback || (
+        <div className="error-boundary">
+          <h2>Something went wrong</h2>
+          <button onClick={() => this.setState({ hasError: false, error: null })}>
+            Try again
+          </button>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+```
+
+### Usage
+
+```typescript
+// App.tsx
+<ErrorBoundary fallback={<ErrorFallback />}>
+  <App />
+</ErrorBoundary>
+```
+
+---
+
+## 🔄 Global Error Handlers
+
+### React Global Error Handler
+
+```typescript
+// utils/globalErrorHandler.ts
+export function setupGlobalErrorHandler() {
+  // Unhandled errors
+  window.addEventListener('error', (event) => {
+    console.error('Global error:', event.error);
+    logError(event.error, { type: 'unhandled' });
+  });
+
+  // Unhandled promise rejections
+  window.addEventListener('unhandledrejection', (event) => {
+    console.error('Unhandled rejection:', event.reason);
+    logError(event.reason, { type: 'unhandledRejection' });
+  });
+}
+```
+
+### Vue Global Error Handler
+
+```typescript
+// main.ts
+app.config.errorHandler = (err, instance, info) => {
+  console.error('Vue error:', err, info);
+  logError(err, { component: instance?.$options.name, info });
+};
+```
+
+### Angular Global Error Handler
+
+```typescript
+// services/global-error-handler.service.ts
+@Injectable()
+export class GlobalErrorHandler implements ErrorHandler {
+  constructor(private errorLoggingService: ErrorLoggingService) {}
+
+  handleError(error: Error): void {
+    console.error('Angular error:', error);
+    this.errorLoggingService.logError(error);
+  }
+}
+```
+
+---
+
+## 📡 API Error Handling
+
+### Error Types
+
+```typescript
+// types/errors.ts
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    public message: string,
+    public code?: string,
+    public details?: unknown
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+export class NetworkError extends Error {
+  constructor(message = 'Network error') {
+    super(message);
+    this.name = 'NetworkError';
+  }
+}
+
+export class TimeoutError extends Error {
+  constructor(message = 'Request timeout') {
+    super(message);
+    this.name = 'TimeoutError';
+  }
+}
+```
+
+### Error Handling by Status Code
+
+```typescript
+// utils/apiErrorHandler.ts
+export function handleApiError(error: unknown): {
+  message: string;
+  action: 'retry' | 'redirect' | 'show' | 'ignore';
+} {
+  if (error instanceof ApiError) {
+    switch (error.status) {
+      case 400:
+        return {
+          message: 'Invalid request. Please check your input.',
+          action: 'show',
+        };
+      case 401:
+        return {
+          message: 'Session expired. Please log in again.',
+          action: 'redirect', // Redirect to login
+        };
+      case 403:
+        return {
+          message: 'Access denied.',
+          action: 'show',
+        };
+      case 404:
+        return {
+          message: 'Resource not found.',
+          action: 'show',
+        };
+      case 429:
+        return {
+          message: 'Too many requests. Please try again later.',
+          action: 'retry',
+        };
+      case 500:
+      case 502:
+      case 503:
+      case 504:
+        return {
+          message: 'Server error. Please try again.',
+          action: 'retry',
+        };
+      default:
+        return {
+          message: 'An error occurred. Please try again.',
+          action: 'show',
+        };
+    }
+  }
+
+  if (error instanceof NetworkError) {
+    return {
+      message: 'Network error. Please check your connection.',
+      action: 'retry',
+    };
+  }
+
+  if (error instanceof TimeoutError) {
+    return {
+      message: 'Request timed out. Please try again.',
+      action: 'retry',
+    };
+  }
+
+  return {
+    message: 'An unexpected error occurred.',
+    action: 'show',
+  };
+}
+```
+
+---
+
+## 🔁 Retry Logic
+
+### Exponential Backoff Retry
+
+```typescript
+// utils/retry.ts
+export async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  maxRetries = 3,
+  initialDelay = 1000
+): Promise<T> {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === maxRetries - 1) throw error;
+      
+      // Don't retry on 4xx errors (except 429)
+      if (error instanceof ApiError && error.status >= 400 && error.status < 500 && error.status !== 429) {
+        throw error;
+      }
+
+      // Exponential backoff: 1s, 2s, 4s
+      const delay = initialDelay * Math.pow(2, attempt);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  throw new Error('Max retries exceeded');
+}
+```
+
+### Usage with TanStack Query
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+
+const { data } = useQuery({
+  queryKey: ['users', id],
+  queryFn: () => usersService.getById(id),
+  retry: (failureCount, error) => {
+    // Don't retry on 4xx errors
+    if (error instanceof ApiError && error.status >= 400 && error.status < 500) {
+      return false;
+    }
+    return failureCount < 3;
+  },
+  retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
+});
+```
+
+---
+
+## 📝 Error Logging
+
+### Error Logging Service
+
+```typescript
+// services/errorLogging.ts
+import * as Sentry from '@sentry/react';
+
+export function logError(error: Error, context?: Record<string, unknown>) {
+  // Development: Console
+  if (import.meta.env.DEV) {
+    console.error('Error:', error, context);
+    return;
+  }
+
+  // Production: Sentry
+  Sentry.captureException(error, {
+    contexts: {
+      custom: context || {},
+    },
+    tags: {
+      component: context?.component as string,
+    },
+  });
+}
+```
+
+### User Context
+
+```typescript
+// Add user context to errors
+Sentry.setUser({
+  id: user.id,
+  email: user.email,
+  username: user.username,
+});
+```
+
+---
+
+## 🎨 Error UI Components
+
+### Error Display Component
+
+```typescript
+// components/ErrorDisplay.tsx
+interface ErrorDisplayProps {
+  error: Error;
+  onRetry?: () => void;
+}
+
+export const ErrorDisplay: React.FC<ErrorDisplayProps> = ({ error, onRetry }) => {
+  const { message, action } = handleApiError(error);
+
+  return (
+    <div className="error-display">
+      <h3>Oops! Something went wrong</h3>
+      <p>{message}</p>
+      {action === 'retry' && onRetry && (
+        <button onClick={onRetry}>Try Again</button>
+      )}
+    </div>
+  );
+};
+```
+
+### Fallback UI
+
+```typescript
+// components/ErrorFallback.tsx
+export const ErrorFallback: React.FC<{ error: Error; resetError: () => void }> = ({
+  error,
+  resetError,
+}) => {
+  return (
+    <div className="error-fallback">
+      <h2>Something went wrong</h2>
+      <pre>{error.message}</pre>
+      <button onClick={resetError}>Try again</button>
+    </div>
+  );
+};
+```
+
+---
+
+## 🔗 Related Documents
+
+- [API Integration](api-integration.md) - API error handling
+- [State Management](state-management.md) - Error state management
+- [Security](security.md) - Security error handling
+
+---
+
+**Last Updated:** {{GENERATION_DATE}}
+
+**Error Handling Strategy:** {{ERROR_HANDLING_STRATEGY}}
+

package/templates/frontend/docs/operations.template.md

@@ -0,0 +1,123 @@
+# Operations & Deployment
+
+> Deployment procedures and operational guidelines for {{PROJECT_NAME}}
+
+---
+
+## 🚀 Deployment Platform
+
+**Platform:** {{DEPLOYMENT_PLATFORM}}
+**CI/CD:** {{CI_CD_PLATFORM}}
+**Environments:** {{ENVIRONMENTS}}
+
+---
+
+## 📦 Build Process
+
+### Production Build
+
+```bash
+# Build for production
+npm run build
+
+# Output directory
+dist/
+├── index.html
+├── assets/
+│   ├── app-[hash].js
+│   ├── app-[hash].css
+│   └── images/
+```
+
+### Environment Variables
+
+```bash
+# .env.production
+VITE_API_BASE_URL=https://api.example.com
+VITE_APP_ENV=production
+```
+
+---
+
+## 🔄 CI/CD Pipeline
+
+### GitHub Actions Example
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run test
+      - run: npm run build
+      - uses: vercel/action@v1
+        with:
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+```
+
+---
+
+## 📊 Monitoring
+
+### Error Tracking
+
+**Tool:** {{ERROR_TRACKING_TOOL}}
+
+```typescript
+// Sentry setup
+import * as Sentry from '@sentry/react';
+
+Sentry.init({
+  dsn: import.meta.env.VITE_SENTRY_DSN,
+  environment: import.meta.env.VITE_APP_ENV,
+});
+```
+
+### Analytics
+
+**Tool:** {{ANALYTICS_TOOL}}
+
+```typescript
+// Google Analytics
+gtag('config', 'GA_MEASUREMENT_ID');
+```
+
+### Performance Monitoring
+
+**Tool:** {{PERFORMANCE_MONITORING_TOOL}}
+
+```typescript
+// Web Vitals
+import { onCLS, onFID, onLCP } from 'web-vitals';
+
+onCLS(console.log);
+onFID(console.log);
+onLCP(console.log);
+```
+
+---
+
+## 🔗 Related Documents
+
+- [Performance](performance.md) - Performance optimization
+- [Configuration](../specs/configuration.md) - Environment configuration
+
+---
+
+**Last Updated:** {{GENERATION_DATE}}
+
+**Deployment Platform:** {{DEPLOYMENT_PLATFORM}}
+

package/templates/frontend/docs/performance.template.md

@@ -0,0 +1,140 @@
+# Performance Optimization
+
+> Performance optimization strategies and best practices for {{PROJECT_NAME}}
+
+---
+
+## 🎯 Performance Targets
+
+**Core Web Vitals:**
+- **LCP:** < {{LCP_TARGET}}s
+- **FID/INP:** < {{FID_TARGET}}ms
+- **CLS:** < {{CLS_TARGET}}
+
+**Bundle Size:** < {{BUNDLE_SIZE_TARGET}}KB (gzipped)
+
+---
+
+## 📦 Bundle Optimization
+
+### Code Splitting
+
+```typescript
+// Route-based splitting
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+const Profile = lazy(() => import('./pages/Profile'));
+
+// Component-based splitting
+const HeavyChart = lazy(() => import('./components/HeavyChart'));
+```
+
+### Tree Shaking
+
+```typescript
+// ✅ Good - Tree shakeable
+import { debounce } from 'lodash-es';
+
+// ❌ Bad - Imports entire library
+import _ from 'lodash';
+```
+
+### Bundle Analysis
+
+```bash
+# Analyze bundle size
+npm run build -- --analyze
+
+# Check bundle size in CI
+npm run build && du -sh dist/*
+```
+
+---
+
+## 🖼️ Image Optimization
+
+### Next-gen Formats
+
+```typescript
+// Use WebP/AVIF with fallback
+<picture>
+  <source srcset="image.avif" type="image/avif" />
+  <source srcset="image.webp" type="image/webp" />
+  <img src="image.jpg" alt="Description" />
+</picture>
+```
+
+### Lazy Loading
+
+```typescript
+// Native lazy loading
+<img src="image.jpg" loading="lazy" alt="Description" />
+
+// Intersection Observer
+const observer = new IntersectionObserver((entries) => {
+  entries.forEach(entry => {
+    if (entry.isIntersecting) {
+      entry.target.src = entry.target.dataset.src;
+      observer.unobserve(entry.target);
+    }
+  });
+});
+```
+
+---
+
+## ⚡ Performance Monitoring
+
+### Core Web Vitals Tracking
+
+```typescript
+// utils/webVitals.ts
+import { onCLS, onFID, onLCP } from 'web-vitals';
+
+function sendToAnalytics(metric: Metric) {
+  // Send to analytics service
+  gtag('event', metric.name, {
+    value: Math.round(metric.value),
+    event_label: metric.id,
+    non_interaction: true,
+  });
+}
+
+onCLS(sendToAnalytics);
+onFID(sendToAnalytics);
+onLCP(sendToAnalytics);
+```
+
+### Performance Budgets
+
+```javascript
+// .lighthouserc.js
+module.exports = {
+  ci: {
+    collect: {
+      numberOfRuns: 3,
+    },
+    assert: {
+      assertions: {
+        'categories:performance': ['error', { minScore: 0.9 }],
+        'first-contentful-paint': ['error', { maxNumericValue: 2000 }],
+        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
+        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
+      },
+    },
+  },
+};
+```
+
+---
+
+## 🔗 Related Documents
+
+- [Operations](operations.md) - Performance monitoring setup
+- [Build Configuration](../specs/configuration.md) - Build optimization
+
+---
+
+**Last Updated:** {{GENERATION_DATE}}
+
+**Performance Targets:** LCP < {{LCP_TARGET}}s, FID < {{FID_TARGET}}ms, CLS < {{CLS_TARGET}}
+