Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/vercel-pack/skills/vercel-known-pitfalls/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill vercel-known-pitfalls. Copyright stays with the author (MIT).

Vercel Known Pitfalls

Overview

Catalog of the most common Vercel anti-patterns with severity ratings, detection methods, and fixes. Organized by category: secret exposure, serverless function mistakes, edge runtime violations, configuration errors, and cost traps.

Prerequisites

• Access to Vercel codebase for review
• Understanding of Vercel's deployment model
• Familiarity with vercel-common-errors for error codes

Instructions

Category 1: Secret Exposure (Critical)

P1: Secrets in NEXT_PUBLIC_ variables

// BAD — exposed in client JavaScript bundle, visible to anyone
const apiKey = process.env.NEXT_PUBLIC_API_SECRET;
// This value is inlined at build time into the browser bundle

// GOOD — server-only access
const apiKey = process.env.API_SECRET;
// Only accessible in serverless functions and server components

• Detection: grep -r 'NEXT_PUBLIC_.*SECRET\|NEXT_PUBLIC_.*KEY\|NEXT_PUBLIC_.*TOKEN' src/
• Fix: Remove NEXT_PUBLIC_ prefix, rotate the exposed secret immediately

P2: Hardcoded credentials in source

// BAD
const client = new Client({ apiKey: 'sk_live_abc123' });

// GOOD
const client = new Client({ apiKey: process.env.API_KEY });

• Detection: grep -rE 'sk_live|sk_test|Bearer [a-zA-Z0-9]{20,}' src/ api/
• Fix: Move to environment variables, add pre-commit hook

P3: Secrets in vercel.json

// BAD — vercel.json is committed to git
{
  "env": { "API_KEY": "sk_live_abc123" }
}

// GOOD — use Vercel dashboard or CLI
// vercel env add API_KEY production

Category 2: Serverless Function Mistakes (High)

P4: Heavy initialization at module level

// BAD — runs on every cold start, adds 500ms+
import { PrismaClient } from '@prisma/client';
const prisma = new PrismaClient(); // Connects on import
const cache = await loadLargeDataset(); // Blocks cold start

// GOOD — lazy initialization
let prisma: PrismaClient | null = null;
function getDb() {
  if (!prisma) prisma = new PrismaClient();
  return prisma;
}

export default async function handler(req, res) {
  const db = getDb(); // Only connects on first request
  // ...
}

P5: Not returning responses from all code paths

// BAD — some paths don't return, causing NO_RESPONSE_FROM_FUNCTION
export default function handler(req, res) {
  if (req.method === 'GET') {
    res.json({ data: 'ok' });
  }
  // POST, PUT, DELETE — no response returned!
}

// GOOD
export default function handler(req, res) {
  if (req.method === 'GET') {
    return res.json({ data: 'ok' });
  }
  return res.status(405).json({ error: 'Method not allowed' });
}

P6: Ignoring function timeout limits

// BAD — no timeout awareness, function silently killed
export default async function handler(req, res) {
  const results = await processMillionRecords(); // Takes 5 minutes
  res.json(results);
}

// GOOD — chunk work, respect timeout
export default async function handler(req, res) {
  const batch = req.query.batch ?? 0;
  const results = await processBatch(batch, 100); // Process 100 at a time
  res.json({
    results,
    nextBatch: batch + 1,
    done: results.length < 100,
  });
}

P7: Connection pool exhaustion

// BAD — each function instance creates its own connection pool
// With 100 concurrent functions × 10 pool connections = 1000 DB connections
const pool = new Pool({ max: 10 });

// GOOD — use a connection pooler
// Use Prisma Accelerate, PgBouncer, or Supabase connection pooler
// Configure pool size to 1-2 per function instance
const pool = new Pool({ max: 2 });

Category 3: Edge Runtime Violations (High)

P8: Node.js APIs in edge functions

// BAD — these crash silently in Edge Runtime
export const config = { runtime: 'edge' };

import fs from 'fs';           // Not available
import path from 'path';       // Not available
import crypto from 'crypto';   // Use crypto.subtle instead
import { Buffer } from 'buffer'; // Use Uint8Array instead

// GOOD — Web Standard APIs
const hash = await crypto.subtle.digest('SHA-256', data);
const encoded = btoa(String.fromCharCode(...new Uint8Array(hash)));

