| name | vercel-cost-optimization |
| description | Use when deploying Next.js apps to Vercel and costs are high, or when setting up a new Vercel project. Covers ISR-breaking patterns, function constraints, caching, Fluid Compute, build optimization. Triggers: "Vercel bill", "Vercel cost", "ISR broken", "dynamic rendering", "cache-control private", "x-vercel-cache MISS", "function invocations", "Fluid Compute", "GB-hours", "s-maxage", "stale-while-revalidate", "maxDuration", "build minutes" |
Vercel Cost Optimization
When to Use
- Vercel bill is higher than expected
- All pages show
cache-control: private, no-cache, no-store
x-vercel-cache: MISS on every request- Setting up a new Next.js + Vercel project
- Reviewing deployment config before going live
- Investigating why ISR/SSG isn't working
Quick Diagnosis
curl -sI https://your-site.com/ | grep -i 'cache-control\|x-vercel-cache'
If every page returns private, no-cache, something is forcing dynamic rendering.
ISR-Breaking Patterns (Most Expensive)
Pattern 1: cookies() or headers() in Shared Code
Calling cookies() or headers() from next/headers anywhere in the rendering tree forces the entire page to be dynamic. This includes root layouts, shared components, and i18n config.
export default async function RootLayout({ children }) {
const locale = await getLocale();
return <html lang={locale}>{children}</html>;
}
export default getRequestConfig(async () => {
const cookieStore = await cookies();
const locale = cookieStore.get("NEXT_LOCALE")?.value || "en";
return { locale, messages: ... };
});
Fix: Use the [locale] route segment with next-intl/middleware's createMiddleware, which passes locale via request context (ISR-compatible) instead of reading cookies at render time.
import createMiddleware from "next-intl/middleware";
import { routing } from "@/i18n/routing";
export default createMiddleware(routing);
export default getRequestConfig(async ({ requestLocale }) => {
const locale = (await requestLocale) || "en";
return { locale, messages: ... };
});
export function generateStaticParams() {
return routing.locales.map((locale) => ({ locale }));
}
export default async function Layout({ params }) {
const { locale } = await params;
setRequestLocale(locale);
}
Important: createMiddleware requires pages under a [locale] folder. Without it, the middleware rewrites to paths that don't exist → 404 on all pages.
Pattern 2: Custom Middleware with NextResponse.rewrite()
export async function middleware(request) {
const locale = request.cookies.get("NEXT_LOCALE")?.value;
const url = new URL(request.url);
url.pathname = `/${locale}${url.pathname}`;
return NextResponse.rewrite(url);
}
export async function middleware(request) {
if (request.nextUrl.pathname.startsWith("/old-path")) {
return NextResponse.redirect(new URL("/new-path", request.url), 308);
}
return NextResponse.next();
}
Pattern 3: Missing setRequestLocale() in Layouts
Even with [locale] routing, forgetting setRequestLocale() keeps pages dynamic:
export default async function Layout({ params }) {
const { locale } = await params;
const messages = await getMessages();
return <>{children}</>;
}
export default async function Layout({ params }) {
const { locale } = await params;
setRequestLocale(locale);
const messages = await getMessages();
return <>{children}</>;
}
Function Constraints (Free Insurance)
vercel.json Configuration
Always set memory and duration caps to prevent runaway costs:
{
"functions": {
"src/app/api/heavy-route/route.ts": {
"memory": 512,
"maxDuration": 60
},
"src/app/api/light-route/route.ts": {
"memory": 128,
"maxDuration": 10
}
}
}
Route-Level maxDuration Exports
Belt-and-suspenders approach — add to every API route file:
export const maxDuration = 10;
export const maxDuration = 15;
export const maxDuration = 60;
Memory Guidelines
| Route Type | Memory | Examples |
|---|
| Stubs / simple JSON | 128 MB | Health check, feature flags, disabled endpoints |
| DB reads / external API | 256 MB | List pages, detail pages, search |
| Heavy processing | 512 MB | Cron jobs, batch operations, email sending |
| Never use | 1024 MB | Default if unset — wasteful for most routes |
Cache-Control Headers on API Routes
return NextResponse.json(data, {
headers: {
"Cache-Control": "public, s-maxage=3600, stale-while-revalidate=600",
},
});
return NextResponse.json(data, {
headers: {
"Cache-Control": "public, s-maxage=86400, stale-while-revalidate=3600",
},
});
Fluid Compute
Disable unless you specifically need it. Fluid Compute adds two line items:
- Fluid Active CPU
- Fluid Provisioned Memory
For typical Next.js sites with ISR pages and short API calls, Fluid Compute adds $50-80/month with no benefit. It's designed for sustained workloads (streaming, long-running connections).
Where to disable: Vercel Dashboard → Project Settings → Functions → Fluid Compute toggle.
Build Optimization
Skip Non-Source Builds
{
"git": {
"ignoredBuildStep": "git diff --quiet HEAD^ -- src/ prisma/ package.json vercel.json next.config.ts"
}
}
This skips builds when only docs, scripts, or config files change — saves build minutes.
Skip Static Generation During Build
{
"env": {
"SKIP_BUILD_STATIC_GENERATION": "true"
}
}
Use fallback: 'blocking' or ISR to generate pages on-demand instead of at build time.
Cost Impact Reference
| Issue | Monthly Cost Impact | Fix Difficulty |
|---|
cookies()/headers() in root layout | +$80-100 | Medium (requires [locale] refactor) |
| Fluid Compute enabled unnecessarily | +$50-80 | Easy (dashboard toggle) |
No ignoredBuildStep | +$15-30 | Easy (vercel.json) |
| No function memory/duration caps | +$10-20 | Easy (vercel.json + exports) |
| No Cache-Control on API routes | +$5-15 | Easy (response headers) |
| Default 1024MB function memory | +$5-10 | Easy (vercel.json) |
Anti-Patterns
| Anti-Pattern | Why It's Bad | Fix |
|---|
Reading cookies() in root layout | All pages become dynamic | Use [locale] segment + createMiddleware |
NextResponse.rewrite() in middleware | Breaks ISR for rewritten paths | Use NextResponse.next() or library middleware |
Using createMiddleware without [locale] folder | 404 on all pages | Add [locale] route segment first |
Removing cookies() without alternative locale detection | Breaks language switching | Need full i18n architecture change, not just deletion |
No maxDuration on API routes | Stuck queries run for 60s at 1024MB | Add export const maxDuration to every route |
| Fluid Compute for simple sites | $50-80/mo for no benefit | Disable in dashboard |
Verification Checklist
After deploying optimizations:
curl -sI https://site.com/ | grep -i cache-control
curl -sI https://site.com/ | grep -i x-vercel-cache
curl -sI https://site.com/api/your-route | grep -i cache-control
for path in / /papers /topics /authors; do
echo "$path: $(curl -s -o /dev/null -w '%{http_code}' https://site.com$path)"
done
curl -sI --cookie "NEXT_LOCALE=zh" https://site.com/ | grep -i 'content-language\|set-cookie'
See Also
fail-fast-ml-engineering — General engineering disciplineagents-md-writing — Documenting deployment patterns in CLAUDE.md
