@cubis/foundry 0.3.10

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/nextjs-developer/references/deployment.md

@@ -0,0 +1,267 @@
+# Deployment Strategies
+
+## Vercel Deployment
+
+### Setup
+
+```bash
+# Install Vercel CLI
+npm i -g vercel
+
+# Deploy (auto-detects Next.js)
+vercel
+
+# Deploy to production
+vercel --prod
+```
+
+### Environment Variables
+
+```bash
+# Add via CLI
+vercel env add DATABASE_URL production
+vercel env add DATABASE_URL preview
+vercel env add DATABASE_URL development
+
+# Or via dashboard: Settings → Environment Variables
+```
+
+### vercel.json Configuration
+
+```json
+{
+  "framework": "nextjs",
+  "regions": ["iad1", "sfo1"],
+  "headers": [
+    {
+      "source": "/api/(.*)",
+      "headers": [{ "key": "Cache-Control", "value": "no-store" }]
+    }
+  ],
+  "redirects": [
+    {
+      "source": "/old-page",
+      "destination": "/new-page",
+      "permanent": true
+    }
+  ]
+}
+```
+
+### Preview Deployments
+
+- Every PR gets a unique preview URL automatically
+- Preview deployments use `preview` environment variables
+- Comment on PR with deployment URL
+
+## Docker Deployment
+
+### Dockerfile (multi-stage)
+
+```dockerfile
+# Stage 1: Dependencies
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --only=production
+
+# Stage 2: Build
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+# Stage 3: Production
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+EXPOSE 3000
+ENV PORT=3000
+CMD ["node", "server.js"]
+```
+
+### next.config.js for Docker
+
+```js
+module.exports = {
+  output: "standalone", // Required for Docker
+};
+```
+
+### Docker Compose
+
+```yaml
+version: "3.8"
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - DATABASE_URL=postgresql://user:pass@db:5432/mydb
+    depends_on:
+      - db
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: pass
+      POSTGRES_DB: mydb
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+volumes:
+  pgdata:
+```
+
+## Self-Hosting (Node.js)
+
+```bash
+# Build
+npm run build
+
+# Start production server
+npm start
+# or
+node .next/standalone/server.js
+```
+
+### PM2 Process Manager
+
+```js
+// ecosystem.config.js
+module.exports = {
+  apps: [
+    {
+      name: "nextjs-app",
+      script: "node_modules/.bin/next",
+      args: "start",
+      instances: "max",
+      exec_mode: "cluster",
+      env: {
+        NODE_ENV: "production",
+        PORT: 3000,
+      },
+    },
+  ],
+};
+```
+
+```bash
+pm2 start ecosystem.config.js
+pm2 save
+pm2 startup
+```
+
+### Nginx Reverse Proxy
+
+```nginx
+server {
+    listen 80;
+    server_name myapp.com;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+    }
+
+    # Cache static assets
+    location /_next/static {
+        proxy_pass http://localhost:3000;
+        add_header Cache-Control "public, max-age=31536000, immutable";
+    }
+}
+```
+
+## Monitoring
+
+### Error Tracking (Sentry)
+
+```bash
+npx @sentry/wizard@latest -i nextjs
+```
+
+```tsx
+// sentry.client.config.ts
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  tracesSampleRate: 0.1,
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0,
+});
+```
+
+### Analytics
+
+```tsx
+// app/layout.tsx
+import { Analytics } from "@vercel/analytics/react";
+import { SpeedInsights } from "@vercel/speed-insights/next";
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+        <SpeedInsights />
+      </body>
+    </html>
+  );
+}
+```
+
+### Health Check Endpoint
+
+```tsx
+// app/api/health/route.ts
+export async function GET() {
+  try {
+    // Check database connection
+    await db.$queryRaw`SELECT 1`;
+    return Response.json({
+      status: "healthy",
+      timestamp: new Date().toISOString(),
+    });
+  } catch (e) {
+    return Response.json(
+      { status: "unhealthy", error: "Database connection failed" },
+      { status: 503 },
+    );
+  }
+}
+```
+
+## Deployment Checklist
+
+- [ ] Environment variables set for production
+- [ ] `output: 'standalone'` if using Docker
+- [ ] Error tracking configured (Sentry or similar)
+- [ ] Analytics enabled
+- [ ] Health check endpoint available
+- [ ] HTTPS configured
+- [ ] Security headers set (CSP, HSTS, etc.)
+- [ ] Caching strategy verified
+- [ ] Preview deployments working for PRs
+- [ ] Rollback plan documented

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/nextjs-developer/references/performance.md

