opencode-skills-collection 4.0.53 → 4.0.55

package/bundled-skills/vercel-deployment/SKILL.md

@@ -10,662 +10,14 @@ date_added: 2026-02-27
 
 Expert knowledge for deploying to Vercel with Next.js
 
-## Capabilities
+## Detailed Guide
 
-- vercel
-- deployment
-- edge-functions
-- serverless
-- environment-variables
+Read [the detailed guide](references/detailed-guide.md) before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.
 
 ## Prerequisites
 
 - Required skills: nextjs-app-router
 
-## Patterns
-
-### Environment Variables Setup
-
-Properly configure environment variables for all environments
-
-**When to use**: Setting up a new project on Vercel
-
-// Three environments in Vercel:
-// - Development (local)
-// - Preview (PR deployments)
-// - Production (main branch)
-
-// In Vercel Dashboard:
-// Settings → Environment Variables
-
-// PUBLIC variables (exposed to browser)
-NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
-NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
-
-// PRIVATE variables (server only)
-SUPABASE_SERVICE_ROLE_KEY=eyJ...  // Never NEXT_PUBLIC_!
-DATABASE_URL=postgresql://...
-
-// Per-environment values:
-// Production: Real database, production API keys
-// Preview: Staging database, test API keys
-// Development: Local/dev values (also in .env.local)
-
-// In code, check environment:
-const isProduction = process.env.VERCEL_ENV === 'production'
-const isPreview = process.env.VERCEL_ENV === 'preview'
-
-### Edge vs Serverless Functions
-
-Choose the right runtime for your API routes
-
-**When to use**: Creating API routes or middleware
-
-// EDGE RUNTIME - Fast cold starts, limited APIs
-// Good for: Auth checks, redirects, simple transforms
-
-// app/api/hello/route.ts
-export const runtime = 'edge'
-
-export async function GET() {
-  return Response.json({ message: 'Hello from Edge!' })
-}
-
-// middleware.ts (always edge)
-export function middleware(request: NextRequest) {
-  // Fast auth checks here
-}
-
-// SERVERLESS (Node.js) - Full Node APIs, slower cold start
-// Good for: Database queries, file operations, heavy computation
-
-// app/api/users/route.ts
-export const runtime = 'nodejs'  // Default, can omit
-
-export async function GET() {
-  const users = await db.query('SELECT * FROM users')
-  return Response.json(users)
-}
-
-### Build Optimization
-
-Optimize build for faster deployments and smaller bundles
-
-**When to use**: Preparing for production deployment
-
-// next.config.js
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  // Minimize output
-  output: 'standalone',  // For Docker/self-hosting
-
-  // Image optimization
-  images: {
-    remotePatterns: [
-      { hostname: 'your-cdn.com' },
-    ],
-  },
-
-  // Bundle analyzer (dev only)
-  // npm install @next/bundle-analyzer
-  ...(process.env.ANALYZE === 'true' && {
-    webpack: (config) => {
-      const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer')
-      config.plugins.push(new BundleAnalyzerPlugin())
-      return config
-    },
-  }),
-}
-
-// Reduce serverless function size:
-// - Use dynamic imports for heavy libs
-// - Check bundle with: npx @next/bundle-analyzer
-
-### Preview Deployment Workflow
-
-Use preview deployments for PR reviews
-
-**When to use**: Setting up team development workflow
-
-// Every PR gets a unique preview URL automatically
-
-// Protect preview deployments with password:
-// Vercel Dashboard → Settings → Deployment Protection
-
-// Use different env vars for preview:
-// - PREVIEW: Use staging database
-// - PRODUCTION: Use production database
-
-// In code, detect preview:
-if (process.env.VERCEL_ENV === 'preview') {
-  // Show "Preview" banner
-  // Use test payment processor
-  // Disable analytics
-}
-
-// Comment preview URL on PR (automatic with Vercel GitHub integration)
-
-### Custom Domain Setup
-
-Configure custom domains with proper SSL
-
-**When to use**: Going to production
-
-// In Vercel Dashboard → Domains
-
-// Add domains:
-// - example.com (apex/root)
-// - www.example.com (subdomain)
-
-// DNS Configuration (at your registrar):
-// Type: A, Name: @, Value: 76.76.21.21
-// Type: CNAME, Name: www, Value: cname.vercel-dns.com
-
-// Redirect www to apex (or vice versa):
-// Vercel handles this automatically
-
-// In next.config.js for redirects:
-module.exports = {
-  async redirects() {
-    return [
-      {
-        source: '/old-page',
-        destination: '/new-page',
-        permanent: true,  // 308
-      },
-    ]
-  },
-}
-
-## Sharp Edges
-
-### NEXT_PUBLIC_ exposes secrets to the browser
-
-Severity: CRITICAL
-
-Situation: Using NEXT_PUBLIC_ prefix for sensitive API keys
-
-Symptoms:
-- Secrets visible in browser DevTools → Sources
-- Security audit finds exposed keys
-- Unexpected API access from unknown sources
-
-Why this breaks:
-Variables prefixed with NEXT_PUBLIC_ are inlined into the JavaScript
-bundle at build time. Anyone can view them in browser DevTools.
-This includes all your users and potential attackers.
-
-Recommended fix:
-
-Only use NEXT_PUBLIC_ for truly public values:
-
-// SAFE to use NEXT_PUBLIC_
-NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
-NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...  // Anon key is designed to be public
-NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
-NEXT_PUBLIC_GA_ID=G-XXXXXXX
-
-// NEVER use NEXT_PUBLIC_
-SUPABASE_SERVICE_ROLE_KEY=eyJ...     // Full database access!
-STRIPE_SECRET_KEY=sk_live_...         // Can charge cards!
-DATABASE_URL=postgresql://...          // Direct DB access!
-JWT_SECRET=...                         // Can forge tokens!
-
-// Access server-only vars in:
-// - Server Components (app router)
-// - API Routes
-// - Server Actions ('use server')
-// - getServerSideProps (pages router)
-
-### Preview deployments using production database
-
-Severity: HIGH
-
-Situation: Not configuring separate environment variables for preview
-
-Symptoms:
-- Test data appearing in production
-- Production data corrupted after PR merge
-- Users seeing test accounts/content
-
-Why this breaks:
-Preview deployments run untested code. If they use production database,
-a bug in a PR can corrupt production data. Also, testers might create
-test data that shows up in production.
-
-Recommended fix:
-
-Set up separate databases for each environment:
-
-// In Vercel Dashboard → Settings → Environment Variables
-
-// Production (production env only):
-DATABASE_URL=postgresql://prod-host/prod-db
-
-// Preview (preview env only):
-DATABASE_URL=postgresql://staging-host/staging-db
-
-// Or use Vercel's branching databases:
-// - Neon, PlanetScale, Supabase all support branch databases
-// - Auto-create preview DB for each PR
-
-// For Supabase, create a staging project:
-// Production:
-NEXT_PUBLIC_SUPABASE_URL=https://prod-xxx.supabase.co
-
-// Preview:
-NEXT_PUBLIC_SUPABASE_URL=https://staging-xxx.supabase.co
-
-### Serverless function too large, slow cold starts
-
-Severity: HIGH
-
-Situation: API route or server component has slow initial load
-
-Symptoms:
-- First request takes 3-10+ seconds
-- Subsequent requests are fast
-- Function size limit exceeded error
-- Deployment fails with size error
-
-Why this breaks:
-Vercel serverless functions have a 50MB limit (compressed).
-Large functions mean slow cold starts (1-5+ seconds).
-Heavy dependencies like puppeteer, sharp can cause this.
-
-Recommended fix:
-
-Reduce function size:
-
-// 1. Use dynamic imports for heavy libs
-export async function GET() {
-  const sharp = await import('sharp')  // Only loads when needed
-  // ...
-}
-
-// 2. Move heavy processing to edge or external service
-export const runtime = 'edge'  // Much smaller, faster cold start
-
-// 3. Check bundle size
-// npx @next/bundle-analyzer
-// Look for large dependencies
-
-// 4. Use external services for heavy tasks
-// - Image processing: Cloudinary, imgix
-// - PDF generation: API service
-// - Puppeteer: Browserless.io
-
-// 5. Split into multiple functions
-// /api/heavy-task/start - Queue the job
-// /api/heavy-task/status - Check progress
-
-### Edge runtime missing Node.js APIs
-
-Severity: HIGH
-
-Situation: Using Node.js APIs in edge runtime functions
-
-Symptoms:
-- X is not defined at runtime
-- Cannot find module fs
-- Works locally, fails deployed
-- Middleware crashes
-
-Why this breaks:
-Edge runtime runs on V8, not Node.js. Many Node APIs are missing:
-fs, path, crypto (partial), child_process, and most native modules.
-Your code will fail at runtime with "X is not defined".
-
-Recommended fix:
-
-Check API compatibility before using edge:
-
-// SUPPORTED in Edge:
-// - fetch, Request, Response
-// - crypto.subtle (Web Crypto)
-// - TextEncoder, TextDecoder
-// - URL, URLSearchParams
-// - Headers, FormData
-// - setTimeout, setInterval
-
-// NOT SUPPORTED in Edge:
-// - fs, path, os
-// - Buffer (use Uint8Array)
-// - crypto.createHash (use crypto.subtle)
-// - Most npm packages with native deps
-
-// If you need Node.js APIs:
-export const runtime = 'nodejs'  // Use Node runtime instead
-
-// For crypto hashing in edge:
-// WRONG
-import { createHash } from 'crypto'  // Fails in edge
-
-// RIGHT
-async function hash(message: string) {
-  const encoder = new TextEncoder()
-  const data = encoder.encode(message)
-  const hashBuffer = await crypto.subtle.digest('SHA-256', data)
-  return Array.from(new Uint8Array(hashBuffer))
-    .map(b => b.toString(16).padStart(2, '0'))
-    .join('')
-}
-
-### Function timeout causes incomplete operations
-
-Severity: MEDIUM
-
-Situation: Long-running operations timing out
-
-Symptoms:
-- Task timed out after X seconds
-- Incomplete database operations
-- Partial file uploads
-- Function killed mid-execution
-
-Why this breaks:
-Vercel has timeout limits:
-- Hobby: 10 seconds
-- Pro: 60 seconds (can increase to 300)
-- Enterprise: 900 seconds
-
-Operations exceeding this are killed mid-execution.
-
-Recommended fix:
-
-Handle long operations properly:
-
-// 1. Return early, process async
-export async function POST(request: Request) {
-  const data = await request.json()
-
-  // Queue for background processing
-  await queue.add('process-data', data)
-
-  // Return immediately
-  return Response.json({ status: 'queued' })
-}
-
-// 2. Use streaming for long responses
-export async function GET() {
-  const stream = new ReadableStream({
-    async start(controller) {
-      for (const chunk of generateChunks()) {
-        controller.enqueue(chunk)
-        await sleep(100)  // Prevents timeout
-      }
-      controller.close()
-    }
-  })
-  return new Response(stream)
-}
-
-// 3. Use external services for heavy processing
-// - Trigger serverless function, return job ID
-// - Process in background (Inngest, Trigger.dev)
-// - Client polls for completion
-
-// 4. Increase timeout (Pro plan)
-// vercel.json:
-{
-  "functions": {
-    "app/api/slow/route.ts": {
-      "maxDuration": 60
-    }
-  }
-}
-
-### Environment variable missing at runtime but present at build
-
-Severity: MEDIUM
-
-Situation: Environment variable works in build but undefined at runtime
-
-Symptoms:
-- Env var is undefined in production
-- Value doesn't change after updating in dashboard
-- Works in dev, wrong value in production
-- Requires redeploy to update value
-
-Why this breaks:
-Some env vars are only available at build time (hardcoded into bundle).
-If you expect a runtime value but it was baked in at build, you get
-the build-time value or undefined.
-
-Recommended fix:
-
-Understand when env vars are read:
-
-// BUILD TIME (baked into bundle):
-// - NEXT_PUBLIC_* variables
-// - next.config.js
-// - generateStaticParams
-// - Static pages
-
-// RUNTIME (read on each request):
-// - Server Components (without cache)
-// - API Routes
-// - Server Actions
-// - Middleware
-
-// To force runtime reading:
-export const dynamic = 'force-dynamic'
-
-// For config that must be runtime:
-// Don't use NEXT_PUBLIC_, read on server and pass to client
-
-// Check which env vars you need:
-// Build: URLs, public keys, feature flags (if static)
-// Runtime: Secrets, database URLs, user-specific config
-
-### CORS errors calling API routes from different domain
-
-Severity: MEDIUM
-
-Situation: Frontend on different domain can't call API routes
-
-Symptoms:
-- CORS policy error in browser console
-- No Access-Control-Allow-Origin header
-- Requests work in Postman but not browser
-- Works same-origin, fails cross-origin
-
-Why this breaks:
-By default, browsers block cross-origin requests. Vercel doesn't
-automatically add CORS headers. If your frontend is on a different
-domain (or localhost in dev), requests fail.
-
-Recommended fix:
-
-Add CORS headers to API routes:
-
-// app/api/data/route.ts
-export async function GET(request: Request) {
-  const data = await fetchData()
-
-  return Response.json(data, {
-    headers: {
-      'Access-Control-Allow-Origin': '*',  // Or specific domain
-      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
-    },
-  })
-}
-
-// Handle preflight requests
-export async function OPTIONS() {
-  return new Response(null, {
-    headers: {
-      'Access-Control-Allow-Origin': '*',
-      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
-      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
-    },
-  })
-}
-
-// Or use next.config.js for all routes:
-module.exports = {
-  async headers() {
-    return [
-      {
-        source: '/api/:path*',
-        headers: [
-          { key: 'Access-Control-Allow-Origin', value: '*' },
-        ],
-      },
-    ]
-  },
-}
-
-### Page shows stale data after deployment
-
-Severity: MEDIUM
-
-Situation: Updated data not appearing after new deployment
-
-Symptoms:
-- Old content shows after deploy
-- Changes not visible immediately
-- Different users see different versions
-- Data updates but page doesn't
-
-Why this breaks:
-Vercel caches aggressively. Static pages are cached at the edge.
-Even dynamic pages may be cached if not configured properly.
-Old cached versions served until cache expires or is purged.
-
-Recommended fix:
-
-Control caching behavior:
-
-// Force no caching (always fresh)
-export const dynamic = 'force-dynamic'
-export const revalidate = 0
-
-// ISR - revalidate every 60 seconds
-export const revalidate = 60
-
-// On-demand revalidation (after mutation)
-import { revalidatePath, revalidateTag } from 'next/cache'
-
-// In Server Action:
-async function updatePost(id: string) {
-  await db.post.update({ ... })
-  revalidatePath(`/posts/${id}`)  // Purge this page
-  revalidateTag('posts')          // Purge all with this tag
-}
-
-// Purge via API (deployment hook):
-// POST https://your-site.vercel.app/api/revalidate?path=/posts
-
-// Check caching in response headers:
-// x-vercel-cache: HIT = served from cache
-// x-vercel-cache: MISS = freshly generated
-
-## Validation Checks
-
-### Secret in NEXT_PUBLIC Variable
-
-Severity: CRITICAL
-
-Message: Secret exposed via NEXT_PUBLIC_ prefix. This will be visible in browser.
-
-Fix action: Remove NEXT_PUBLIC_ prefix and access only in server-side code
-
-### Hardcoded Vercel URL
-
-Severity: WARNING
-
-Message: Hardcoded Vercel URL. Use VERCEL_URL environment variable instead.
-
-Fix action: Use process.env.VERCEL_URL or NEXT_PUBLIC_VERCEL_URL
-
-### Node.js API in Edge Runtime
-
-Severity: ERROR
-
-Message: Node.js module used in Edge runtime. fs/path not available in Edge.
-
-Fix action: Use runtime = 'nodejs' or remove Node.js dependencies
-
-### API Route Without CORS Headers
-
-Severity: WARNING
-
-Message: API route without CORS headers may fail cross-origin requests.
-
-Fix action: Add Access-Control-Allow-Origin header if API is called from other domains
-
-### API Route Without Error Handling
-
-Severity: WARNING
-
-Message: API route without try/catch. Unhandled errors return 500 without details.
-
-Fix action: Wrap in try/catch and return appropriate error responses
-
-### Secret Read in Static Context
-
-Severity: WARNING
-
-Message: Server secret accessed in static generation. Value baked into build.
-
-Fix action: Move secret access to runtime code or use NEXT_PUBLIC_ for public values
-
-### Large Package Import
-
-Severity: WARNING
-
-Message: Large package imported. May cause slow cold starts. Consider alternatives.
-
-Fix action: Use lodash-es with tree shaking, date-fns instead of moment, @aws-sdk/client-* instead of aws-sdk
-
-### Dynamic Page Without Revalidation Config
-
-Severity: WARNING
-
-Message: Dynamic page without revalidation config. Consider setting revalidation strategy.
-
-Fix action: Add export const revalidate = 60 for ISR, or 0 for no cache
-
-## Collaboration
-
-### Delegation Triggers
-
-- next.js|app router|pages|server components -> nextjs-app-router (Deployment needs Next.js patterns)
-- database|supabase|backend -> supabase-backend (Deployment needs database)
-- auth|authentication|session -> nextjs-supabase-auth (Deployment needs auth config)
-- monitoring|logs|errors|analytics -> analytics-architecture (Deployment needs monitoring)
-
-### Production Launch
-
-Skills: vercel-deployment, nextjs-app-router, supabase-backend, nextjs-supabase-auth
-
-Workflow:
-
-```
-1. App configuration (nextjs-app-router)
-2. Database setup (supabase-backend)
-3. Auth config (nextjs-supabase-auth)
-4. Deploy (vercel-deployment)
-```
-
-### CI/CD Pipeline
-
-Skills: vercel-deployment, devops, qa-engineering
-
-Workflow:
-
-```
-1. Test automation (qa-engineering)
-2. Pipeline config (devops)
-3. Deploy strategy (vercel-deployment)
-```
-
-## Related Skills
-
-Works well with: `nextjs-app-router`, `supabase-backend`
-
 ## When to Use
 - User mentions or implies: vercel
 - User mentions or implies: deploy