@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

package/skills/vercel-cost-tuning/SKILL.md

@@ -1,201 +1,214 @@
 ---
 name: vercel-cost-tuning
-description: |
-  Optimize Vercel costs through tier selection, sampling, and usage monitoring.
-  Use when analyzing Vercel billing, reducing API costs,
-  or implementing usage monitoring and budget alerts.
+description: 'Optimize Vercel costs through plan selection, function efficiency, and
+  usage monitoring.
+
+  Use when analyzing Vercel billing, reducing function execution costs,
+
+  or implementing spend management and budget alerts.
+
   Trigger with phrases like "vercel cost", "vercel billing",
+
   "reduce vercel costs", "vercel pricing", "vercel expensive", "vercel budget".
-allowed-tools: Read, Grep
+
+  '
+allowed-tools: Read, Write, Edit, Bash(vercel:*), Bash(curl:*), Grep
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- cost-optimization
+- billing
+- monitoring
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel Cost Tuning
 
 ## Overview
-Optimize Vercel costs through smart tier selection, sampling, and usage monitoring.
+
+Optimize Vercel costs by understanding the Fluid Compute pricing model, reducing function execution time, leveraging edge caching to avoid function invocations, and configuring spend management. Covers plan comparison, cost drivers, and monitoring.
 
 ## Prerequisites
+
 - Access to Vercel billing dashboard
-- Understanding of current usage patterns
-- Database for usage tracking (optional)
-- Alerting system configured (optional)
+- Understanding of current deployment architecture
+- Access to Vercel Analytics for usage patterns
 
-## Pricing Tiers
+## Instructions
 
-| Tier | Monthly Cost | Included | Overage |
-|------|-------------|----------|---------|
-| Hobby | $0 | 100GB bandwidth, 100GB-hrs functions | N/A |
-| Pro | $20 | 1TB bandwidth, 1000GB-hrs functions | $0.001/request |
-| Enterprise | Custom | Unlimited | Volume discounts |
+### Step 1: Understand the Pricing Model
 
-## Cost Estimation
+Vercel uses **Fluid Compute** pricing (for new projects):
 
-```typescript
-interface UsageEstimate {
-  requestsPerMonth: number;
-  tier: string;
-  estimatedCost: number;
-  recommendation?: string;
-}
+| Resource | Hobby (Free) | Pro ($20/member/mo) | Enterprise |
+|----------|-------------|---------------------|------------|
+| Bandwidth | 100 GB | 1 TB included | Custom |
+| Serverless Execution | 100 GB-hrs | 1000 GB-hrs included | Custom |
+| Edge Function invocations | 500K | 1M included | Custom |
+| Edge Middleware invocations | 1M | 1M included | Custom |
+| Image Optimizations | 1000 | 5000 included | Custom |
+| Builds per day | 6000 | 6000 | Custom |
+| Concurrent builds | 1 | 1 (more available) | Custom |
 
-function estimateVercelCost(requestsPerMonth: number): UsageEstimate {
-  if (requestsPerMonth <= 1000) {
-    return { requestsPerMonth, tier: 'Free', estimatedCost: 0 };
-  }
+**Fluid Compute billing breakdown:**
 
-  if (requestsPerMonth <= 100000) {
-    return { requestsPerMonth, tier: 'Pro', estimatedCost: 20 };
-  }
+- **Active CPU time**: charged per ms of actual CPU usage
+- **Provisioned memory**: charged per GB-second of allocated memory
+- Benefit: you pay for actual work, not idle waiting (e.g., waiting for a database response)
 
-  const proOverage = (requestsPerMonth - 100000) * 0.001;
-  const proCost = 20 + proOverage;
-
-  return {
-    requestsPerMonth,
-    tier: 'Pro (with overage)',
-    estimatedCost: proCost,
-    recommendation: proCost > 500
-      ? 'Consider Enterprise tier for volume discounts'
-      : undefined,
-  };
-}
+### Step 2: Identify Cost Drivers
+
+```bash
+# Check usage via API
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v2/usage" | jq .
+
+# Top cost drivers on Vercel:
+# 1. Serverless function execution time (CPU + memory)
+# 2. Bandwidth (large responses, unoptimized images)
+# 3. Edge Middleware invocations (runs on EVERY request)
+# 4. Image optimizations (each unique transform costs)
+# 5. Build minutes (frequent deploys or slow builds)
 ```
 
-## Usage Monitoring
+### Step 3: Reduce Function Execution Costs
 
 ```typescript
