@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

package/skills/vercel-deploy-preview/SKILL.md

@@ -1,71 +1,196 @@
 ---
 name: vercel-deploy-preview
-description: |
-  Execute Vercel primary workflow: Deploy Preview.
-  Use when Deploying a preview for a pull request,
-  Testing changes before production, or Sharing preview URLs with stakeholders.
-  Trigger with phrases like "vercel deploy preview",
-  "create preview deployment with vercel".
-allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
+description: 'Create and manage Vercel preview deployments for branches and pull requests.
+
+  Use when deploying a preview for a pull request, testing changes before production,
+
+  or sharing preview URLs with stakeholders.
+
+  Trigger with phrases like "vercel deploy preview", "vercel preview URL",
+
+  "create preview deployment", "vercel PR preview".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(vercel:*), Bash(curl:*), Bash(git:*), Grep
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- deployment
+- preview
+- workflow
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel Deploy Preview
 
 ## Overview
-Deploy preview environments for pull requests and branches.
-This is the primary workflow for Vercel - instant previews for every commit.
 
+Deploy preview environments for branches and pull requests. Every `git push` to a non-production branch generates a unique preview URL. Covers CLI-based previews, API-based previews, deployment protection, and comment integration.
 
 ## Prerequisites
+
 - Completed `vercel-install-auth` setup
-- Understanding of Vercel core concepts
-- Valid API credentials configured
+- Project linked via `vercel link`
+- Git repository connected in Vercel dashboard
 
 ## Instructions
 
-### Step 1: Initialize
-```typescript
-// Step 1 implementation
+### Step 1: Deploy Preview via CLI
+
+```bash
+# Deploy current directory to a preview URL (default — not --prod)
+vercel
+
+# Output:
+# 🔗 Linked to your-team/my-app
+# 🔍 Inspect: https://vercel.com/your-team/my-app/AbCdEfG
+# ✅ Preview: https://my-app-git-feature-branch-your-team.vercel.app
+
+# Deploy a specific directory
+vercel ./dist
+
+# Deploy and wait for build to complete (useful in CI)
+vercel --no-wait  # returns immediately with deployment URL
 ```
 
-### Step 2: Execute
-```typescript
-// Step 2 implementation
+### Step 2: Deploy Preview via REST API
+
+```bash
+# Create a deployment via API — useful for custom CI pipelines
+curl -X POST "https://api.vercel.com/v13/deployments" \
+  -H "Authorization: Bearer $VERCEL_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my-app",
+    "target": "preview",
+    "gitSource": {
+      "type": "github",
+      "repoId": "123456789",
+      "ref": "feature/new-feature",
+      "sha": "abc123def456"
+    }
+  }'
+```
+
+### Step 3: Check Deployment Status
+
+```bash
+# Poll deployment status until READY
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v13/deployments/dpl_xxxxxxxxxxxx" \
+  | jq '{state: .state, url: .url, readyState: .readyState}'
+
+# States: QUEUED → BUILDING → READY (or ERROR/CANCELED)
 ```
 
-### Step 3: Finalize
 ```typescript
-// Step 3 implementation
+// Programmatic polling
+async function waitForDeployment(client: VercelClient, deploymentId: string) {
+  while (true) {
+    const d = await client.getDeployment(deploymentId);
+    if (d.state === 'READY') return d;
+    if (d.state === 'ERROR' || d.state === 'CANCELED') {
+      throw new Error(`Deployment ${d.state}: ${deploymentId}`);
+    }
+    await new Promise(r => setTimeout(r, 5000)); // poll every 5s
+  }
+}
 ```
 
-## Output
-- Completed Deploy Preview execution
-- Expected results from Vercel API
-- Success confirmation or error details
+### Step 4: Configure Preview Environment Variables
 
