create-claude-webapp 1.0.0 → 1.0.1

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

@@ -0,0 +1,407 @@
+---
+name: vercel-edge
+description: Vercel Edge runtime, middleware patterns, and Edge Functions. Use when implementing edge logic, middleware, or geo-routing.
+---
+
+# Vercel Edge Runtime
+
+## Edge Runtime Constraints
+
+### What's NOT Available
+The Edge runtime uses V8 isolates, not Node.js. These APIs are unavailable:
+
+| Unavailable | Alternative |
+|-------------|-------------|
+| `fs` module | Use fetch for remote files |
+| `path` module | String manipulation |
+| `crypto` (Node.js) | Web Crypto API |
+| `Buffer` (full) | Use Uint8Array |
+| Native modules | Pure JS alternatives |
+| Long-running processes | Use serverless functions |
+
+### What IS Available
+- Web standard APIs (fetch, Request, Response)
+- Web Crypto API
+- TextEncoder/TextDecoder
+- URL and URLSearchParams
+- setTimeout (limited)
+- console methods
+
+### Execution Limits
+| Limit | Value |
+|-------|-------|
+| Memory | 128 MB |
+| CPU time | 50ms (Hobby), unlimited (Pro) |
+| Duration | 30s |
+| Response body | 4 MB |
+
+## Middleware Patterns
+
+### Basic Middleware Structure
+```typescript
+// middleware.ts (at project root)
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  // Your logic here
+  return NextResponse.next()
+}
+
+// Configure which paths trigger middleware
+export const config = {
+  matcher: [
+    /*
+     * Match all request paths except:
+     * - _next/static (static files)
+     * - _next/image (image optimization)
+     * - favicon.ico (favicon file)
+     * - public files
+     */
+    '/((?!_next/static|_next/image|favicon.ico|.*\\..*$).*)',
+  ],
+}
+```
+
+### Authentication Middleware
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+const protectedPaths = ['/dashboard', '/settings', '/api/protected']
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl
+
+  // Check if path is protected
+  const isProtected = protectedPaths.some(path => pathname.startsWith(path))
+
+  if (!isProtected) {
+    return NextResponse.next()
+  }
+
+  // Check for auth token
+  const token = request.cookies.get('auth-token')?.value
+
+  if (!token) {
+    // Redirect to login
+    const loginUrl = new URL('/login', request.url)
+    loginUrl.searchParams.set('redirect', pathname)
+    return NextResponse.redirect(loginUrl)
+  }
+
+  // Verify token (simplified - use proper JWT verification)
+  try {
+    // Token validation logic
+    return NextResponse.next()
+  } catch {
+    // Invalid token, redirect to login
+    const response = NextResponse.redirect(new URL('/login', request.url))
+    response.cookies.delete('auth-token')
+    return response
+  }
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/settings/:path*', '/api/protected/:path*'],
+}
+```
+
+### Geo-Routing Middleware
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+const COUNTRY_REDIRECTS: Record<string, string> = {
+  DE: '/de',
+  FR: '/fr',
+  ES: '/es',
+}
+
+export function middleware(request: NextRequest) {
+  const country = request.geo?.country || 'US'
+
+  // Skip if already on localized path
+  const { pathname } = request.nextUrl
+  if (pathname.startsWith('/de') || pathname.startsWith('/fr') || pathname.startsWith('/es')) {
+    return NextResponse.next()
+  }
+
+  // Redirect to localized version
+  const redirect = COUNTRY_REDIRECTS[country]
+  if (redirect && pathname === '/') {
+    return NextResponse.redirect(new URL(redirect, request.url))
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: '/',
+}
+```
+
+### A/B Testing Middleware
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+const EXPERIMENT_COOKIE = 'ab-experiment'
+const VARIANTS = ['control', 'variant-a', 'variant-b']
+
+export function middleware(request: NextRequest) {
+  // Check for existing experiment assignment
+  let variant = request.cookies.get(EXPERIMENT_COOKIE)?.value
+
+  // Assign variant if not already assigned
+  if (!variant || !VARIANTS.includes(variant)) {
+    variant = VARIANTS[Math.floor(Math.random() * VARIANTS.length)]
+  }
+
+  // Rewrite to variant path
+  const url = request.nextUrl.clone()
+  url.pathname = `/${variant}${url.pathname}`
+
+  const response = NextResponse.rewrite(url)
+
+  // Set cookie for consistent experience
+  response.cookies.set(EXPERIMENT_COOKIE, variant, {
+    maxAge: 60 * 60 * 24 * 30, // 30 days
+    httpOnly: true,
+    sameSite: 'lax',
+  })
+
+  return response
+}
+
+export const config = {
+  matcher: '/landing-page',
+}
+```
+
+### Rate Limiting Middleware
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+// Note: For production, use Edge Config or external store
+const rateLimitMap = new Map<string, { count: number; timestamp: number }>()
+
+const RATE_LIMIT = 100 // requests
+const WINDOW_MS = 60 * 1000 // 1 minute
+
+export function middleware(request: NextRequest) {
+  const ip = request.ip ?? request.headers.get('x-forwarded-for') ?? 'unknown'
+
+  const now = Date.now()
+  const record = rateLimitMap.get(ip)
+
+  if (!record || now - record.timestamp > WINDOW_MS) {
+    rateLimitMap.set(ip, { count: 1, timestamp: now })
+    return NextResponse.next()
+  }
+
+  if (record.count >= RATE_LIMIT) {
+    return new NextResponse('Too Many Requests', {
+      status: 429,
+      headers: {
+        'Retry-After': String(Math.ceil((WINDOW_MS - (now - record.timestamp)) / 1000)),
+      },
+    })
+  }
+
+  record.count++
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: '/api/:path*',
+}
+```
+
+## Edge Functions
+
+### Creating Edge API Routes
+```typescript
+// app/api/edge-example/route.ts
+export const runtime = 'edge'
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url)
+  const name = searchParams.get('name') || 'World'
+
+  return Response.json({ message: `Hello ${name}!` })
+}
+
+export async function POST(request: Request) {
+  const body = await request.json()
+
+  return Response.json({ received: body })
+}
+```
+
+### Edge Function with Geo Data
+```typescript
+// app/api/geo/route.ts
+export const runtime = 'edge'
+
+export async function GET(request: Request) {
+  // Access geo data from headers (Vercel sets these)
+  const country = request.headers.get('x-vercel-ip-country') || 'Unknown'
+  const city = request.headers.get('x-vercel-ip-city') || 'Unknown'
+  const region = request.headers.get('x-vercel-ip-country-region') || 'Unknown'
+
+  return Response.json({
+    country,
+    city,
+    region,
+  })
+}
+```
+
+## Edge Config
+
+### Setup
+```bash
+# Create Edge Config store in Vercel Dashboard
+# Project > Storage > Create Edge Config
+
+# Install SDK
+npm install @vercel/edge-config
+```
+
+### Using Edge Config
+```typescript
+// app/api/feature-flags/route.ts
+export const runtime = 'edge'
+
+import { get } from '@vercel/edge-config'
+
+export async function GET() {
+  const flags = await get('featureFlags')
+
+  return Response.json({ flags })
+}
+```
+
+### Feature Flags Pattern
+```typescript
+// lib/features.ts
+import { get } from '@vercel/edge-config'
+
+export interface FeatureFlags {
+  newDashboard: boolean
+  betaFeatures: boolean
+  maintenanceMode: boolean
+}
+
+export async function getFeatureFlags(): Promise<FeatureFlags> {
+  const flags = await get<FeatureFlags>('featureFlags')
+
+  return flags ?? {
+    newDashboard: false,
+    betaFeatures: false,
+    maintenanceMode: false,
+  }
+}
+
+// Usage in Edge middleware
+import { getFeatureFlags } from '@/lib/features'
+
+export async function middleware(request: NextRequest) {
+  const flags = await getFeatureFlags()
+
+  if (flags.maintenanceMode) {
+    return NextResponse.rewrite(new URL('/maintenance', request.url))
+  }
+
+  return NextResponse.next()
+}
+```
+
+### Updating Edge Config
+```typescript
+// Via API (from serverless function, not edge)
+import { createClient } from '@vercel/edge-config'
+
+const client = createClient(process.env.EDGE_CONFIG)
+
+// Read
+const value = await client.get('key')
+
+// Note: Writing requires Vercel API
+// Use Vercel dashboard or API for updates
+```
+
+## Caching at the Edge
+
+### Cache Headers
+```typescript
+export const runtime = 'edge'
+
+export async function GET() {
+  const data = await fetchData()
+
+  return Response.json(data, {
+    headers: {
+      'Cache-Control': 's-maxage=3600, stale-while-revalidate=86400',
+    },
+  })
+}
+```
+
+### Cache Strategies
+
+| Strategy | Header | Use Case |
+|----------|--------|----------|
+| Static | `s-maxage=31536000, immutable` | Assets that never change |
+| Revalidate | `s-maxage=60, stale-while-revalidate=3600` | Frequently updated content |
+| No cache | `no-store` | Personalized/dynamic data |
+
+## Best Practices
+
+### Performance
+- Keep middleware fast (<50ms)
+- Avoid heavy computations
+- Use Edge Config for configuration data
+- Cache responses where possible
+
+### Security
+- Validate all inputs
+- Use secure cookie settings
+- Implement proper CORS
+- Rate limit sensitive endpoints
+
+### Error Handling
+```typescript
+export const runtime = 'edge'
+
+export async function GET(request: Request) {
+  try {
+    const data = await riskyOperation()
+    return Response.json(data)
+  } catch (error) {
+    console.error('Edge function error:', error)
+
+    return Response.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    )
+  }
+}
+```
+
+### Debugging
+```typescript
+// Log request details
+console.log('Request URL:', request.url)
+console.log('Headers:', Object.fromEntries(request.headers))
+console.log('Geo:', {
+  country: request.headers.get('x-vercel-ip-country'),
+  city: request.headers.get('x-vercel-ip-city'),
+})
+```

package/README.md

@@ -30,7 +30,7 @@
 
 ```bash
 # 1. Create your project (30 seconds)
-npx create-ai-project my-project
+npx create-claude-webapp my-project
 
 # 2. Install dependencies (automatic)
 cd my-project && npm install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-webapp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "packageManager": "npm@10.8.2",
   "description": "TypeScript boilerplate with skills and sub-agents for Claude Code. Prevents context exhaustion through role-based task splitting.",
   "keywords": [