-class VercelUsageMonitor {
-  private requestCount = 0;
-  private bytesTransferred = 0;
-  private alertThreshold: number;
-
-  constructor(monthlyBudget: number) {
-    this.alertThreshold = monthlyBudget * 0.8; // 80% warning
-  }
-
-  track(request: { bytes: number }) {
-    this.requestCount++;
-    this.bytesTransferred += request.bytes;
-
-    if (this.estimatedCost() > this.alertThreshold) {
-      this.sendAlert('Approaching Vercel budget limit');
-    }
-  }
-
-  estimatedCost(): number {
-    return estimateVercelCost(this.requestCount).estimatedCost;
-  }
-
-  private sendAlert(message: string) {
-    // Send to Slack, email, PagerDuty, etc.
+// 1. Right-size function memory — don't over-allocate
+// vercel.json
+{
+  "functions": {
+    "api/lightweight.ts": { "memory": 128 },    // Simple JSON responses
+    "api/standard.ts": { "memory": 512 },       // Database queries
+    "api/heavy.ts": { "memory": 1024 }          // Image processing
   }
 }
-```
 
-## Cost Reduction Strategies
+// 2. Move read-only endpoints to Edge Functions (cheaper, no cold starts)
+// api/config.ts
+export const config = { runtime: 'edge' };
+export default function handler() {
+  return Response.json({ features: ['a', 'b'] });
+}
 
-### Step 1: Request Sampling
-```typescript
-function shouldSample(samplingRate = 0.1): boolean {
-  return Math.random() < samplingRate;
+// 3. Cache function responses at the edge
+// Eliminates function invocations entirely for cached routes
+export default function handler(req, res) {
+  res.setHeader('Cache-Control', 's-maxage=3600, stale-while-revalidate=86400');
+  res.json(data);
 }
+```
 
-// Use for non-critical telemetry
-if (shouldSample(0.1)) { // 10% sample
-  await vercelClient.trackEvent(event);
+### Step 4: Reduce Bandwidth Costs
+
+```json
+// vercel.json — compress and cache aggressively
+{
+  "headers": [
+    {
+      "source": "/static/(.*)",
+      "headers": [
+        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
+      ]
+    }
+  ],
+  "images": {
+    "sizes": [640, 750, 1080],
+    "formats": ["image/avif", "image/webp"],
+    "minimumCacheTTL": 86400
+  }
 }
 ```
 
-### Step 2: Batching Requests
-```typescript
-// Instead of N individual calls
-await Promise.all(ids.map(id => vercelClient.get(id)));
+Key bandwidth reducers:
 
-// Use batch endpoint (1 call)
-await vercelClient.batchGet(ids);
-```
+- Use Vercel's image optimization (auto WebP/AVIF conversion)
+- Set aggressive cache headers on static assets
+- Use ISR to serve static HTML instead of SSR
+- Compress API responses (Vercel auto-compresses with Brotli)
 
-### Step 3: Caching (from P16)
-- Cache frequently accessed data
-- Use cache invalidation webhooks
-- Set appropriate TTLs
+### Step 5: Optimize Middleware Costs
+
+Middleware runs on **every matched request**. Minimize its scope:
 
-### Step 4: Compression
 ```typescript
-const client = new VercelClient({
-  compression: true, // Enable gzip
-});
+// middleware.ts — scope to specific paths only
+export const config = {
+  matcher: [
+    // Only run middleware on API routes and protected pages
+    '/api/:path*',
+    '/dashboard/:path*',
+    // Skip static files, images, and public assets
+    '/((?!_next/static|_next/image|favicon.ico|public).*)',
+  ],
+};
+
+export function middleware(request) {
+  // Keep logic minimal — this runs on every matched request
+  // Avoid: database queries, external API calls, heavy computation
+  // Good: cookie checks, header modifications, redirects
+}
 ```
 
-## Budget Alerts
+### Step 6: Configure Spend Management
 
-```bash
-# Set up billing alerts in Vercel dashboard
-# Or use API if available:
-# Check Vercel documentation for billing APIs
-```
+In the Vercel dashboard under **Settings > Billing > Spend Management**:
 
-## Cost Dashboard Query
-
-```sql
--- If tracking usage in your database
-SELECT
-  DATE_TRUNC('day', created_at) as date,
-  COUNT(*) as requests,
-  SUM(response_bytes) as bytes,
-  COUNT(*) * 0.001 as estimated_cost
-FROM vercel_api_logs
-WHERE created_at >= NOW() - INTERVAL '30 days'
-GROUP BY 1
-ORDER BY 1;
+```
+Default budget: $200/month on-demand usage
+Options:
+- Set custom budget limit
+- Enable hard limit (pauses all projects when reached)
+- Configure email alerts at 50%, 75%, 90%, 100%
 ```
 
-## Instructions
-
-### Step 1: Analyze Current Usage
-Review Vercel dashboard for usage patterns and costs.
-
-### Step 2: Select Optimal Tier
-Use the cost estimation function to find the right tier.
+```bash
+# Check current usage against budget via API
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v2/usage?teamId=team_xxx" \
+  | jq '{period: .period, bandwidth: .bandwidth, execution: .serverlessFunctionExecution}'
+```
 
-### Step 3: Implement Monitoring
-Add usage tracking to catch budget overruns early.
+## Cost Optimization Checklist
 
-### Step 4: Apply Optimizations
-Enable batching, caching, and sampling where appropriate.
+| Action | Impact | Effort |
+|--------|--------|--------|
+| Add `s-maxage` cache headers | High — eliminates function invocations | Low |
+| Use Edge Functions for simple endpoints | Medium — cheaper than serverless | Low |
+| Right-size function memory | Medium — reduces GB-hr cost | Low |
+| Scope middleware matcher | Medium — reduces edge invocations | Low |
+| Enable image optimization | Medium — reduces bandwidth | Low |
+| Use ISR instead of SSR | High — serves cached HTML | Medium |
+| Optimize build speed | Low — reduces build minutes | Medium |
+| Set spend management alerts | Safety — prevents surprise bills | Low |
 
 ## Output
-- Optimized tier selection
-- Usage monitoring implemented
-- Budget alerts configured
-- Cost reduction strategies applied
 
-## Error Handling
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| Unexpected charges | Untracked usage | Implement monitoring |
-| Overage fees | Wrong tier | Upgrade tier |
-| Budget exceeded | No alerts | Set up alerts |
-| Inefficient usage | No batching | Enable batch requests |
+- Function memory right-sized per endpoint
+- Edge caching reducing function invocations
+- Middleware scoped to minimize invocations
+- Spend management configured with budget alerts
+- Usage monitoring via API
 
-## Examples
+## Error Handling
 
-### Quick Cost Check
-```typescript
-// Estimate monthly cost for your usage
-const estimate = estimateVercelCost(yourMonthlyRequests);
-console.log(`Tier: ${estimate.tier}, Cost: $${estimate.estimatedCost}`);
-if (estimate.recommendation) {
-  console.log(`💡 ${estimate.recommendation}`);
-}
-```
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Unexpected bill spike | Uncached high-traffic endpoint | Add `s-maxage` to the response |
+| Projects paused | Hard spending limit reached | Increase limit or optimize usage |
+| Image optimization quota exceeded | Too many unique image transforms | Reduce `sizes` array, increase cache TTL |
+| Build minutes exceeded | Slow builds or too many deploys | Use `ignoreCommand` to skip non-code changes |
 
 ## Resources
+
 - [Vercel Pricing](https://vercel.com/pricing)
-- [Vercel Billing Dashboard](https://dashboard.vercel.com/billing)
+- [Fluid Compute Pricing](https://vercel.com/docs/functions/usage-and-pricing)
+- [Spend Management](https://vercel.com/docs/pricing#spend-management)
+- [Limits](https://vercel.com/docs/limits)
+- [Usage API](https://vercel.com/docs/rest-api)
 
 ## Next Steps
-For architecture patterns, see `vercel-reference-architecture`.
+
+For reference architecture, see `vercel-reference-architecture`.

package/skills/vercel-cost-tuning/references/cost-estimation.md

@@ -0,0 +1,34 @@
+# Cost Estimation
+
+## Cost Estimation
+
+```typescript
+interface UsageEstimate {
+  requestsPerMonth: number;
+  tier: string;
+  estimatedCost: number;
+  recommendation?: string;
+}
+
+function estimateVercelCost(requestsPerMonth: number): UsageEstimate {
+  if (requestsPerMonth <= 1000) {
+    return { requestsPerMonth, tier: 'Free', estimatedCost: 0 };
+  }
+
+  if (requestsPerMonth <= 100000) {
+    return { requestsPerMonth, tier: 'Pro', estimatedCost: 20 };
+  }
+
+  const proOverage = (requestsPerMonth - 100000) * 0.001;
+  const proCost = 20 + proOverage;
+
+  return {
+    requestsPerMonth,
+    tier: 'Pro (with overage)',
+    estimatedCost: proCost,
+    recommendation: proCost > 500
+      ? 'Consider Enterprise tier for volume discounts'
+      : undefined,
+  };
+}
+```

package/skills/vercel-cost-tuning/references/cost-reduction-strategies.md

@@ -0,0 +1,40 @@
+# Cost Reduction Strategies
+
+## Cost Reduction Strategies
+
+### Step 1: Request Sampling
+
+```typescript
+function shouldSample(samplingRate = 0.1): boolean {
+  return Math.random() < samplingRate;
+}
+
+// Use for non-critical telemetry
+if (shouldSample(0.1)) { // 10% sample
+  await vercelClient.trackEvent(event);
+}
+```
+
+### Step 2: Batching Requests
+
+```typescript
+// Instead of N individual calls
+await Promise.all(ids.map(id => vercelClient.get(id)));
+
+// Use batch endpoint (1 call)
+await vercelClient.batchGet(ids);
+```
+
+### Step 3: Caching (from P16)
+
+- Cache frequently accessed data
+- Use cache invalidation webhooks
+- Set appropriate TTLs
+
+### Step 4: Compression
+
+```typescript
+const client = new VercelClient({
+  compression: true, // Enable gzip
+});
+```

package/skills/vercel-cost-tuning/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Unexpected charges | Untracked usage | Implement monitoring |
+| Overage fees | Wrong tier | Upgrade tier |
+| Budget exceeded | No alerts | Set up alerts |
+| Inefficient usage | No batching | Enable batch requests |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-cost-tuning/references/examples.md

@@ -0,0 +1,15 @@
+## Examples
+
+### Quick Cost Check
+
+```typescript
+// Estimate monthly cost for your usage
+const estimate = estimateVercelCost(yourMonthlyRequests);
+console.log(`Tier: ${estimate.tier}, Cost: $${estimate.estimatedCost}`);
+if (estimate.recommendation) {
+  console.log(`💡 ${estimate.recommendation}`);
+}
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*