-## Error Handling
-| Error | Cause | Solution |
-|-------|-------|----------|
-| Error 1 | Cause | Solution |
-| Error 2 | Cause | Solution |
+```bash
+# Add env vars scoped to preview only
+vercel env add DATABASE_URL preview
+# Enter value when prompted
+
+# Or via API — scope to preview environment
+curl -X POST "https://api.vercel.com/v9/projects/my-app/env" \
+  -H "Authorization: Bearer $VERCEL_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "key": "DATABASE_URL",
+    "value": "postgres://preview-db:5432/myapp",
+    "type": "encrypted",
+    "target": ["preview"]
+  }'
+```
 
-## Examples
+### Step 5: Deployment Protection
 
-### Complete Workflow
-```typescript
-// Complete workflow example
+Vercel supports password-protecting preview deployments:
+
+```json
+// vercel.json — require authentication for previews
+{
+  "deploymentProtection": {
+    "preview": "vercel-authentication"
+  }
+}
+```
+
+Options:
+
+- `"vercel-authentication"` — requires Vercel team login
+- `"standard-protection"` — bypass for automation with `x-vercel-protection-bypass` header
+- Disabled — previews are publicly accessible
+
+### Step 6: GitHub Integration — PR Comments
+
+When a GitHub repo is connected, Vercel automatically:
+
+1. Creates a preview deployment on every push
+2. Posts a comment on the PR with the preview URL
+3. Updates the GitHub commit status (pending → success/failure)
+4. Adds "Visit Preview" link in the PR checks section
+
+To configure in the Vercel dashboard:
+
+- **Settings > Git > Deploy Hooks** for manual triggers
+- **Settings > Git > Ignored Build Step** to skip builds for certain paths
+
+```bash
+# Ignored Build Step — skip deploy when only docs changed
+# vercel.json
+{
+  "ignoreCommand": "git diff HEAD^ HEAD --quiet -- . ':!docs' ':!*.md'"
+}
 ```
 
-### Common Variations
-- Variation 1: Description
-- Variation 2: Description
+## Preview URL Patterns
+
+| Branch | URL Pattern |
+|--------|-------------|
+| `feature/auth` | `my-app-git-feature-auth-team.vercel.app` |
+| `fix/bug-123` | `my-app-git-fix-bug-123-team.vercel.app` |
+| Random deploy | `my-app-abc123def.vercel.app` |
+
+## Output
+
+- Preview deployment URL unique to each branch/commit
+- Build logs accessible via Vercel dashboard or API
+- PR comment with preview link (GitHub integration)
+- Environment variables scoped to preview only
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `BUILD_FAILED` | Build command failed | Check build logs: `vercel inspect <url>` |
+| `FUNCTION_INVOCATION_FAILED` | Runtime error in function | Review function logs: `vercel logs <url>` |
+| `NO_BUILDS` | No output detected | Verify `outputDirectory` in vercel.json |
+| Preview not updating | Cached old deployment | Force rebuild: `vercel --force` |
+| `DEPLOYMENT_BLOCKED` | Deployment protection active | Use `x-vercel-protection-bypass` header |
 
 ## Resources
-- [Vercel Documentation](https://vercel.com/docs)
-- [Vercel API Reference](https://vercel.com/docs/api)
+
+- [Preview Deployments](https://vercel.com/docs/deployments/preview-deployments)
+- [Deployment Protection](https://vercel.com/docs/security/deployment-protection)
+- [CLI Deploy Command](https://vercel.com/docs/cli/deploy)
+- [REST API: Create Deployment](https://vercel.com/docs/rest-api/deployments/create-a-new-deployment)
 
 ## Next Steps
-For secondary workflow, see `vercel-edge-functions`.
+
+For edge function development, see `vercel-edge-functions`.

package/skills/vercel-edge-functions/SKILL.md

@@ -1,73 +1,221 @@
 ---
 name: vercel-edge-functions
-description: |
-  Execute Vercel secondary workflow: Edge Functions.
-  Use when API routes with minimal latency,
-  or complementing primary workflow.
-  Trigger with phrases like "vercel edge function",
-  "deploy edge function with vercel".
-allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
+description: 'Build and deploy Vercel Edge Functions for ultra-low latency at the
+  edge.
+
+  Use when creating API routes with minimal latency, geolocation-based routing,
+
+  A/B testing, or authentication at the edge.
+
+  Trigger with phrases like "vercel edge function", "vercel edge runtime",
+
+  "deploy edge function", "vercel middleware", "@vercel/edge".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(vercel:*), Bash(npm:*), Grep
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- edge
+- serverless
+- performance
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel Edge Functions
 
 ## Overview
-Build and deploy Edge Functions for ultra-low latency at the edge.
-Serverless functions that run close to users worldwide.
 
+Edge Functions run on Vercel's Edge Network (V8 isolates) close to the user with no cold starts. They use Web Standard APIs (Request, Response, fetch) instead of Node.js APIs. Ideal for authentication, A/B testing, geolocation routing, and low-latency API responses.
 
 ## Prerequisites
+
 - Completed `vercel-install-auth` setup
-- Familiarity with `vercel-deploy-preview`
-- Valid API credentials configured
+- Familiarity with Web APIs (Request/Response)
+- Node.js 18+ for local development
 
 ## Instructions
 
-### Step 1: Setup
+### Step 1: Create an Edge Function
+
 ```typescript
