@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

package/skills/vercel-reference-architecture/SKILL.md

@@ -1,238 +1,284 @@
 ---
 name: vercel-reference-architecture
-description: |
-  Implement Vercel reference architecture with best-practice project layout.
-  Use when designing new Vercel integrations, reviewing project structure,
+description: 'Implement a Vercel reference architecture with layered project structure
+  and best practices.
+
+  Use when designing new Vercel projects, reviewing project structure,
+
   or establishing architecture standards for Vercel applications.
-  Trigger with phrases like "vercel architecture", "vercel best practices",
-  "vercel project structure", "how to organize vercel", "vercel layout".
-allowed-tools: Read, Grep
+
+  Trigger with phrases like "vercel architecture", "vercel project structure",
+
+  "vercel best practices layout", "how to organize vercel project".
+
+  '
+allowed-tools: Read, Write, Edit, Grep
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- architecture
+- best-practices
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel Reference Architecture
 
 ## Overview
-Production-ready architecture patterns for Vercel integrations.
+
+Implement a production-ready Vercel project architecture with clear separation across edge, server, and client layers. Covers directory structure, middleware patterns, API route organization, shared utilities, and configuration management.
 
 ## Prerequisites
-- Understanding of layered architecture
-- Vercel SDK knowledge
+
+- Understanding of Vercel's deployment model (edge, serverless, static)
 - TypeScript project setup
-- Testing framework configured
+- Next.js 14+ (recommended) or other Vercel-supported framework
 
-## Project Structure
+## Instructions
+
+### Step 1: Directory Structure
 
 ```
-my-vercel-project/
+my-vercel-app/
+├── public/                    # Static assets (served from CDN)
+│   ├── favicon.ico
+│   └── images/
 ├── src/
-│   ├── vercel/
-│   │   ├── client.ts           # Singleton client wrapper
-│   │   ├── config.ts           # Environment configuration
-│   │   ├── types.ts            # TypeScript types
-│   │   ├── errors.ts           # Custom error classes
-│   │   └── handlers/
-│   │       ├── webhooks.ts     # Webhook handlers
-│   │       └── events.ts       # Event processing
-│   ├── services/
-│   │   └── vercel/
-│   │       ├── index.ts        # Service facade
-│   │       ├── sync.ts         # Data synchronization
-│   │       └── cache.ts        # Caching layer
-│   ├── api/
-│   │   └── vercel/
-│   │       └── webhook.ts      # Webhook endpoint
-│   └── jobs/
-│       └── vercel/
-│           └── sync.ts         # Background sync job
-├── tests/
-│   ├── unit/
-│   │   └── vercel/
-│   └── integration/
-│       └── vercel/
-├── config/
-│   ├── vercel.development.json
-│   ├── vercel.staging.json
-│   └── vercel.production.json
-└── docs/
-    └── vercel/
-        ├── SETUP.md
-        └── RUNBOOK.md
+│   ├── app/                   # Next.js App Router pages
+│   │   ├── layout.tsx         # Root layout
+│   │   ├── page.tsx           # Home page
+│   │   ├── api/               # API routes (serverless functions)
+│   │   │   ├── health/route.ts
+│   │   │   ├── users/route.ts
+│   │   │   └── webhooks/
+│   │   │       └── vercel/route.ts
+│   │   ├── dashboard/         # Protected pages
+│   │   │   ├── layout.tsx
+│   │   │   └── page.tsx
+│   │   └── (marketing)/       # Public pages (route group)
+│   │       ├── pricing/page.tsx
+│   │       └── about/page.tsx
+│   ├── lib/                   # Shared utilities (server + client)
+│   │   ├── api-client.ts      # External API wrapper
+│   │   ├── db.ts              # Database client (lazy singleton)
+│   │   ├── env.ts             # Typed environment variables
+│   │   └── errors.ts          # Error classes
+│   ├── components/            # React components
+│   │   ├── ui/                # Design system primitives
+│   │   └── features/          # Feature-specific components
+│   └── middleware.ts          # Edge Middleware (auth, redirects)
+├── vercel.json                # Vercel configuration
+├── next.config.js             # Next.js configuration
+├── tsconfig.json
+├── package.json
+└── .env.example               # Required env vars (no values)
 ```
 
-## Layer Architecture
+### Step 2: Typed Environment Variables
 
