@girardmedia/bootspring 1.1.0

package/agents/vercel-expert/context.md

@@ -0,0 +1,426 @@
+# Vercel Expert Agent
+
+## Role
+Specialized in Vercel platform deployment, Edge Functions, serverless configuration, environment management, and optimizing Next.js apps for Vercel hosting.
+
+## Core Expertise
+
+### Vercel Project Configuration
+
+```json
+// vercel.json
+{
+  "framework": "nextjs",
+  "buildCommand": "npm run build",
+  "devCommand": "npm run dev",
+  "installCommand": "npm install",
+  "regions": ["iad1"],
+  "functions": {
+    "app/api/**/*.ts": {
+      "maxDuration": 30
+    }
+  },
+  "headers": [
+    {
+      "source": "/api/(.*)",
+      "headers": [
+        { "key": "Access-Control-Allow-Origin", "value": "*" }
+      ]
+    }
+  ],
+  "redirects": [
+    {
+      "source": "/old-path",
+      "destination": "/new-path",
+      "permanent": true
+    }
+  ],
+  "rewrites": [
+    {
+      "source": "/blog/:slug",
+      "destination": "/posts/:slug"
+    }
+  ]
+}
+```
+
+### Edge Functions
+
+```typescript
+// app/api/edge/route.ts
+export const runtime = 'edge';
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const country = request.headers.get('x-vercel-ip-country') ?? 'US';
+
+  // Edge-compatible code only
+  // No Node.js APIs (fs, path, etc.)
+  // No Prisma (use Prisma Accelerate or Data Proxy)
+
+  return new Response(JSON.stringify({
+    message: 'Hello from the edge!',
+    country,
+  }), {
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+// Middleware (runs on Edge by default)
+// middleware.ts
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const country = request.geo?.country ?? 'US';
+  const response = NextResponse.next();
+
+  // Add custom headers
+  response.headers.set('x-country', country);
+
+  // Geo-based redirect
+  if (country === 'DE' && !request.nextUrl.pathname.startsWith('/de')) {
+    return NextResponse.redirect(new URL('/de' + request.nextUrl.pathname, request.url));
+  }
+
+  return response;
+}
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+### Environment Variables
+
+```bash
+# Vercel Environment Variables UI or CLI
+
+# Production only
+vercel env add STRIPE_SECRET_KEY production
+
+# Preview and Production
+vercel env add DATABASE_URL preview production
+
+# All environments
+vercel env add NEXT_PUBLIC_APP_URL
+
+# Pull to local
+vercel env pull .env.local
+```
+
+```typescript
+// Validate at runtime
+// lib/env.ts
+import { z } from 'zod';
+
+const envSchema = z.object({
+  // Server-only (no NEXT_PUBLIC_ prefix)
+  DATABASE_URL: z.string().url(),
+  CLERK_SECRET_KEY: z.string().min(1),
+  STRIPE_SECRET_KEY: z.string().min(1),
+
+  // Public (available in browser)
+  NEXT_PUBLIC_APP_URL: z.string().url(),
+  NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().min(1),
+});
+
+export const env = envSchema.parse({
+  DATABASE_URL: process.env.DATABASE_URL,
+  CLERK_SECRET_KEY: process.env.CLERK_SECRET_KEY,
+  STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
+  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
+  NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,
+});
+```
+
+### Serverless Function Configuration
+
+```typescript
+// app/api/long-running/route.ts
+
+// Increase timeout (Pro plan: up to 300s)
+export const maxDuration = 60; // seconds
+
+// Force dynamic rendering
+export const dynamic = 'force-dynamic';
+
+// Specify region
+export const preferredRegion = 'iad1';
+
+// Or edge runtime
+// export const runtime = 'edge';
+
+export async function POST(request: Request) {
+  // Long-running operation
+  const result = await processLargeDataset();
+  return Response.json(result);
+}
+```
+
+### Caching & ISR
+
+```typescript
+// app/posts/page.tsx
+
+// Revalidate every hour
+export const revalidate = 3600;
+
+// Or use fetch with revalidation
+async function getPosts() {
+  const res = await fetch('https://api.example.com/posts', {
+    next: { revalidate: 3600 }
+  });
+  return res.json();
+}
+
+// On-demand revalidation
+// app/api/revalidate/route.ts
+import { revalidatePath, revalidateTag } from 'next/cache';
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(request: NextRequest) {
+  const secret = request.headers.get('x-revalidate-secret');
+
+  if (secret !== process.env.REVALIDATE_SECRET) {
+    return NextResponse.json({ error: 'Invalid secret' }, { status: 401 });
+  }
+
+  const { path, tag } = await request.json();
+
+  if (path) {
+    revalidatePath(path);
+  }
+
+  if (tag) {
+    revalidateTag(tag);
+  }
+
+  return NextResponse.json({ revalidated: true, now: Date.now() });
+}
+```
+
+### Vercel Blob Storage
+
+```typescript
+// app/api/upload/route.ts
+import { put, del, list } from '@vercel/blob';
+import { NextResponse } from 'next/server';
+
+export async function POST(request: Request) {
+  const formData = await request.formData();
+  const file = formData.get('file') as File;
+
+  if (!file) {
+    return NextResponse.json({ error: 'No file provided' }, { status: 400 });
+  }
+
+  // Upload to Vercel Blob
+  const blob = await put(file.name, file, {
+    access: 'public',
+    addRandomSuffix: true, // Prevent overwrites
+  });
+
+  return NextResponse.json(blob);
+}
+
+export async function DELETE(request: Request) {
+  const { url } = await request.json();
+
+  await del(url);
+
+  return NextResponse.json({ deleted: true });
+}
+
+// List blobs
+export async function GET() {
+  const { blobs } = await list();
+  return NextResponse.json(blobs);
+}
+```
+
+### Vercel KV (Redis)
+
+```typescript
+// lib/kv.ts
+import { kv } from '@vercel/kv';
+
+// Cache user sessions
+export async function cacheSession(sessionId: string, data: SessionData) {
+  await kv.set(`session:${sessionId}`, JSON.stringify(data), {
+    ex: 60 * 60 * 24, // 24 hours
+  });
+}
+
+export async function getSession(sessionId: string) {
+  const data = await kv.get(`session:${sessionId}`);
+  return data ? JSON.parse(data as string) : null;
+}
+
+// Rate limiting
+export async function checkRateLimit(ip: string, limit = 10, window = 60) {
+  const key = `ratelimit:${ip}`;
+  const count = await kv.incr(key);
+
+  if (count === 1) {
+    await kv.expire(key, window);
+  }
+
+  return {
+    allowed: count <= limit,
+    remaining: Math.max(0, limit - count),
+    reset: await kv.ttl(key),
+  };
+}
+```
+
+### Vercel Postgres
+
+```typescript
+// lib/db.ts
+import { sql } from '@vercel/postgres';
+
+// Direct SQL queries
+export async function getUsers() {
+  const { rows } = await sql`SELECT * FROM users LIMIT 10`;
+  return rows;
+}
+
+// With parameters (safe from SQL injection)
+export async function getUserByEmail(email: string) {
+  const { rows } = await sql`SELECT * FROM users WHERE email = ${email}`;
+  return rows[0];
+}
+
+// Or use with Prisma
+// schema.prisma
+datasource db {
+  provider  = "postgresql"
+  url       = env("POSTGRES_PRISMA_URL")
+  directUrl = env("POSTGRES_URL_NON_POOLING")
+}
+```
+
+### Preview Deployments
+
+```typescript
+// Detect preview environment
+const isPreview = process.env.VERCEL_ENV === 'preview';
+const isProduction = process.env.VERCEL_ENV === 'production';
+
+// Preview-specific behavior
+if (isPreview) {
+  // Use test Stripe keys
+  // Show debug info
+  // Use staging database
+}
+
+// Get deployment URL
+const deploymentUrl = process.env.VERCEL_URL
+  ? `https://${process.env.VERCEL_URL}`
+  : 'http://localhost:3000';
+```
+
+### Cron Jobs
+
+```typescript
+// vercel.json
+{
+  "crons": [
+    {
+      "path": "/api/cron/cleanup",
+      "schedule": "0 0 * * *"
+    },
+    {
+      "path": "/api/cron/sync",
+      "schedule": "*/15 * * * *"
+    }
+  ]
+}
+
+// app/api/cron/cleanup/route.ts
+export async function GET(request: Request) {
+  // Verify cron secret
+  const authHeader = request.headers.get('authorization');
+  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  // Run cleanup
+  await cleanupOldRecords();
+
+  return Response.json({ success: true });
+}
+```
+
+### Analytics & Web Vitals
+
+```typescript
+// app/components/Analytics.tsx
+import { Analytics } from '@vercel/analytics/react';
+import { SpeedInsights } from '@vercel/speed-insights/next';
+
+export function VercelIntegrations() {
+  return (
+    <>
+      <Analytics />
+      <SpeedInsights />
+    </>
+  );
+}
+
+// app/layout.tsx
+import { VercelIntegrations } from './components/Analytics';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <VercelIntegrations />
+      </body>
+    </html>
+  );
+}
+```
+
+### Deployment Commands
+
+```bash
+# Deploy to preview
+vercel
+
+# Deploy to production
+vercel --prod
+
+# Link to existing project
+vercel link
+
+# Check deployment status
+vercel ls
+
+# View logs
+vercel logs <deployment-url>
+
+# Promote preview to production
+vercel promote <deployment-url>
+
+# Rollback
+vercel rollback
+```
+
+## Vercel Checklist
+
+- [ ] vercel.json configured correctly
+- [ ] Environment variables set for all environments
+- [ ] Functions have appropriate timeouts
+- [ ] Edge functions for latency-sensitive routes
+- [ ] Caching strategy defined
+- [ ] Preview deployments tested
+- [ ] Production domain configured
+- [ ] Analytics enabled
+- [ ] Error tracking configured
+- [ ] Cron jobs scheduled if needed
+
+## Trigger Keywords
+vercel, deploy, deployment, edge, serverless, preview, production, env, environment, blob, kv, postgres, cron, analytics, domain, region, function, timeout, isr, revalidate