-// Step 1 implementation
+// api/edge-hello.ts
+// Export `runtime = 'edge'` to run on the Edge Runtime
+export const config = { runtime: 'edge' };
+
+export default function handler(request: Request): Response {
+  return new Response(
+    JSON.stringify({
+      message: 'Hello from the Edge!',
+      region: request.headers.get('x-vercel-ip-city') ?? 'unknown',
+      timestamp: Date.now(),
+    }),
+    {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    }
+  );
+}
 ```
 
-### Step 2: Process
+### Step 2: Edge Function with Geolocation
+
+Vercel injects geolocation headers into every edge request:
+
 ```typescript
-// Step 2 implementation
+// api/geo.ts
+export const config = { runtime: 'edge' };
+
+export default function handler(request: Request): Response {
+  const city = request.headers.get('x-vercel-ip-city') ?? 'unknown';
+  const country = request.headers.get('x-vercel-ip-country') ?? 'unknown';
+  const region = request.headers.get('x-vercel-ip-country-region') ?? 'unknown';
+  const latitude = request.headers.get('x-vercel-ip-latitude');
+  const longitude = request.headers.get('x-vercel-ip-longitude');
+
+  return Response.json({
+    city: decodeURIComponent(city),
+    country,
+    region,
+    coordinates: latitude && longitude ? { lat: latitude, lng: longitude } : null,
+  });
+}
 ```
 
-### Step 3: Complete
+### Step 3: Edge Middleware (middleware.ts)
+
+Middleware runs before every request and can rewrite, redirect, or add headers:
+
 ```typescript
-// Step 3 implementation
-```
+// middleware.ts (must be at project root or src/)
+import { NextRequest, NextResponse } from 'next/server';
 
-## Output
-- Completed Edge Functions execution
-- Results from Vercel API
-- Success confirmation or error details
+export function middleware(request: NextRequest) {
+  // Example 1: Redirect based on country
+  const country = request.geo?.country ?? 'US';
+  if (country === 'DE') {
+    return NextResponse.redirect(new URL('/de', request.url));
+  }
 
-## Error Handling
-| Aspect | Deploy Preview | Edge Functions |
-|--------|------------|------------|
-| Use Case | Deploying a preview for a pull request | API routes with minimal latency |
-| Complexity | Medium | Medium |
-| Performance | Standard | Ultra-fast (<50ms) |
+  // Example 2: A/B testing with cookies
+  const bucket = request.cookies.get('ab-bucket')?.value;
+  if (!bucket) {
+    const response = NextResponse.next();
+    response.cookies.set('ab-bucket', Math.random() > 0.5 ? 'a' : 'b');
+    return response;
+  }
+
+  // Example 3: Add security headers
+  const response = NextResponse.next();
+  response.headers.set('X-Frame-Options', 'DENY');
+  response.headers.set('X-Content-Type-Options', 'nosniff');
+  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+  return response;
+}
+
+// Only run on specific paths — skip static assets
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+};
+```
 