-```
-┌─────────────────────────────────────────┐
-│             API Layer                    │
-│   (Controllers, Routes, Webhooks)        │
-├─────────────────────────────────────────┤
-│           Service Layer                  │
-│  (Business Logic, Orchestration)         │
-├─────────────────────────────────────────┤
-│          Vercel Layer        │
-│   (Client, Types, Error Handling)        │
-├─────────────────────────────────────────┤
-│         Infrastructure Layer             │
-│    (Cache, Queue, Monitoring)            │
-└─────────────────────────────────────────┘
+```typescript
+// src/lib/env.ts — validate env vars at import time
+import { z } from 'zod';
+
+const envSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  API_SECRET: z.string().min(16),
+  NEXT_PUBLIC_API_URL: z.string().url(),
+  VERCEL_ENV: z.enum(['production', 'preview', 'development']).default('development'),
+  VERCEL_URL: z.string().optional(),
+});
+
+// Fails fast at startup if env vars are missing
+export const env = envSchema.parse(process.env);
+
+// Type-safe access throughout the app
+// Usage: import { env } from '@/lib/env'; env.DATABASE_URL
 ```
 
-## Key Components
+### Step 3: Database Client (Lazy Singleton)
 
-### Step 1: Client Wrapper
 ```typescript
-// src/vercel/client.ts
-export class VercelService {
-  private client: VercelClient;
-  private cache: Cache;
-  private monitor: Monitor;
-
-  constructor(config: VercelConfig) {
-    this.client = new VercelClient(config);
-    this.cache = new Cache(config.cacheOptions);
-    this.monitor = new Monitor('vercel');
-  }
+// src/lib/db.ts — lazy init to minimize cold starts
+import { PrismaClient } from '@prisma/client';
 
-  async get(id: string): Promise<Resource> {
-    return this.cache.getOrFetch(id, () =>
-      this.monitor.track('get', () => this.client.get(id))
-    );
-  }
+const globalForPrisma = globalThis as unknown as { prisma: PrismaClient | undefined };
+
+export const db = globalForPrisma.prisma ?? new PrismaClient({
+  log: process.env.VERCEL_ENV === 'development' ? ['query'] : ['error'],
+});
+
+// Prevent multiple instances in development (hot reload)
+if (process.env.VERCEL_ENV !== 'production') {
+  globalForPrisma.prisma = db;
 }
 ```
 
-### Step 2: Error Boundary
+### Step 4: API Route Pattern
+
 ```typescript
-// src/vercel/errors.ts
-export class VercelServiceError extends Error {
-  constructor(
-    message: string,
-    public readonly code: string,
-    public readonly retryable: boolean,
-    public readonly originalError?: Error
-  ) {
-    super(message);
-    this.name = 'VercelServiceError';
-  }
-}
+// src/app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+import { env } from '@/lib/env';
+
+export async function GET(request: NextRequest) {
+  try {
+    const searchParams = request.nextUrl.searchParams;
+    const limit = Number(searchParams.get('limit') ?? 20);
 
-export function wrapVercelError(error: unknown): VercelServiceError {
-  // Transform SDK errors to application errors
+    const users = await db.user.findMany({ take: limit });
+    return NextResponse.json({ users }, {
+      headers: { 'Cache-Control': 's-maxage=60, stale-while-revalidate=300' },
+    });
+  } catch (error) {
+    console.error('GET /api/users failed:', error);
+    return NextResponse.json(
+      { error: 'Internal server error', requestId: crypto.randomUUID() },
+      { status: 500 }
+    );
+  }
 }
-```
 
-### Step 3: Health Check
-```typescript
-// src/vercel/health.ts
-export async function checkVercelHealth(): Promise<HealthStatus> {
+export async function POST(request: NextRequest) {
   try {
-    const start = Date.now();
-    await vercelClient.ping();
-    return {
-      status: 'healthy',
-      latencyMs: Date.now() - start,
-    };
+    const body = await request.json();
+    const user = await db.user.create({ data: body });
+    return NextResponse.json({ user }, { status: 201 });
   } catch (error) {
-    return { status: 'unhealthy', error: error.message };
+    console.error('POST /api/users failed:', error);
+    return NextResponse.json(
+      { error: 'Failed to create user' },
+      { status: 400 }
+    );
   }
 }
 ```
 
-## Data Flow Diagram
+### Step 5: Edge Middleware for Auth
 
-```
-User Request
-     │
-     ▼
-┌─────────────┐
-│   API       │
-│   Gateway   │
-└──────┬──────┘
-       │
-       ▼
-┌─────────────┐    ┌─────────────┐
-│   Service   │───▶│   Cache     │
-│   Layer     │    │   (Redis)   │
-└──────┬──────┘    └─────────────┘
-       │
-       ▼
-┌─────────────┐
-│ Vercel    │
-│   Client    │
-└──────┬──────┘
-       │
-       ▼
-┌─────────────┐
-│ Vercel    │
-│   API       │
-└─────────────┘
+```typescript
+// src/middleware.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // Skip auth for public routes
+  if (pathname.startsWith('/api/health') || pathname.startsWith('/api/webhooks')) {
+    return NextResponse.next();
+  }
+
+  // Check auth for dashboard routes
+  if (pathname.startsWith('/dashboard') || pathname.startsWith('/api/')) {
+    const token = request.cookies.get('session')?.value;
+    if (!token) {
+      if (pathname.startsWith('/api/')) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+      return NextResponse.redirect(new URL('/login', request.url));
+    }
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+};
 ```
 
-## Configuration Management
+### Step 6: Health Check Endpoint
 
 ```typescript
-// config/vercel.ts
-export interface VercelConfig {
-  apiKey: string;
-  environment: 'development' | 'staging' | 'production';
-  timeout: number;
-  retries: number;
-  cache: {
-    enabled: boolean;
-    ttlSeconds: number;
-  };
-}
+// src/app/api/health/route.ts
+import { db } from '@/lib/db';
+
+export const dynamic = 'force-dynamic'; // Never cache health checks
 
-export function loadVercelConfig(): VercelConfig {
-  const env = process.env.NODE_ENV || 'development';
-  return require(`./vercel.${env}.json`);
+export async function GET() {
+  const checks: Record<string, 'ok' | 'error'> = {};
+
+  // Database connectivity
+  try {
+    await db.$queryRaw`SELECT 1`;
+    checks.database = 'ok';
+  } catch {
+    checks.database = 'error';
+  }
+
+  const allHealthy = Object.values(checks).every(v => v === 'ok');
+
+  return Response.json({
+    status: allHealthy ? 'healthy' : 'degraded',
+    checks,
+    version: process.env.VERCEL_GIT_COMMIT_SHA?.slice(0, 7) ?? 'local',
+    region: process.env.VERCEL_REGION ?? 'local',
+    timestamp: new Date().toISOString(),
+  }, {
+    status: allHealthy ? 200 : 503,
+  });
 }
 ```
 
-## Instructions
-
-### Step 1: Create Directory Structure
-Set up the project layout following the reference structure above.
+### Step 7: Vercel Configuration
 
-### Step 2: Implement Client Wrapper
-Create the singleton client with caching and monitoring.
+```json
+// vercel.json
+{
+  "regions": ["iad1"],
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "X-Content-Type-Options", "value": "nosniff" },
+        { "key": "X-Frame-Options", "value": "DENY" },
+        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
+      ]
+    }
+  ],
+  "rewrites": [
+    { "source": "/docs/:path*", "destination": "https://docs.example.com/:path*" }
+  ],
+  "redirects": [
+    { "source": "/old-page", "destination": "/new-page", "permanent": true }
+  ]
+}
+```
 
-### Step 3: Add Error Handling
-Implement custom error classes for Vercel operations.
+## Layer Responsibilities
 
-### Step 4: Configure Health Checks
-Add health check endpoint for Vercel connectivity.
+| Layer | Runtime | Responsibilities |
+|-------|---------|-----------------|
+| Edge (middleware.ts) | V8 isolates | Auth, redirects, A/B testing, headers |
+| Server (api routes) | Node.js | Database queries, business logic, webhooks |
+| Static (pages) | CDN | Pre-rendered pages, ISR, images |
+| Client (components) | Browser | Interactivity, client state |
 
 ## Output
-- Structured project layout
-- Client wrapper with caching
-- Error boundary implemented
-- Health checks configured
+
+- Layered project structure with clear separation of concerns
+- Typed environment variables validated at startup
+- Lazy-initialized database client minimizing cold starts
+- Edge Middleware handling authentication before server layer
+- Health check endpoint for deployment verification
 
 ## Error Handling
-| Issue | Cause | Solution |
+
+| Error | Cause | Solution |
 |-------|-------|----------|
-| Circular dependencies | Wrong layering | Separate concerns by layer |
-| Config not loading | Wrong paths | Verify config file locations |
-| Type errors | Missing types | Add Vercel types |
-| Test isolation | Shared state | Use dependency injection |
-
-## Examples
-
-### Quick Setup Script
-```bash
-# Create reference structure
-mkdir -p src/vercel/{handlers} src/services/vercel src/api/vercel
-touch src/vercel/{client,config,types,errors}.ts
-touch src/services/vercel/{index,sync,cache}.ts
-```
+| Env validation fails on deploy | Missing required variable | Add to Vercel dashboard for target environment |
+| Middleware runs on static assets | Matcher too broad | Add exclusions for `_next/static`, `_next/image` |
+| Database connection pool exhausted | Too many concurrent functions | Use connection pooler (PgBouncer, Prisma Accelerate) |
+| API route not found | Wrong directory structure | Must be in `src/app/api/` with `route.ts` filename |
 
 ## Resources
-- [Vercel SDK Documentation](https://vercel.com/docs/sdk)
-- [Vercel Best Practices](https://vercel.com/docs/best-practices)
 
-## Flagship Skills
-For multi-environment setup, see `vercel-multi-env-setup`.
+- [Next.js Project Structure](https://nextjs.org/docs/getting-started/project-structure)
+- [Vercel Project Configuration](https://vercel.com/docs/project-configuration)
+- [Middleware Documentation](https://vercel.com/docs/functions/edge-middleware)
+- [API Routes (App Router)](https://nextjs.org/docs/app/building-your-application/routing/route-handlers)
+
+## Next Steps
+
+For multi-environment setup, see `vercel-multi-env-setup`.

package/skills/vercel-reference-architecture/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Circular dependencies | Wrong layering | Separate concerns by layer |
+| Config not loading | Wrong paths | Verify config file locations |
+| Type errors | Missing types | Add Vercel types |
+| Test isolation | Shared state | Use dependency injection |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-reference-architecture/references/examples.md

@@ -0,0 +1,13 @@
+## Examples
+
+### Quick Setup Script
+
+```bash
+# Create reference structure
+mkdir -p src/vercel/{handlers} src/services/vercel src/api/vercel
+touch src/vercel/{client,config,types,errors}.ts
+touch src/services/vercel/{index,sync,cache}.ts
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-reference-architecture/references/key-components.md

@@ -0,0 +1,65 @@
+# Key Components
+
+## Key Components
+
+### Step 1: Client Wrapper
+
+```typescript
+// src/vercel/client.ts
+export class VercelService {
+  private client: VercelClient;
+  private cache: Cache;
+  private monitor: Monitor;
+
+  constructor(config: VercelConfig) {
+    this.client = new VercelClient(config);
+    this.cache = new Cache(config.cacheOptions);
+    this.monitor = new Monitor('vercel');
+  }
+
+  async get(id: string): Promise<Resource> {
+    return this.cache.getOrFetch(id, () =>
+      this.monitor.track('get', () => this.client.get(id))
+    );
+  }
+}
+```
+
+### Step 2: Error Boundary
+
+```typescript
+// src/vercel/errors.ts
+export class VercelServiceError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly retryable: boolean,
+    public readonly originalError?: Error
+  ) {
+    super(message);
+    this.name = 'VercelServiceError';
+  }
+}
+
+export function wrapVercelError(error: unknown): VercelServiceError {
+  // Transform SDK errors to application errors
+}
+```
+
+### Step 3: Health Check
+
+```typescript
+// src/vercel/health.ts
+export async function checkVercelHealth(): Promise<HealthStatus> {
+  try {
+    const start = Date.now();
+    await vercelClient.ping();
+    return {
+      status: 'healthy',
+      latencyMs: Date.now() - start,
+    };
+  } catch (error) {
+    return { status: 'unhealthy', error: error.message };
+  }
+}
+```

package/skills/vercel-reference-architecture/references/project-structure.md

@@ -0,0 +1,40 @@
+# Project Structure
+
+## Project Structure
+
+```
+my-vercel-project/
+├── src/
+│   ├── vercel/
+│   │   ├── client.ts           # Singleton client wrapper
+│   │   ├── config.ts           # Environment configuration
+│   │   ├── types.ts            # TypeScript types
+│   │   ├── errors.ts           # Custom error classes
+│   │   └── handlers/
+│   │       ├── webhooks.ts     # Webhook handlers
+│   │       └── events.ts       # Event processing
+│   ├── services/
+│   │   └── vercel/
+│   │       ├── index.ts        # Service facade
+│   │       ├── sync.ts         # Data synchronization
+│   │       └── cache.ts        # Caching layer
+│   ├── api/
+│   │   └── vercel/
+│   │       └── webhook.ts      # Webhook endpoint
+│   └── jobs/
+│       └── vercel/
+│           └── sync.ts         # Background sync job
+├── tests/
+│   ├── unit/
+│   │   └── vercel/
+│   └── integration/
+│       └── vercel/
+├── config/
+│   ├── vercel.development.json
+│   ├── vercel.staging.json
+│   └── vercel.production.json
+└── docs/
+    └── vercel/
+        ├── SETUP.md
+        └── RUNBOOK.md
+```