@@ -0,0 +1,222 @@
+# Performance Optimization
+
+## Core Web Vitals Targets
+
+| Metric  | Target  | What It Measures        |
+| ------- | ------- | ----------------------- |
+| TTFB    | < 200ms | Server response time    |
+| FCP     | < 1s    | First content painted   |
+| LCP     | < 2.5s  | Largest content painted |
+| CLS     | < 0.1   | Layout shift score      |
+| FID/INP | < 100ms | Input responsiveness    |
+
+## Image Optimization
+
+### next/image
+
+```tsx
+import Image from "next/image";
+
+// Local image — auto-sized, optimized at build
+import heroImage from "@/public/hero.jpg";
+
+export function Hero() {
+  return (
+    <Image
+      src={heroImage}
+      alt="Hero banner"
+      placeholder="blur" // Blur placeholder while loading
+      priority // Preload (use for above-the-fold images)
+      sizes="100vw"
+    />
+  );
+}
+
+// Remote image — must specify sizes
+export function Avatar({ src, name }: { src: string; name: string }) {
+  return (
+    <Image
+      src={src}
+      alt={`${name}'s avatar`}
+      width={48}
+      height={48}
+      className="rounded-full"
+    />
+  );
+}
+```
+
+### Image Best Practices
+
+- Use `priority` for LCP images (hero, above-the-fold)
+- Always provide `sizes` for responsive images
+- Use `placeholder="blur"` for better perceived performance
+- Configure `remotePatterns` in `next.config.js` for external images
+- Use WebP/AVIF formats (automatic with next/image)
+
+```js
+// next.config.js
+module.exports = {
+  images: {
+    remotePatterns: [{ protocol: "https", hostname: "cdn.example.com" }],
+    formats: ["image/avif", "image/webp"],
+  },
+};
+```
+
+## Font Optimization
+
+```tsx
+// app/layout.tsx
+import { Inter, Roboto_Mono } from "next/font/google";
+
+const inter = Inter({
+  subsets: ["latin"],
+  display: "swap", // Prevent FOIT
+  variable: "--font-inter",
+});
+
+const robotoMono = Roboto_Mono({
+  subsets: ["latin"],
+  display: "swap",
+  variable: "--font-roboto-mono",
+});
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
+      <body className={inter.className}>{children}</body>
+    </html>
+  );
+}
+```
+
+### Local Fonts
+
+```tsx
+import localFont from "next/font/local";
+
+const myFont = localFont({
+  src: "./fonts/MyFont.woff2",
+  display: "swap",
+  variable: "--font-my-font",
+});
+```
+
+## Script Loading
+
+```tsx
+import Script from 'next/script';
+
+// After page is interactive (default)
+<Script src="https://analytics.example.com/script.js" />
+
+// Before page hydration (blocking — use sparingly)
+<Script src="/critical.js" strategy="beforeInteractive" />
+
+// After hydration, when browser is idle
+<Script src="/non-critical.js" strategy="lazyOnload" />
+
+// Inline script with worker strategy (off main thread)
+<Script strategy="worker">
+  {`console.log('Runs in web worker')`}
+</Script>
+```
+
+## Link Prefetching
+
+```tsx
+import Link from 'next/link';
+
+// Prefetched automatically when visible in viewport
+<Link href="/dashboard">Dashboard</Link>
+
+// Disable prefetch for rarely visited pages
+<Link href="/admin/settings" prefetch={false}>Settings</Link>
+```
+
+## Bundle Analysis
+
+```bash
+# Install analyzer
+npm install @next/bundle-analyzer
+
+# next.config.js
+const withBundleAnalyzer = require('@next/bundle-analyzer')({
+  enabled: process.env.ANALYZE === 'true',
+});
+module.exports = withBundleAnalyzer({ /* config */ });
+
+# Run analysis
+ANALYZE=true npm run build
+```
+
+## Code Splitting
+
+### Dynamic Imports
+
+```tsx
+import dynamic from "next/dynamic";
+
+// Lazy load heavy components
+const HeavyChart = dynamic(() => import("@/components/HeavyChart"), {
+  loading: () => <ChartSkeleton />,
+  ssr: false, // Skip SSR for client-only components
+});
+
+// Lazy load below-the-fold content
+const Comments = dynamic(() => import("@/components/Comments"));
+```
+
+### Route-Based Splitting
+
+Next.js automatically code-splits by route. Each `page.tsx` is its own chunk.
+
+## Caching Strategy
+
+| Layer               | What                               | How                         |
+| ------------------- | ---------------------------------- | --------------------------- |
+| Request memoization | Duplicate fetches in single render | Automatic for `fetch()`     |
+| Data cache          | API responses across requests      | `fetch()` with `revalidate` |
+| Full route cache    | Static HTML + RSC payload          | Automatic for static routes |
+| Router cache        | Client-side route cache            | Automatic, 30s for dynamic  |
+
+### Opting Out of Caching
+
+```tsx
+// Per-fetch
+fetch(url, { cache: "no-store" });
+
+// Per-route segment
+export const dynamic = "force-dynamic";
+export const revalidate = 0;
+
+// Per-route via headers/cookies usage
+import { cookies, headers } from "next/headers";
+// Using these automatically makes the route dynamic
+```
+
+## React Compiler (experimental)
+
+```js
+// next.config.js
+module.exports = {
+  experimental: {
+    reactCompiler: true, // Auto-memoizes components and hooks
+  },
+};
+```
+
+When enabled, the compiler automatically handles `useMemo`, `useCallback`, and `React.memo` — you don't need to add them manually.
+
+## Performance Checklist
+
+- [ ] LCP image has `priority` prop
+- [ ] Fonts use `next/font` with `display: 'swap'`
+- [ ] Heavy components use `dynamic()` import
+- [ ] Third-party scripts use appropriate `strategy`
+- [ ] Images use `next/image` with proper `sizes`
+- [ ] No layout shift from dynamic content (set explicit dimensions)
+- [ ] Server Components used where possible (smaller client bundle)
+- [ ] Suspense boundaries for streaming
+- [ ] Bundle analyzed for unexpected large dependencies