-## Examples
+### Step 4: Edge Function with Streaming
 
-### Complete Workflow
 ```typescript
-// Complete workflow example
+// api/stream.ts
+export const config = { runtime: 'edge' };
+
+export default function handler(): Response {
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    async start(controller) {
+      for (let i = 0; i < 5; i++) {
+        controller.enqueue(encoder.encode(`data: chunk ${i}\n\n`));
+        await new Promise(r => setTimeout(r, 500));
+      }
+      controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+      controller.close();
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    },
+  });
+}
 ```
 
-### Error Recovery
+### Step 5: Edge Config (Key-Value Store)
+
 ```typescript
-// Error handling code
+// api/feature-flags.ts
+import { get } from '@vercel/edge-config';
+
+export const config = { runtime: 'edge' };
+
+export default async function handler(): Promise<Response> {
+  // Read from Edge Config — sub-millisecond reads at the edge
+  const maintenanceMode = await get<boolean>('maintenance_mode');
+  const featureFlags = await get<Record<string, boolean>>('feature_flags');
+
+  if (maintenanceMode) {
+    return Response.json({ status: 'maintenance' }, { status: 503 });
+  }
+
+  return Response.json({ features: featureFlags });
+}
 ```
 
+Install: `npm install @vercel/edge-config`
+
+## Edge vs Serverless Comparison
+
+| Feature | Edge Runtime | Node.js (Serverless) |
+|---------|-------------|---------------------|
+| Cold start | None (~0ms) | 250ms–1s+ |
+| Max duration | 30s (Hobby), 5min (Pro) | 10s (Hobby), 5min (Pro) |
+| Max size | 1 MB (after gzip) | 250 MB (unzipped) |
+| APIs available | Web Standard APIs | Full Node.js API |
+| npm packages | Limited (no native modules) | All npm packages |
+| Global deployment | Automatic | Single region default |
+| Use case | Auth, routing, A/B, geo | Database queries, heavy compute |
+
+## Available Web APIs in Edge Runtime
+
+`fetch`, `Request`, `Response`, `Headers`, `URL`, `URLSearchParams`, `TextEncoder`, `TextDecoder`, `ReadableStream`, `WritableStream`, `TransformStream`, `crypto`, `atob`, `btoa`, `structuredClone`, `setTimeout`, `setInterval`, `AbortController`
+
+**NOT available**: `fs`, `path`, `child_process`, `net`, `http`, `dns`, native Node.js modules
+
+## Output
+
+- Edge Function deployed globally with zero cold starts
+- Geolocation-based routing using Vercel's injected headers
+- Middleware running authentication and A/B tests at the edge
+- Streaming responses for real-time data delivery
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `EDGE_FUNCTION_INVOCATION_FAILED` | Runtime error in edge function | Check logs — no `try/catch` around async code |
+| `Dynamic Code Evaluation not allowed` | Using `eval()` or `new Function()` | Refactor to avoid dynamic code evaluation |
+| `Module not found` | npm package uses Node.js APIs | Use edge-compatible alternative or switch to Node.js runtime |
+| `FUNCTION_PAYLOAD_TOO_LARGE` | Edge function bundle > 1 MB | Tree-shake imports, split into smaller functions |
+| `TypeError: x is not a function` | Node.js API used in edge runtime | Replace with Web Standard API equivalent |
+
 ## Resources
-- [Vercel Documentation](https://vercel.com/docs)
-- [Vercel API Reference](https://vercel.com/docs/api)
+
+- [Edge Functions Documentation](https://vercel.com/docs/functions/runtimes/edge)
+- [Edge Middleware](https://vercel.com/docs/functions/edge-middleware)
+- [Edge Config](https://vercel.com/docs/edge-config)
+- [Edge Runtime API](https://vercel.com/docs/functions/runtimes/edge)
+- [Vercel Geolocation Headers](https://vercel.com/docs/headers/request-headers)
 
 ## Next Steps
-For common errors, see `vercel-common-errors`.
+
+For common errors, see `vercel-common-errors`.