• Detection: grep -rn "from 'fs'\|from 'path'\|from 'crypto'\|from 'child_process'" --include="*edge*" --include="*middleware*"

P9: Dynamic code evaluation in edge

// BAD — throws "Dynamic Code Evaluation not allowed"
export const config = { runtime: 'edge' };
const fn = new Function('return 42'); // Not allowed
eval('console.log("hi")');            // Not allowed

// GOOD — use static code only
const fn = () => 42;

Category 4: Configuration Errors (Medium)

P10: Missing environment variable scoping

# BAD — variable only in Production, preview deployments break
vercel env add DATABASE_URL production

# GOOD — add to all environments that need it
vercel env add DATABASE_URL production preview development

P11: Using deprecated builds property

// BAD (deprecated)
{
  "builds": [
    { "src": "api/**/*.ts", "use": "@vercel/node" }
  ]
}

// GOOD (current)
{
  "functions": {
    "api/**/*.ts": {
      "runtime": "nodejs20.x",
      "maxDuration": 30
    }
  }
}

P12: Middleware running on static assets

// BAD — middleware runs on every request including static files
export function middleware(request) { /* auth check */ }

// GOOD — exclude static assets
export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

Category 5: Cost Traps (Medium)

P13: Uncached high-traffic endpoints

// BAD — every request invokes a function
export default function handler(req, res) {
  res.json({ config: getConfig() }); // No cache headers
}

// GOOD — cache at the edge, save function invocations
export default function handler(req, res) {
  res.setHeader('Cache-Control', 's-maxage=3600, stale-while-revalidate=86400');
  res.json({ config: getConfig() });
}

P14: Over-allocated function memory

// BAD — 3GB for a simple JSON response
{
  "functions": { "api/config.ts": { "memory": 3008 } }
}

// GOOD — right-size per endpoint
{
  "functions": {
    "api/config.ts": { "memory": 128 },
    "api/image-process.ts": { "memory": 1024 }
  }
}

P15: Middleware doing heavy work

// BAD — database query on every request
export async function middleware(request) {
  const user = await db.user.findUnique({ where: { id: token.sub } });
  // Runs on EVERY matched request, expensive at scale
}

// GOOD — validate JWT locally, no DB call
export function middleware(request) {
  const token = request.cookies.get('session')?.value;
  // Verify JWT signature locally (cheap, no external call)
}

Quick Audit Script

#!/usr/bin/env bash
echo "=== Vercel Pitfall Audit ==="

echo "P1: Secrets in NEXT_PUBLIC_:"
grep -rn 'NEXT_PUBLIC_.*SECRET\|NEXT_PUBLIC_.*KEY\|NEXT_PUBLIC_.*TOKEN' src/ api/ 2>/dev/null || echo "  PASS"

echo "P2: Hardcoded credentials:"
grep -rnE 'sk_live|sk_test|Bearer [a-zA-Z0-9]{20,}' src/ api/ 2>/dev/null || echo "  PASS"

echo "P8: Node.js APIs in edge files:"
grep -rn "from 'fs'\|from 'path'\|from 'child_process'" src/middleware.ts api/*edge* 2>/dev/null || echo "  PASS"

echo "P11: Deprecated builds:"
jq -e '.builds' vercel.json 2>/dev/null && echo "  FAIL: deprecated builds" || echo "  PASS"

echo "P12: Middleware without matcher:"
grep -L 'matcher' src/middleware.ts 2>/dev/null && echo "  WARN: no matcher configured" || echo "  PASS"

Output

• Anti-patterns identified and classified by severity (Critical/High/Medium)
• Security issues fixed and exposed secrets rotated
• Performance improvements from lazy initialization and caching
• ESLint and CI prevention measures blocking future regressions

Error Handling

Examples

Fix an exposed client-side secret without preserving it

When a scan finds a NEXT_PUBLIC_ value that should be private, immediately stop treating the string as a valid secret, rotate it at the upstream provider, and remove the value from code and build settings. Replace the browser call with a server-side route that enforces authorization and returns only required data. Validate the fix in preview with synthetic traffic, check that the old credential is refused, and record the rotation outcome without placing either value in logs or documentation.

Resources

• Vercel Best Practices
• Edge Runtime Limitations
• Function Configuration
• Vercel Security
• Vercel Limits

Next Steps

Return to vercel-install-auth for setup or vercel-reference-architecture for project structure.