DEV Community: Ahmed Mahmoud

Database Connections in Serverless: Field Notes on Pool Math, PgBouncer Transaction Mode, and the Singleton HMR Kept Recreating

Ahmed Mahmoud — Fri, 28 Aug 2026 06:00:12 +0000

Headline: A database connection pool in a serverless deployment is per-instance, not per-application. The real ceiling is concurrent instances multiplied by pool size, which is why the fix is almost never a bigger database — it is a connection pooler in transaction mode plus a driver configured to survive one.

I hit FATAL: sorry, too many clients already on a Next.js app whose traffic would not have troubled a single Postgres box in 2005. The database was idle. The application code was fine. What was not fine was my mental model: I had configured one pool with a sensible max and assumed that number described the deployment. It described one function instance.

Key takeaways

A connection pool is a cache of open TCP connections living inside one Node.js process. Total connections opened by a serverless app are roughly concurrent instances multiplied by each pool's max, not the max you configured.
PostgreSQL ships with max_connections = 100 by default and reserves three for superusers, and every connection is a separate backend process with its own memory.
PgBouncer in transaction mode multiplexes many clients onto few server connections, but it discards session state: prepared statements, LISTEN/NOTIFY, session-level SET, and advisory locks held between transactions all break.
Drizzle with postgres.js needs prepare: false behind a transaction-mode pooler; Prisma needs ?pgbouncer=true plus a separate directUrl for migrations.
Vercel Fluid Compute reuses one instance across concurrent requests, so max: 1 now serializes handlers instead of protecting the database.

Why does my serverless app run out of Postgres connections?

Because each function instance runs its own Node.js process holding its own pool, so the connections you actually open are concurrent instances multiplied by each pool's max. Nothing about a pool is shared between processes. Ten instances configured with max: 10 is one hundred connections, not ten.

That product collides with a hard server-side limit. PostgreSQL defaults to max_connections = 100, holds three back for superuser access, and spawns a separate backend process per connection. The failure is load-shaped: a traffic spike opens more instances, each opens its own pool, and Postgres answers with FATAL: sorry, too many clients already while database CPU stays flat.

What did Fluid Compute change about connection pooling?

Fluid Compute reuses a single function instance across concurrent requests, so one module-scope pool is shared by several in-flight requests inside the same process. The classic advice — set max: 1, because an instance only ever handles one request — is actively harmful under that model: a pool of one serializes concurrent handlers behind a single connection.

// lib/db.ts
import { Pool } from 'pg';

// Module scope: created once per instance, reused by every request
// that instance serves, including concurrent ones under Fluid Compute.
export const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 5,                      // per instance, not per deployment
  idleTimeoutMillis: 10_000,   // hand connections back to the pooler
  connectionTimeoutMillis: 5_000,
});

Which PgBouncer pooling mode should I use?

Transaction mode, for ordinary application traffic. PgBouncer is a lightweight proxy that multiplexes many client connections onto a small set of real server connections, and pool_mode decides how long a client keeps one of them.

Mode	Server connection held for	What it breaks	Use it for
`session`	The whole client session	Nothing	Migrations, `LISTEN/NOTIFY`, long-lived workers
`transaction`	One transaction	Prepared statements, session `SET`, advisory locks outside a transaction, `WITH HOLD` cursors	Serverless application traffic
`statement`	One statement	Everything above, plus multi-statement transactions	Rare; sharded setups without transactions

Supabase now fronts Postgres with Supavisor rather than PgBouncer, and Neon and Amazon RDS Proxy ship their own implementations, but the mode semantics are identical everywhere.

Why did my prepared statements break behind the pooler?

Because a protocol-level prepared statement is session state on one server connection, and transaction mode may hand you a different connection for the next transaction. The symptom is a pair of errors alternating under load: prepared statement "s1" already exists and prepared statement "s1" does not exist.

PgBouncer 1.21 and later can track prepared statements in transaction mode when max_prepared_statements is above zero — confirm your provider enables it before depending on it. Otherwise disable them in the driver. node-postgres only uses named prepared statements when you explicitly name a query; postgres.js prepares by default and needs prepare: false; Prisma needs ?pgbouncer=true.

// postgres.js + Drizzle behind a transaction-mode pooler
import postgres from 'postgres';
import { drizzle } from 'drizzle-orm/postgres-js';

const client = postgres(process.env.DATABASE_URL!, {
  prepare: false, // named statements do not survive transaction mode
  max: 5,
});

export const db = drizzle(client);

How do I stop dev HMR from opening a new pool on every save?

Cache the pool on globalThis in development. Next.js hot module replacement re-evaluates changed modules, so new Pool() at module scope runs again on every save while the previous pool keeps its sockets open. Twenty saves is twenty live pools, and eventually the local database refuses connections.

// lib/db.ts
import { Pool } from 'pg';

const globalForDb = globalThis as unknown as { pool?: Pool };

export const pool =
  globalForDb.pool ??
  new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });

if (process.env.NODE_ENV !== 'production') globalForDb.pool = pool;

Which connection string should migrations use?

The direct, session-mode connection string — never the transaction-mode pooler. Migrations take advisory locks and run DDL that must stay held across statements, and a transaction-mode pooler can route the next statement to a different backend where that lock does not exist.

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")         // pooled, transaction mode
  directUrl = env("DIRECT_DATABASE_URL")  // direct, session mode
}

Drizzle Kit takes the same split by pointing its config at the direct URL while the runtime client uses the pooled one. The rule generalises: LISTEN/NOTIFY, advisory locks used as a distributed mutex, and anything that sets a session variable belongs on the direct connection.

When is an HTTP database driver the better choice?

When your handler runs one self-contained statement and you would rather not manage a TCP pool at all. Neon's @neondatabase/serverless package exposes neon(), which sends a single SQL statement over HTTP — no pool to size, no connection to leak. The cost is that HTTP is stateless: no interactive transactions, no session settings. The same package ships a WebSocket-backed Pool for cases that need real transactions.

My rule is boring: HTTP driver for read handlers running one query, TCP pool through a transaction-mode pooler for multi-statement transactions, direct connection for migrations and workers.

FAQ

Q: How large should max be in a serverless connection pool?
A: Small — start around three to five per instance, then watch the server-side connection count at peak concurrency. The number that matters is instances × max.

Q: Do I still need PgBouncer if I use Prisma?
A: Yes. Prisma's client-side pool is per-instance like any other and does not coordinate across processes. Add ?pgbouncer=true so Prisma stops relying on named prepared statements.

Q: Does transaction-mode pooling break database transactions?
A: No. It pins one server connection for the full duration of a transaction. It breaks state that lives between transactions.

Q: Why does my local database run out of connections when production does not?
A: Almost always HMR creating a new pool on every file save. Cache the pool on globalThis in development.

Q: Can I use LISTEN/NOTIFY from a serverless function?
A: Not through a transaction-mode pooler — the listening session is not preserved. Use a direct session connection on a long-lived process, or a real queue.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Environment Variables in Next.js: Field Notes on NEXT_PUBLIC_ Inlining, the Secret That Almost Shipped, and Failing the Build with Zod

Ahmed Mahmoud — Tue, 25 Aug 2026 06:00:11 +0000

Headline: A NEXT_PUBLIC_ environment variable is not read at runtime — Next.js replaces every process.env.NEXT_PUBLIC_* expression with a string literal at build time. That single fact explains the value that refuses to update without a rebuild, the dynamic lookup that returns undefined in the browser, and why one build artifact cannot serve two environments.

An environment variable in Next.js is one name with two different lives. On the server it lives in process.env, a real Node.js object read at request time. In the browser it does not exist at all: any variable prefixed with NEXT_PUBLIC_ is copied into the JavaScript bundle as a literal during next build, and everything else is stripped. I have watched the same three failures come out of that split on several projects this year — a stale API URL that survived a redeploy, a secret that nearly rode a prop into the HTML, and a missing variable that surfaced as a runtime crash instead of a failed build. These notes are the checklist I now run before the first deploy.

Key takeaways

NEXT_PUBLIC_ variables are inlined into the client bundle at build time. Changing the value in your host's dashboard does nothing until the next build.
Inlining is static text replacement. process.env[name] with a dynamic key and const { NEXT_PUBLIC_X } = process.env both return undefined in the browser.
Server-only variables are stripped from client bundles, so process.env.SECRET in a Client Component is undefined, not a leak. Secrets leak through props serialized into the RSC payload and through renaming a variable to NEXT_PUBLIC_.
The server-only package turns "a Client Component imported my secrets module" into a build error instead of a silent risk.
Validate environment variables with a Zod schema at module load and import that module in next.config.ts, so a missing variable fails next build instead of the first production request.

Why did changing my NEXT_PUBLIC_ variable do nothing?

Because the value the browser sees was compiled into the JavaScript at the last build. During next build, the bundler performs a find-and-replace: every static process.env.NEXT_PUBLIC_API_URL expression becomes the string the variable held on the build machine at that moment. The deployed bundle contains the literal URL, not a lookup. Editing the variable in a dashboard, a Docker -e flag, or .env.production changes what the next build will see — the running one is frozen.

The replacement is textual, which produces a failure mode that looks like a bug in Next.js and is not:

// Replaced at build time with a string literal — works in the browser
const url = process.env.NEXT_PUBLIC_API_URL;

// undefined in the browser: inlining is static text replacement,
// and no process.env object exists at runtime to index into
const name = 'NEXT_PUBLIC_API_URL';
const url2 = process.env[name];

// Also undefined after bundling: destructuring is not a static reference
const { NEXT_PUBLIC_API_URL } = process.env;

Server code has none of these restrictions. Inside a Server Component, a route handler, or a Server Action, process.env is the live Node.js object, read at request time, dynamic keys and all.

How does a server secret actually reach the browser?

Not through process.env — Next.js strips unprefixed variables from client bundles, so process.env.STRIPE_SECRET_KEY in a Client Component evaluates to undefined. The leaks I have actually seen take two other roads. The first is serialization: a Server Component reads a secret and passes it as a prop to a Client Component, and the value is embedded in the RSC payload inside the HTML response, visible in View Source. The second is the "fix" reflex: a developer sees undefined in the browser, renames API_SECRET to NEXT_PUBLIC_API_SECRET, the error disappears, and the secret is now a string literal in a public JavaScript file.

The cheap defence is the server-only package — an empty module whose import fails the build if it ends up in the client graph:

// lib/secrets.ts
import 'server-only';

export const stripeSecret = process.env.STRIPE_SECRET_KEY!;
export const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;

Any module that touches secrets gets that import at the top. If a Client Component ever imports it, directly or through a chain, the build fails with a readable error instead of shipping. React's experimental taint API (experimental_taintUniqueValue) covers the prop-serialization road as well, but server-only is stable today and catches the common case.

How do I fail the build when a variable is missing?

Parse the environment through a Zod schema in a module that runs during the build, and import every variable through it. A missing or malformed variable then stops next build with a named error instead of surfacing as undefined in whatever code happened to read it first.

// src/env.ts
import { z } from 'zod';

const schema = z.object({
  DATABASE_URL: z.string().url(),
  STRIPE_SECRET_KEY: z.string().min(1),
  NEXT_PUBLIC_API_URL: z.string().url(),
});

export const env = schema.parse({
  DATABASE_URL: process.env.DATABASE_URL,
  STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
  // Client vars must be referenced literally so the bundler can inline them
  NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
});

Two details earn their place. The keys are listed explicitly instead of passing process.env wholesale, because client-referenced variables must appear as literal member expressions for the bundler to inline them. And importing this module from next.config.ts (import './src/env';) forces the schema to execute at build time even if no route touches it. The @t3-oss/env-nextjs package wraps the same idea with a server/client split.

Which .env file wins, and which ones do I commit?

Next.js loads .env files itself — no dotenv package needed — with a fixed precedence: an already-set shell variable beats every file, and more specific files beat general ones.

File	Loaded when	Commit it?
`.env`	Every environment	Yes — shared defaults
`.env.local`	Every environment except `NODE_ENV=test`	No — machine secrets
`.env.development` / `.env.production`	When `NODE_ENV` matches	Yes — per-env defaults
`.env.development.local` / `.env.production.local`	When `NODE_ENV` matches; beats other files	No

NODE_ENV itself is not free-form: Next.js recognises exactly development, production, and test. next dev forces the first; next build and next start force the second. A staging environment is therefore NODE_ENV=production plus your own variable such as APP_ENV=staging. One more sharp edge: .env.local is deliberately ignored when NODE_ENV=test, so test runs stay reproducible across machines.

Can one build artifact serve both staging and production?

For server-side variables, yes — they are read at request time, so the same Docker image can boot with different DATABASE_URL values. For NEXT_PUBLIC_ variables, no — their values are already inside the JavaScript. On Vercel this stays invisible because every environment gets its own build with its own variables. A output: 'standalone' Docker deployment that promotes the same image across environments exposes it immediately.

Three honest ways out, in the order I try them: keep configuration server-side and let client code call same-origin paths (a rewrite that proxies /api removes most reasons a browser needs an absolute URL); read the value in a Server Component at request time and pass it down as a prop; or accept one build per environment. What does not work is editing the variable and redeploying the same artifact — and it fails silently, because the old value keeps being served with no error anywhere.

FAQ

Q: Are my server-only variables exposed to the browser?

A: No. Next.js strips variables without the NEXT_PUBLIC_ prefix from client bundles, so reading one in a Client Component returns undefined. Exposure happens when a secret is passed as a prop into a Client Component or renamed to a NEXT_PUBLIC_ variable.

Q: Do I need the dotenv package in a Next.js project?

A: No. Next.js loads .env, .env.local, and the NODE_ENV-specific variants itself, in a documented order. Adding dotenv on top usually just creates a second, conflicting load order.

Q: Can I set NODE_ENV to staging?

A: No. Next.js recognises only development, production, and test, and the CLI commands set it for you. Model staging as NODE_ENV=production plus your own variable, for example APP_ENV=staging.

Q: Why is process.env[name] undefined in the browser?

A: Because inlining is a static build-time replacement of literal process.env.NEXT_PUBLIC_* expressions. There is no process.env object in the browser to index with a dynamic key, so only the literal form works.

Q: How do I get type-safe environment variables in TypeScript?

A: Export a Zod-validated env object from one module and import it everywhere instead of touching process.env directly. Augmenting the ProcessEnv type gives autocomplete but no runtime guarantee; the schema gives both.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Webhooks in the Next.js App Router: Field Notes on Raw Bodies, Signature Verification, and Returning 200 Before the Work

Ahmed Mahmoud — Mon, 24 Aug 2026 06:00:08 +0000

Headline: A webhook signature is an HMAC computed over the raw request bytes, so a handler that parses the body before verifying has already destroyed the evidence. In the Next.js App Router, await req.text() inside a route handler returns those raw bytes — verify first, acknowledge fast, and do the real work idempotently after the response.

A webhook is an HTTP POST a provider sends to my server when something happens on their side — a payment settles, a repository receives a push, a subscription cancels. I have wired webhooks into several Next.js App Router apps this year, and every one of them broke in the same three places first: verifying a signature against a body I had already parsed, doing too much work before responding, and processing the same event twice. These notes are the checklist I now start from.

Key takeaways

Webhook signatures — Stripe's Stripe-Signature, GitHub's X-Hub-Signature-256 — are HMACs over the raw request bytes. Verify against await req.text(), never a re-serialized JSON.parse result.
App Router route handlers do not pre-parse request bodies, so the Pages Router bodyParser: false escape hatch is unnecessary — req.text() is already the raw payload.
Return a 2xx quickly. Providers treat a slow response as a failed delivery and retry it, so a slow handler races its own retries.
Delivery is at-least-once and unordered: dedupe by event ID with a database unique constraint, and fetch the current object from the provider's API instead of trusting payload state.
Compare signatures with crypto.timingSafeEqual and enforce a timestamp tolerance so a captured request cannot be replayed later.

Why does my signature check fail on a genuine request?

Because the signature was computed over the exact bytes the provider sent, and the handler is verifying different bytes. A webhook signature is a keyed hash — an HMAC — of the raw request body, produced with a shared signing secret. If I call JSON.parse on the body and re-serialize it to verify, key order, whitespace, and unicode escaping can all change, and the HMAC no longer matches even though the request is genuine. The failure is silent and total: every event gets a 400, the provider retries, and the retry queue fills while the code looks correct.

The App Router makes the correct version easy. A route handler receives the standard web Request object, and Next.js does not pre-parse it — await req.text() returns the payload byte-for-byte. The Pages Router needed export const config = { api: { bodyParser: false } } for the same access; that configuration does nothing in the App Router.

// app/api/webhooks/stripe/route.ts
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
  const rawBody = await req.text();               // raw bytes — parse AFTER verification
  const signature = req.headers.get('stripe-signature');

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      rawBody,
      signature!,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch {
    return new Response('invalid signature', { status: 400 });
  }

  return new Response('ok', { status: 200 });
}

When the provider ships a verification helper, I use it. stripe.webhooks.constructEvent checks both the HMAC and the signed timestamp in one call and throws on either failure.

How do I verify a webhook signature without an SDK helper?

Compute the HMAC yourself and compare in constant time. Two rules are non-negotiable. First, compare with crypto.timingSafeEqual, because an ordinary string comparison returns early at the first differing character and leaks timing information an attacker can use to probe signatures byte by byte. Second, enforce a timestamp tolerance — most providers include a signed timestamp, and rejecting anything older than about five minutes stops a captured request from being replayed later.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifySignature(rawBody: string, header: string, secret: string) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const received = header.replace(/^sha256=/, '');   // GitHub prefixes the hex digest
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(received, 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

One structural note: a webhook endpoint must be a route handler, not a Server Action. A Server Action is an RPC mechanism for my own application's frontend, addressed by framework-generated identifiers. A webhook needs a stable public POST URL with byte-level body access, and app/api/webhooks/<provider>/route.ts is exactly that.

Why should the handler return 200 before doing the real work?

Because the provider treats a slow response as a failed delivery. Delivery timeouts are measured in seconds, and a handler that exceeds one gets marked failed and retried — so the slow handler ends up running concurrently with its own retry. Fulfillment logic that takes ten seconds guarantees every real event arrives at least twice.

The shape I use now is verify, record, acknowledge, then work. On Vercel, waitUntil from @vercel/functions keeps the function instance alive after the response has been sent.

import { waitUntil } from '@vercel/functions';

export async function POST(req: Request) {
  const event = await verifyAndParse(req);
  if (!event) return new Response('invalid signature', { status: 400 });

  const fresh = await recordEventId(event.id);   // unique constraint = dedupe
  if (fresh) waitUntil(processEvent(event));     // runs after the response is sent

  return new Response('ok', { status: 200 });    // acknowledge in milliseconds
}

Where the work runs	Ack speed	On a crash	Reach for it when
Inline, before the response	Slow — bounded by the work	Provider retry re-delivers the event	Trivial work: set a flag, update one row
`waitUntil`, after the response	Fast	Work is lost; event already acknowledged	Losable side effects: cache warming, notifications
Queue or job row, separate worker	Fast	Job survives and is retried	Money, entitlements, anything you cannot lose

The queue row is the only option I trust for money. waitUntil work that dies in a crash was already acknowledged with a 200, and the provider will never resend it.

How do I handle retries and out-of-order events?

By assuming at-least-once delivery and no ordering, because both are documented provider behavior, not edge cases.

Deduplication: every provider event carries a stable ID — evt_… on a Stripe event, the X-GitHub-Delivery header on a GitHub delivery. I insert that ID into a table with a unique constraint before processing; a constraint violation means the event was already handled, so the handler returns 200 and stops. A SELECT-then-INSERT check is a race under concurrent retries — the constraint is the lock.

Ordering: I do not build state by applying payloads in arrival order. The event is a notification that something changed, not the change itself. For anything stateful I fetch the current object from the provider's API before writing, so a stale payload cannot overwrite newer state.

How do I test webhooks locally?

A provider cannot reach localhost, so local testing needs a bridge. Three options cover my use: a provider CLI that forwards events — stripe listen --forward-to localhost:3000/api/webhooks/stripe prints a temporary signing secret for the session; a tunnel such as cloudflared or ngrok plus the provider dashboard's manual redelivery button; and signed fixtures in tests.

The fixtures are the ones that pay rent. I capture one real payload, compute its HMAC with a test secret, and assert three things: the verifier accepts the valid pair, rejects a mutated body, and rejects an expired timestamp. That test catches the raw-body regression — someone adding a JSON middleware or moving the parse above the verify — before it ships and silently 400s every event.

FAQ

Q: Can a Server Action be a webhook endpoint?

A: No. A Server Action is invoked through framework-generated identifiers and is designed for your own application's components. A webhook provider needs a stable public POST URL with raw-body access, which is a route handler.

Q: Do I still need bodyParser: false in the App Router?

A: No. That option configures Pages Router API routes. An App Router route handler leaves the body untouched until you call req.text(), req.json(), or req.formData().

Q: What should I return for event types I do not handle?

A: Return 200. A non-2xx response tells the provider the delivery failed, so it retries events you will never process, and some providers disable an endpoint that keeps failing. Reserve 400 for signature failures.

Q: What happens to events sent while my deployment was down?

A: Providers retry failed deliveries with backoff — Stripe retries for days — so short downtime is usually absorbed. For critical state I also run a periodic reconciliation job against the provider's API.

Q: How do I rotate a webhook secret without downtime?

A: Verify incoming signatures against both the old and the new secret during the rotation window. Providers like Stripe allow an old signing secret to stay active for an overlap period for exactly this reason.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

next/image in Next.js 16: Field Notes on LCP, the sizes Prop That Doubles Bandwidth, and What Optimization Costs

Ahmed Mahmoud — Sat, 22 Aug 2026 13:36:14 +0000

Headline: Using next/image is not the same as having fast images. The component lazy-loads every image it renders unless you pass priority, and a wrong sizes prop makes a 400-pixel-wide card download the 3840-pixel candidate on a high-DPR screen.

next/image is the Next.js built-in component that generates a responsive srcset, converts source files to modern formats on demand, and reserves layout space before a byte arrives. I have used it on every Next.js project I have built, and I still spent an afternoon this month working out why a page full of <Image> tags had a worse Largest Contentful Paint than the plain <img> markup it replaced. The layout-shift half is automatic. The bandwidth and latency half is not.

Key takeaways

next/image lazy-loads every image by default, including the one that is your Largest Contentful Paint element. Only the priority prop opts an image out of lazy loading and adds a preload hint.
The sizes prop tells the browser how wide the image will render before CSS is applied. An <Image fill> with no sizes is treated as 100vw, which selects the largest candidate in the srcset.
Next.js 16 removed the images.domains option, so images.remotePatterns is the only way to allow a remote host.
Next.js 16 restricts the quality prop to values listed in images.qualities, which defaults to [75].
An image transformation is a unique combination of source image, width, quality and output format, so a wide deviceSizes array multiplies both cost and cache misses.

Why is my LCP still slow when I already use next/image?

Because next/image lazy-loads every image by default, including the one that is your Largest Contentful Paint element. Largest Contentful Paint measures when the biggest visible element finishes rendering. A lazy image is not requested until the browser has run layout and decided the image is near the viewport, so the preload scanner — which normally starts image downloads while the HTML is still being parsed — never sees it.

The fix is one prop, applied to exactly one image per route:

import Image from 'next/image';
import hero from '@/public/hero.jpg';

export default function Hero() {
  return (
    <Image
      src={hero}        // static import: width, height and blurDataURL come for free
      alt=""
      priority          // no lazy loading, fetchpriority="high", preload hint in head
      sizes="100vw"
      className="w-full h-auto"
    />
  );
}

The priority prop does three things: it removes loading="lazy", sets fetchpriority="high", and emits a preload link in the document head. Marking six images priority is the same as marking none, because six high-priority requests then compete for the same connection.

Two related traps cost me time. First, placeholder="blur" inlines a base64 data URI into the HTML, so a heavy blurDataURL grows the document on the critical path. Second, an image rendered by a client component that only mounts after hydration cannot be preloaded at all, whatever you pass to priority — the markup does not exist when the preload scanner runs.

What does the sizes prop actually do, and when does it double my bandwidth?

The sizes attribute tells the browser how wide the image will be rendered, so it can pick a srcset candidate before stylesheets are applied. Choose the candidate list badly and the browser downloads the biggest file you offered it.

Without sizes, Next.js emits a fixed 1x/2x srcset built from the width you passed. With sizes, it emits a full candidate list drawn from images.deviceSizes (default 640, 750, 828, 1080, 1200, 1920, 2048, 3840) and images.imageSizes (default 16, 32, 48, 64, 96, 128, 256, 384). The fill prop with no sizes is treated as 100vw, so on a 1920-pixel display at device pixel ratio 2 the browser asks for the 3840-pixel file — for a card that renders at 400 pixels.

// A product card image that is never wider than 400 CSS pixels.
<Image
  src={product.image}
  alt={product.name}
  fill
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 400px"
/>

The rule I now apply in review: an <Image fill> with no sizes prop is a defect, not a style preference. Verify it in the Chrome DevTools Network panel by comparing the transferred size of each image against the box it renders into.

Should I use fill or explicit width and height?

Use explicit width and height whenever you know the intrinsic dimensions, because Next.js turns them into a CSS aspect-ratio that reserves space and keeps Cumulative Layout Shift at zero. A static import supplies both dimensions and a generated blurDataURL at build time, so it is the cheapest correct option for any asset in your repository.

Reach for fill only when the rendered box is decided by CSS and the source aspect ratio varies — user-uploaded avatars, CMS hero images, a masonry grid. fill absolutely positions the image, so the parent needs position: relative and a non-zero height, and cropping is your job through object-fit. Every fill image also needs a sizes prop.

What changed for images in Next.js 16?

Next.js 16 tightened image configuration in three ways that break existing config files. The images.domains option was removed in favour of images.remotePatterns. The quality prop is now restricted to values listed in images.qualities, which defaults to [75]. And images.localPatterns lets you restrict which local paths the optimizer will accept, which matters because /_next/image is a public endpoint that anyone can call with arbitrary parameters.

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  images: {
    // images.domains was removed in Next.js 16. remotePatterns is the only form.
    remotePatterns: [
      { protocol: 'https', hostname: 'cdn.example.com', pathname: '/products/**' },
    ],
    // Only these quality values are accepted. Anything else is rejected.
    qualities: [50, 75],
    localPatterns: [{ pathname: '/assets/**', search: '' }],
    formats: ['image/avif', 'image/webp'],
    // Set this explicitly. A short TTL recomputes transformations you already paid for.
    minimumCacheTTL: 60 * 60 * 24 * 31,
  },
};

export default nextConfig;

SVG is still refused by the optimizer unless you set dangerouslyAllowSVG: true, and that default is correct: an SVG is an executable document, and optimizing one from an untrusted host turns your own origin into the delivery vehicle for its scripts.

Should images.formats list AVIF or WebP first?

List AVIF first when bandwidth is the constraint, and WebP first when first-request latency is. The images.formats array is ordered by preference, and the optimizer picks the first entry the requesting browser accepts.

Format	File size	Encode cost	Reach for it when
AVIF	Smaller than WebP at equal visual quality	Noticeably slower to encode	Images are cached and served many times; bytes dominate
WebP	Larger than AVIF, far smaller than JPEG	Fast	Long-tail images with few hits, where every request is a cache miss
JPEG/PNG source	Largest	None	Fallback only, for clients that accept neither

The trade-off is uneven across your site. On a marketing page with five hero images that every visitor loads, AVIF encoding happens once and the smaller bytes win forever. On a catalogue with fifty thousand product photos where most are viewed once, the slower encode is on the critical path of a real user every time.

How do I keep image transformation cost bounded?

An image transformation is a unique combination of source image, requested width, quality and output format, and each unique combination is computed and billed once before it is cached. That definition is the whole cost model: everything that multiplies the number of distinct combinations multiplies your bill.

Trim deviceSizes. Eight default widths times two formats is sixteen possible transformations per source image. If your layout has three real breakpoints, list three widths.
Use one quality value. Next.js 16 already forces you to declare them; declare one.
Raise minimumCacheTTL. Next.js honours an upstream Cache-Control max-age when it is longer than minimumCacheTTL, so a CMS that sends no-store quietly defeats the cache.
Set unoptimized on assets that are already optimized — sprite sheets, small PNG icons, anything your build pipeline has already squeezed.
Watch for cache-busting query strings. A source URL with a changing token is a new source image every time, and therefore a new transformation every time.

When should I bypass next/image entirely?

Three cases justify leaving the component behind. For art direction — a different crop on mobile than desktop — call getImageProps() (stable since Next.js 15, previously unstable_getImgProps) to obtain the generated srcset and feed it into your own <picture> element or a CSS background. For a static export (output: 'export') there is no server to run the optimizer, so you must set images.unoptimized: true or supply a custom loader. And if you already pay for an image CDN such as Cloudinary or imgix, point images.loaderFile at it rather than optimizing twice.

Self-hosting has one more requirement worth stating plainly: the built-in optimizer needs the sharp package installed. The pure-JavaScript fallback was removed in earlier releases, so a self-hosted deployment without sharp will fail to optimize rather than silently degrade.

FAQ

Q: Should I add priority to every above-the-fold image?

A: No. Add priority to the single image most likely to be the Largest Contentful Paint element. Multiple high-priority images compete for bandwidth and delay the one that actually determines the metric.

Q: Why does my optimized image look soft on a Retina screen?

A: Next.js never upscales beyond the intrinsic size of the source file. If the browser requests a 1600-pixel candidate and the source is 800 pixels wide, you get 800 pixels rendered into a 1600-pixel box. Replace the source asset; no configuration fixes it.

Q: Do I need sharp when self-hosting Next.js?

A: Yes. The built-in image optimizer requires the sharp package outside of Vercel, where the platform provides its own optimization layer.

Q: Does next/image work with output: 'export'?

A: Not with the default loader, because a static export has no server. Set images.unoptimized: true to emit plain <img> tags, or configure images.loaderFile to point at an external image CDN.

Q: Is AVIF always the better choice?

A: No. AVIF produces smaller files than WebP at comparable quality but takes measurably longer to encode, so on images with low cache-hit rates the encode time lands on a real user's first request.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Rate Limiting in the Next.js App Router: Field Notes on Middleware, Redis, and the Server Action That Looks Like Every Other POST

Ahmed Mahmoud — Wed, 19 Aug 2026 06:00:14 +0000

Headline: An in-memory rate limiter is wrong on serverless because every function instance keeps its own counter, so a limit of 10 requests per minute becomes 10 requests per minute per instance. The second trap is that every Next.js Server Action POSTs to the URL of the page that called it, so path-based limiting in middleware cannot tell one action from another.

A rate limiter is a counter with a deadline: allow N requests per identity per time window and reject the rest with HTTP 429. I have written that in ten lines before and been happy with it. Moving the same idea into a Next.js 16 App Router project on Vercel broke it in three places I did not expect — where the counter lives, who counts as an identity, and how you attach a limit to a Server Action that has no URL of its own.

Key takeaways

An in-memory Map rate limiter is per-instance on serverless. With ten warm function instances, a 10-requests-per-minute limit permits 100 requests per minute.
Next.js middleware is the cheapest place to shed abusive traffic because it runs before the route's own function boots, but it also sees RSC prefetch requests that carry the RSC: 1 header and that the user never intentionally made.
NextRequest.ip was removed in Next.js 15. On Vercel, read the client address with ipAddress(request) from @vercel/functions instead of trusting a raw x-forwarded-for header.
Every Next.js Server Action POSTs to the current page URL and carries a build-generated Next-Action header, so the only reliable place to limit a specific action is inside the action body.
Reject with status 429 and a Retry-After header, and decide fail-open versus fail-closed per route before your Redis has its first outage.

Why does an in-memory rate limiter break on serverless?

A module-scope Map is private to one function instance, and a serverless platform runs many instances at once. Each instance therefore enforces the full limit on its own, so the effective limit is your configured limit multiplied by the number of warm instances. That number is not something you control or can observe from inside the request.

This is the code I have shipped and regretted:

// Do not ship this to a serverless runtime.
const hits = new Map<string, { count: number; reset: number }>();

export function limit(key: string, max = 10, windowMs = 60_000) {
  const now = Date.now();
  const entry = hits.get(key);
  if (!entry || entry.reset < now) {
    hits.set(key, { count: 1, reset: now + windowMs });
    return { ok: true };
  }
  entry.count += 1;
  return { ok: entry.count <= max };
}

Vercel Fluid Compute makes this harder to notice rather than easier. Fluid Compute reuses a single function instance across concurrent requests instead of spawning one per request, so the Map survives far longer than it did under classic serverless. In local development and in a quiet preview deployment the limiter looks correct. It only comes apart under traffic spread across enough instances to matter, and nothing in the logs announces it.

The Map also never shrinks. On a long-lived instance every unique key you have ever seen stays resident until the instance is recycled, which is a slow memory leak wearing a rate limiter costume.

The fix is not a cleverer Map. The counter has to live in a store that every instance shares and that supports an atomic increment: Redis, or any datastore with a compare-and-set primitive.

Should the limit run in middleware or in the route handler?

Both, for different jobs. Middleware runs before Next.js resolves the route, so a request rejected there never boots the route's function and never touches your database. That makes middleware the correct place for a coarse, identity-agnostic abuse limit. The route handler knows the authenticated user, the parsed body, and the business meaning of the call, which makes it the correct place for a per-user quota.

// middleware.ts
import { NextResponse, type NextRequest } from 'next/server';
import { ipAddress } from '@vercel/functions';
import { ratelimit } from '@/lib/ratelimit';

export const config = {
  matcher: ['/api/:path*', '/login', '/signup'],
};

export async function middleware(request: NextRequest) {
  // RSC prefetches fire on link hover. The user did not ask for these.
  if (request.headers.get('rsc') === '1') return NextResponse.next();

  const ip = ipAddress(request) ?? '127.0.0.1';
  const { success, limit, remaining, reset } = await ratelimit.limit(`ip:${ip}`);

  if (success) return NextResponse.next();

  return NextResponse.json(
    { error: 'rate_limited', message: 'Too many requests.' },
    {
      status: 429,
      headers: {
        'Retry-After': String(Math.ceil((reset - Date.now()) / 1000)),
        'X-RateLimit-Limit': String(limit),
        'X-RateLimit-Remaining': String(remaining),
        'X-RateLimit-Reset': String(reset),
      },
    },
  );
}

The rsc header check is the line I added after watching my own quota drain while I did nothing but move a mouse. The Next.js router prefetches linked routes on hover and on viewport entry, and those requests are real HTTP requests that hit middleware with an RSC: 1 header. Counting them means a user who scrolls a navigation-heavy page is rate limited before they click anything.

Since Next.js 15.5 you can also opt middleware into the Node.js runtime with export const config = { runtime: 'nodejs' }, which lets you use a normal Redis client there. I still prefer an HTTP-based store in middleware, because middleware sits on the latency path of every matched request.

Placement	Sees	Cost of a rejection	Use it for
Middleware	URL, headers, cookies, IP	Lowest — route function never boots	IP-level abuse and brute-force shielding
Route handler	Everything, including session and body	Function has already started	Per-user quotas, per-endpoint cost control
Server Action body	Session, typed arguments	Function has already started	Form submissions and mutations

Which algorithm should I actually use?

Pick the cheapest algorithm whose failure mode you can live with.

Fixed window keeps one counter per window, so a check is a single INCR. Its flaw is the boundary: ten requests at 11:59:59 and ten more at 12:00:00 pass a "ten per minute" limit while delivering twenty requests in one second.
Sliding window log stores a timestamp per request and is exact, but its memory grows with your traffic, which is the wrong direction for a defence against traffic.
Sliding window counter weights the previous window by how much of it still overlaps the current one. Bounded memory, no boundary burst, and my default.
Token bucket gives each identity a capacity and a refill rate, so a quiet client may spend saved tokens at once. Right for APIs whose clients legitimately batch.

The @upstash/ratelimit package ships all four as fixedWindow, slidingWindow, tokenBucket, and cachedFixedWindow. If you write your own against Redis, the thing to get right is atomicity. INCR followed by a separate EXPIRE is two round trips, and if the process dies between them you have created a key with no expiry, which locks that identity out permanently. Do it in one script:

-- One round trip. The TTL is set only on the first hit of a window.
local current = redis.call('INCR', KEYS[1])
if current == 1 then
  redis.call('PEXPIRE', KEYS[1], ARGV[1])
end
return current

How do I identify the client when everything sits behind a proxy?

A rate limit is only as good as its key. NextRequest.ip and NextRequest.geo were removed in Next.js 15, so reading request.ip is now a type error rather than a subtle wrong answer. On Vercel the replacement is ipAddress(request) from @vercel/functions.

Do not key on a raw x-forwarded-for header unless you are certain a trusted proxy overwrites it. x-forwarded-for is an ordinary request header, so on any origin reachable directly, an attacker sets it to a new value per request and gets an unlimited number of fresh limit buckets. That is a complete bypass, not a partial failure.

IPv6 needs its own rule. A single residential subscriber is routinely assigned an entire /64 prefix, so keying on the full 128-bit address hands one attacker 2^64 distinct identities.

function identityKey(request: NextRequest, userId?: string) {
  // A stable account beats a network address whenever you have one.
  if (userId) return `user:${userId}`;

  const ip = ipAddress(request) ?? '0.0.0.0';
  if (ip.includes(':')) {
    // One subscriber can own a whole /64. Key the prefix, not the address.
    return `ip6:${ip.split(':').slice(0, 4).join(':')}`;
  }
  return `ip4:${ip}`;
}

How do I rate limit a Server Action when every action is a POST to the same URL?

A Server Action is a function marked with the 'use server' directive that the client invokes over the network. The invocation is an HTTP POST to the URL of the page the action was called from, with a Next-Action header containing a build-generated identifier for that specific action. There is no dedicated route path, which is exactly what breaks the obvious approach.

In middleware, a POST from a contact form on /contact and a POST from a delete-account button on /contact are the same URL and the same method. You can read request.headers.get('next-action') to at least distinguish action POSTs from ordinary document requests, but that identifier is a hash that changes when the build changes, so branch on its presence and never on its value.

The reliable place is inside the action:

'use server';

import { headers } from 'next/headers';
import { auth } from '@/lib/auth';
import { ratelimit } from '@/lib/ratelimit';

export async function sendMessage(_prev: State, formData: FormData): Promise<State> {
  const session = await auth();
  const key = session?.user.id ?? (await headers()).get('x-forwarded-for') ?? 'anon';

  const { success, reset } = await ratelimit.limit(`action:sendMessage:${key}`);
  if (!success) {
    const seconds = Math.ceil((reset - Date.now()) / 1000);
    // Return a value. A thrown error reaches production as an opaque digest.
    return { ok: false, error: `Too many messages. Try again in ${seconds}s.` };
  }

  // ...the real work
  return { ok: true };
}

Returning a value rather than throwing matters. An uncaught error inside a Server Action is redacted in production and surfaces to the client as a generic message with a digest, so the user is told something went wrong instead of being told to wait forty seconds. Rate limiting is a normal outcome, not an exception.

What should a 429 response actually contain?

HTTP 429 Too Many Requests is the correct status, and Retry-After is the header that makes a limiter usable by anyone other than a human staring at a browser. Its value is either a number of seconds or an HTTP date.

Alongside it, emit the limit state. The X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset convention is not a standard but it is what most SDKs already parse. The IETF draft draft-ietf-httpapi-ratelimit-headers defines RateLimit and RateLimit-Policy as structured fields; adopt it only if your consumers understand it.

Two mistakes I have made and seen: returning 403 for a rate limit, which tells the client to stop forever rather than to retry, and returning 500, which pollutes your error rate with your own defences working correctly.

Then decide what happens when the store is unreachable, because it will be. Failing open on a login endpoint turns a Redis outage into an open brute-force window. Failing closed on a public read endpoint turns a Redis outage into a full outage of your site. I choose per route: fail closed on authentication and on anything that spends money, fail open on reads.

FAQ

Q: Can I rate limit in Next.js without Redis?
A: Only if your app runs as a single long-lived process, such as one container instance. On any serverless or autoscaled deployment the counter must live in a store shared across instances, because in-process state is multiplied by your instance count.

Q: Does Next.js middleware run on RSC prefetch requests?
A: Yes. Router prefetches are real HTTP requests that match your middleware matcher and carry the RSC: 1 header. Exclude them from user-facing quotas or they will consume a visitor's budget before the visitor clicks anything.

Q: How do I get the client IP in Next.js 15 and Next.js 16?
A: NextRequest.ip was removed in Next.js 15. On Vercel, call ipAddress(request) from @vercel/functions. Elsewhere, read the forwarded header your own trusted proxy sets and confirm that the proxy overwrites rather than appends it.

Q: Should a rate limiter fail open or fail closed when Redis is down?
A: Decide per route. Fail closed on login, signup, password reset, and payment endpoints, where failing open creates a security window. Fail open on public reads, where failing closed converts a dependency outage into a site outage.

Q: Is Vercel BotID a replacement for rate limiting?
A: No. Vercel BotID is bot detection, which answers whether a caller is automated. A rate limit answers how often any caller, human or not, may perform an expensive operation. They defend different things and compose well together.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

File Uploads in the Next.js App Router: Field Notes on Vercel Blob, Client Uploads, and the Callback That Never Fires on localhost

Ahmed Mahmoud — Tue, 18 Aug 2026 06:00:08 +0000

Headline: A Vercel Blob client upload sends the file directly from the browser to blob storage and never routes the bytes through your Next.js function, which is why it handles multi-gigabyte files that a route handler cannot. The cost is that your database row is written by a server-to-server callback named onUploadCompleted, and that callback never reaches http://localhost:3000.

I moved a document-upload feature off a plain route handler and onto Vercel Blob client uploads this month. The client-side code took twenty minutes. The next two days went to a callback that worked in production and silently did nothing on my machine, to a 409 I did not expect, and to a small pile of blobs nobody had a database row for. These are the notes I wish I had started with.

Key takeaways

Vercel Blob is Vercel's object storage service. The @vercel/blob package exposes put(), head(), list(), copy() and del() for server code, and a separate @vercel/blob/client entry point for browser uploads.
A client upload is a three-hop handshake: the browser asks your route handler for a one-time token, the browser sends the bytes directly to blob storage, then blob storage calls your route handler back at onUploadCompleted.
onUploadCompleted is an inbound HTTP request from Vercel's infrastructure to your public deployment URL, so it never arrives on localhost. Without a tunnel the upload succeeds and the database row is never written.
Since @vercel/blob v1 the addRandomSuffix option defaults to false, so uploading the same pathname twice fails with HTTP 409 unless you pass allowOverwrite: true.
The allowedContentTypes option validates the MIME type the browser declares, and the browser derives that from the file extension. Verify the file's magic bytes on the server before you trust it.

Why not just POST the file to a route handler?

A route handler upload is the right choice for small files and the wrong choice for large ones, because every byte travels through a serverless function you are billed for and that has a wall-clock limit. Vercel Functions now accept request bodies up to 100 MB, up from the old 4.5 MB ceiling, so proxying moderately sized files is genuinely viable in 2026 — it just does not scale past that.

If you do proxy, pass request.body straight into put(). Calling await request.formData() buffers the entire file in the function's memory before you have written a single byte to storage, which is how a 90 MB PDF turns into an out-of-memory error.

// app/api/upload-proxy/route.ts — fine for small files, wrong for large ones
import { put } from '@vercel/blob';

export async function POST(request: Request) {
  const filename = new URL(request.url).searchParams.get('filename');
  if (!filename || !request.body) return new Response('Bad request', { status: 400 });

  // Passing request.body straight through avoids buffering the file in memory.
  const blob = await put(filename, request.body, {
    access: 'public',
    addRandomSuffix: true,
  });

  return Response.json(blob);
}

Concern	Route handler (server proxy)	Client upload (`@vercel/blob/client`)
Practical file size ceiling	100 MB, the Vercel Functions request-body limit	Multi-gigabyte; bounded by the blob store, not the function
Function compute cost	Billed for the full duration of the transfer	Two short calls: issuing the token and handling the callback
Authentication	Simple — session cookies are on the request	Only on hop 1, inside `onBeforeGenerateToken`
Progress reporting	Requires your own streaming plumbing	Built in via `onUploadProgress`
Works end to end on localhost	Yes	No — the completion callback needs a public URL

How does a Vercel Blob client upload actually work?

A Vercel Blob client upload runs in three hops, and understanding which hop you are in explains almost every bug you will hit. Hop 1 is the browser POSTing to your route handler to request a scoped upload token. Hop 2 is the browser sending the file bytes directly to Vercel Blob. Hop 3 is Vercel Blob POSTing back to that same route handler to tell you the upload finished.

'use client';
import { upload } from '@vercel/blob/client';

async function handleFile(file: File) {
  const blob = await upload(file.name, file, {
    access: 'public',
    handleUploadUrl: '/api/upload',
    clientPayload: JSON.stringify({ folder: 'invoices' }),
    multipart: file.size > 100 * 1024 * 1024,
    onUploadProgress: ({ percentage }) => setProgress(percentage),
  });

  return blob.url; // already served from the CDN
}

The server side is a single route handler wrapping handleUpload, which dispatches hop 1 and hop 3 for you based on the request body it receives.

// app/api/upload/route.ts
import { handleUpload, type HandleUploadBody } from '@vercel/blob/client';
import { auth } from '@/lib/auth';

export async function POST(request: Request): Promise<Response> {
  const body = (await request.json()) as HandleUploadBody;

  try {
    const json = await handleUpload({
      body,
      request,
      // Hop 1: the browser's cookies are present here. This is your only auth gate.
      onBeforeGenerateToken: async (pathname, clientPayload) => {
        const session = await auth();
        if (!session) throw new Error('Unauthorized');
        if (!pathname.startsWith(`u/${session.user.id}/`)) throw new Error('Forbidden pathname');

        return {
          allowedContentTypes: ['image/png', 'image/jpeg', 'application/pdf'],
          maximumSizeInBytes: 25 * 1024 * 1024,
          addRandomSuffix: true,
          tokenPayload: JSON.stringify({ userId: session.user.id, clientPayload }),
        };
      },
      // Hop 3: server-to-server. No cookies, no session — only tokenPayload.
      onUploadCompleted: async ({ blob, tokenPayload }) => {
        const { userId } = JSON.parse(tokenPayload!);
        await db.insert(files).values({ userId, url: blob.url, pathname: blob.pathname });
      },
    });

    return Response.json(json);
  } catch (error) {
    return Response.json({ error: (error as Error).message }, { status: 400 });
  }
}

The single most important detail is that onUploadCompleted has no session. It is called by Vercel's infrastructure, not by your user's browser, so there are no cookies and no headers you control. Anything hop 3 needs to know must be serialized into tokenPayload during hop 1. I lost an hour calling auth() inside onUploadCompleted and getting null every time.

Why doesn't onUploadCompleted fire on localhost?

onUploadCompleted never fires on localhost because it is an inbound HTTP request from Vercel Blob to your application's public URL, and http://localhost:3000 is not routable from the public internet. The failure mode is deceptive: upload() resolves successfully, the file is genuinely in the blob store, the UI shows a green checkmark — and your database table stays empty forever.

The fix is to run your dev server behind a public tunnel and load the app through the tunnel hostname, not through localhost. handleUpload derives the callback URL from the incoming request, so merely exposing the port is not enough; the browser has to be on the tunnel origin when it starts the upload.

# Terminal 1
npm run dev

# Terminal 2 — then open the printed https URL, not localhost:3000
ngrok http 3000

Do not paper over this with a client-side confirmation call. Having the browser POST to a second endpoint after upload() resolves looks like it works, but it is best-effort by construction: if the tab closes in that gap the row is lost, and you now have two code paths that can write the same row.

How do I stop two users from overwriting each other's files?

In Vercel Blob the pathname is the object's identity, so two uploads with the same pathname collide. Since @vercel/blob v1 the addRandomSuffix option defaults to false, which means a second upload of invoice.pdf returns HTTP 409 instead of quietly replacing the first one. That default is the safe one, and it caught a bug for me on day one.

You have two coherent strategies. Set addRandomSuffix: true and let Vercel append a random token to every pathname, which makes collisions impossible but means re-uploading the same file creates a second object. Or build a deterministic namespaced pathname such as u/{userId}/{documentId}/{filename} and pass allowOverwrite: true, which makes re-upload idempotent.

The trap in the second strategy is that the client chooses the pathname. Combining a user-supplied pathname with allowOverwrite: true lets one account clobber another account's file. Validate the prefix inside onBeforeGenerateToken against the authenticated session, as in the handler above, and reject anything outside the caller's namespace.

How do I validate file type when the browser can lie?

The allowedContentTypes option checks the Content-Type the browser declares, and on most platforms the browser derives that value from the file extension. Renaming payload.exe to avatar.png is enough to make Chrome report image/png, so allowedContentTypes is a usability guard, not a security control.

Real validation happens in onUploadCompleted, after the bytes exist. Fetch the first few bytes with a Range header, compare against the format's magic number, and del() the blob if it does not match.

import { del } from '@vercel/blob';

const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);

onUploadCompleted: async ({ blob }) => {
  // Read only the header; never download a whole file to check four bytes.
  const res = await fetch(blob.url, { headers: { Range: 'bytes=0-7' } });
  const head = Buffer.from(await res.arrayBuffer());

  if (!head.subarray(0, 4).equals(PNG_MAGIC)) {
    await del(blob.url);
    return;
  }

  await db.insert(files).values({ url: blob.url, pathname: blob.pathname });
}

One related correction I had to make to my own mental model: a blob created with access: 'public' is world-readable to anyone holding the URL, and an unguessable URL is obscurity rather than access control. Vercel Blob supports private storage, so anything that must stay restricted should be uploaded with private access and served through a route handler that checks the session.

What happens to the blob when the database write fails?

Nothing happens to the blob — it stays in the store and you keep paying for it. The blob store and your database are two independent systems with no shared transaction, so a failure inside onUploadCompleted leaves an object no row points to. Over months of retries and timeouts that set grows quietly.

I settled on two-phase bookkeeping. During hop 1, insert a row with status pending keyed by the pathname you are about to authorize. During hop 3, flip it to ready. Then run a scheduled sweeper that pages through the store with list() and deletes anything older than a day that no row claims.

import { list, del } from '@vercel/blob';

const cutoff = Date.now() - 24 * 60 * 60 * 1000;
let cursor: string | undefined;

do {
  const page = await list({ cursor, limit: 1000 });
  const known = await knownPathnames(page.blobs.map((b) => b.pathname));

  const orphans = page.blobs.filter(
    (b) => !known.has(b.pathname) && b.uploadedAt.getTime() < cutoff,
  );

  if (orphans.length) await del(orphans.map((b) => b.url));
  cursor = page.cursor;
} while (cursor);

The age cutoff matters. Without it the sweeper will delete a blob whose onUploadCompleted is still in flight, which is a far worse bug than the leak it was meant to fix.

How do I show real upload progress for a very large file?

The upload() and put() functions both accept an onUploadProgress callback that receives { loaded, total, percentage }, so a real progress bar needs no custom streaming code. Setting multipart: true splits the file into chunks uploaded in parallel with per-chunk retry, which is what makes a large upload survive a flaky connection.

Two behaviours surprised me. With multipart enabled, progress advances in visible steps as parts complete rather than moving smoothly, so a naive animated bar looks broken. And multipart adds request overhead per chunk, which is pure waste on a 2 MB avatar — I gate it on file size rather than enabling it globally. If you need to let users cancel, upload() accepts an abortSignal, and aborting mid-flight means onUploadCompleted simply never runs, which your reconciliation job already handles.

FAQ

Q: Do I still need a route handler if I use client uploads?

A: Yes. handleUpload lives in a route handler that the browser calls to obtain a one-time token and that Vercel Blob calls back when the upload finishes. Only the file bytes bypass it.

Q: Is a public Vercel Blob URL secure because it is unguessable?

A: No. A blob created with access: 'public' is readable by anyone who has the URL and is cached by the CDN. Use Vercel Blob's private storage plus a session-checking download route for anything sensitive.

Q: When should I turn on multipart: true?

A: When a single failed transfer would be expensive to retry — roughly files of 100 MB and up. Multipart adds one request per chunk, so it is not worth the overhead for small images.

Q: What happens if the user closes the tab mid-upload?

A: The transfer dies and onUploadCompleted never runs, so no database row is created. Your reconciliation sweep is what removes the partial artefacts, which is one more reason to build it early.

Q: Can I rename or move a blob after it is uploaded?

A: Not in place. Use copy() from @vercel/blob to write the object to a new pathname and then del() the original. Because pathname is the blob's identity, choose a naming scheme before you have a million objects.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Web Push in the Next.js App Router: Field Notes on Service Workers, VAPID, and the iOS Rule That Silently Blocks Everything

Ahmed Mahmoud — Mon, 17 Aug 2026 06:00:11 +0000

Headline: Web Push is a browser API that delivers a server-sent notification to a device while your site is closed, and in a Next.js App Router project it needs exactly three parts: a service worker served from the origin root, a VAPID key pair, and a Node.js-runtime route handler that sends. On iOS Safari it needs a fourth thing nobody documents loudly enough — the user must install the site to the Home Screen first.

I wired Web Push into a Next.js 16 App Router project this month. The happy path took an afternoon. The rest of the week went to iOS, to subscriptions that had quietly died months earlier, and to a service worker the browser refused to replace. These are the notes I wish I had on day one.

Key takeaways

Web Push needs a service worker at the origin root (/sw.js), because a service worker's scope can never be broader than the path it is served from. In Next.js that means public/sw.js.
VAPID (Voluntary Application Server Identification) is a public/private key pair that authenticates your server to the browser's push service. Generate it once with npx web-push generate-vapid-keys and never rotate it casually.
iOS Safari 16.4 and later support Web Push, but only after the user adds the site to the Home Screen and the app runs in display: standalone mode. In a normal iOS tab, window.PushManager is undefined.
A push service returning HTTP 404 or 410 means the subscription is permanently dead. Delete the row immediately.
Send pushes from the Node.js runtime, not the Edge runtime: the web-push package uses Node's crypto module for aes128gcm payload encryption.

What does Web Push actually require in a Next.js app?

Web Push requires three moving parts and nothing else: a registered service worker, a PushSubscription obtained from registration.pushManager.subscribe(), and a server that signs its requests with VAPID keys. There is no vendor SDK in the critical path — Firebase Cloud Messaging is one browser's push endpoint, not a requirement of the protocol.

The service worker file has to live in public/sw.js so Next.js serves it at /sw.js. A service worker's scope — the set of pages it is allowed to control — defaults to the directory it was served from, so a worker served from /_next/static/sw.js can only control pages under /_next/static/, which is no pages at all. Files in public/ are copied verbatim and never bundled, so you cannot import npm packages there.

// components/EnablePush.tsx (client component)
async function enablePush(vapidPublicKey: string) {
  const reg = await navigator.serviceWorker.register('/sw.js');

  // Must be called inside a user gesture — click handler, not useEffect.
  const permission = await Notification.requestPermission();
  if (permission !== 'granted') return null;

  const sub = await reg.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: vapidPublicKey,
  });

  await fetch('/api/push/subscribe', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(sub),
  });

  return sub;
}

Chrome and Firefox accept a base64url string for applicationServerKey. Older Safari builds and some Android WebViews still want a Uint8Array, which is why most production code keeps a small urlBase64ToUint8Array() helper around. userVisibleOnly: true is not optional anywhere — you are promising to display a notification for every push you receive, and Chrome will eventually revoke a subscription that repeatedly breaks that promise.

Why does my push prompt do nothing on iOS Safari?

iOS Safari only exposes the Push API to sites installed on the Home Screen. In a normal Safari tab on iOS, window.PushManager is undefined and the permission prompt never appears — no error, no rejected promise, nothing to debug. Web Push landed in iOS 16.4 in March 2023 with exactly this constraint, and it still holds.

const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
const isStandalone = window.matchMedia('(display-mode: standalone)').matches;
const canPrompt = 'PushManager' in window && (!isIOS || isStandalone);

When an iOS user is browsing in a tab, show install instructions instead of a button that does nothing. You also need a manifest declaring "display": "standalone", or the installed shortcut opens back into Safari chrome and never qualifies.

Safari 18.4, shipped in March 2025, added Declarative Web Push: the server sends a JSON payload containing a web_push key set to 8030 plus a notification object, and the browser renders the notification without running your service worker's push handler at all. It is additive — the classic service worker path is still required for Chrome and Firefox.

How do I send a push from a Next.js route handler?

Send pushes from a route handler on the Node.js runtime using the web-push package, which handles VAPID signing and aes128gcm payload encryption. Do not put export const runtime = 'edge' on this route — the encryption path depends on Node's crypto module. On Vercel the Node.js runtime is the default and runs on Fluid Compute.

// app/api/push/send/route.ts
import webpush from 'web-push';

webpush.setVapidDetails(
  'mailto:alerts@example.com',
  process.env.VAPID_PUBLIC_KEY!,
  process.env.VAPID_PRIVATE_KEY!,
);

export async function POST(req: Request) {
  const { userId, title, body, url } = await req.json();
  const subs = await db.pushSubscription.findMany({ where: { userId } });

  const results = await Promise.allSettled(
    subs.map((s) =>
      webpush.sendNotification(
        { endpoint: s.endpoint, keys: { p256dh: s.p256dh, auth: s.auth } },
        JSON.stringify({ title, body, url }),
      ),
    ),
  );

  // 404 / 410 = gone forever. Prune now, not "later".
  await Promise.all(
    results.map((r, i) =>
      r.status === 'rejected' && [404, 410].includes(r.reason?.statusCode)
        ? db.pushSubscription.delete({ where: { endpoint: subs[i].endpoint } })
        : null,
    ),
  );

  return Response.json({
    sent: results.filter((r) => r.status === 'fulfilled').length,
  });
}

Keep the payload small. Push services guarantee only about 4 KB of encrypted payload, and encryption overhead eats into that budget. Send an identifier plus a short title, then fetch the full record on click. Payload contents also sit on a third-party push server until delivery, which is a second reason to keep them thin.

// public/sw.js
self.addEventListener('push', (event) => {
  const data = event.data ? event.data.json() : {};
  event.waitUntil(
    self.registration.showNotification(data.title ?? 'Update', {
      body: data.body,
      data: { url: data.url ?? '/' },
      tag: data.tag, // same tag replaces instead of stacking
    }),
  );
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  const target = new URL(event.notification.data.url, self.location.origin);
  event.waitUntil(
    clients.matchAll({ type: 'window', includeUncontrolled: true }).then((wins) => {
      const open = wins.find((w) => new URL(w.url).origin === target.origin);
      return open ? open.focus() : clients.openWindow(target.href);
    }),
  );
});

When should I delete a push subscription?

Delete a subscription the moment the push service answers 404 or 410 Gone — those two status codes mean the endpoint will never be valid again. Subscriptions die constantly and silently: users clear site data, reinstall the browser, or revoke permission, and nothing notifies your server.

The other status codes need different handling. A 413 means your payload exceeded the size limit. A 429 means you are rate limited and should honour the Retry-After header instead of looping. A 401 or 403 almost always means your VAPID keys do not match the ones used at subscribe time — which is why rotating VAPID keys forces a re-subscribe across your whole user base.

Browsers can also rotate an endpoint themselves, firing a pushsubscriptionchange event in the service worker. Chrome fires it reliably; support elsewhere is uneven. Treat it as a bonus path and let 410-pruning plus a re-subscribe on the next visit be your real recovery mechanism.

Web Push vs SSE vs WebSockets: which should I use?

Web Push is the only one of the three that works when your site is closed. The deciding question is whether the user is present.

Transport	Works with the tab closed	Direction	Best for
Web Push	Yes	Server to device	Re-engagement, alerts the user must not miss
Server-Sent Events (SSE)	No	Server to open page	AI token streaming, progress, live feeds
WebSockets	No	Bidirectional	Collaborative editing, chat, presence

They compose. In the project I shipped, SSE carries live updates while the tab is open, and a background job fires a Web Push only when the user has had no active session for a few minutes. That single rule stopped the same event arriving twice.

What breaks in production that local dev never shows?

The failure that cost me most was a stale service worker. A browser keeps the old sw.js until the file's bytes change and the new worker finishes installing, so a fixed push handler can sit unused on real devices for a day. Calling self.skipWaiting() in install and clients.claim() in activate shortens that window, and logging a version string from the worker tells you which build actually handled a push.

The second was permission UX. Notification.requestPermission() can only be called from a user gesture, and once a user chooses Block you cannot prompt again from JavaScript on that origin — ever. Prompting on page load burns the one chance you get.

The third was fan-out. Every sendNotification() call is a separate HTTPS round trip to a third-party service, so tens of thousands of them do not belong in a request handler. Move that to a queue or background job, batched with Promise.allSettled.

The fourth was localhost lying to me. Service workers and the Push API are permitted on http://localhost as a secure-context exception, so everything works locally and then fails on a staging host served over plain HTTP. Test push on a real HTTPS origin, on a real phone.

FAQ

Q: Do I need Firebase Cloud Messaging to send Web Push?
A: No. FCM is Chrome's push endpoint, but the Web Push protocol with VAPID lets your own server post directly to whatever endpoint the browser hands you. The web-push npm package speaks that protocol to Chrome, Firefox, and Safari endpoints alike.

Q: Can I send a silent push that does not show a notification?
A: Not on the open web. userVisibleOnly: true is mandatory in Chrome, Firefox, and Safari, and repeatedly receiving a push without displaying a notification can get the subscription revoked.

Q: Why did all my subscriptions stop working after a deploy?
A: Almost always rotated VAPID keys. The public key is baked into every existing PushSubscription, so a new key pair makes stored subscriptions fail authentication and every user has to re-subscribe.

Q: How do I test Web Push without waiting for a real event?
A: Chrome DevTools has a Push field under Application → Service Workers that dispatches a payload straight into your worker's push handler. That tests rendering but skips VAPID and encryption, so also call your send route against your own subscription.

Q: Does Web Push work in a Next.js app installed to the iOS Home Screen?
A: Yes. iOS treats an installed PWA as eligible regardless of framework, as long as the manifest sets "display": "standalone" and the permission request comes from a user gesture inside the installed app.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Content Security Policy in the Next.js App Router: Field Notes on Nonces, strict-dynamic, and the Middleware That Made Every Page Dynamic

Ahmed Mahmoud — Fri, 14 Aug 2026 06:02:54 +0000

Headline: A Content Security Policy (CSP) is an HTTP response header that tells the browser which script, style, and connection sources a document is allowed to use, and in the Next.js App Router the only script policy that survives the framework's runtime chunk loading is a per-request nonce combined with 'strict-dynamic'. The cost I did not budget for: generating that nonce in middleware.ts and reading it with headers() opts every matched route out of static rendering.

Key takeaways

A CSP nonce is a per-request random token that appears both in the script-src directive and as a nonce attribute on every allowed <script>. Because it must never repeat, HTML carrying a nonce cannot be cached — which is exactly why Next.js drops the route to dynamic rendering.
A host allowlist cannot secure a Next.js app. The App Router emits an inline bootstrap payload (self.__next_f.push(...)) and then creates further <script> elements at runtime, so script-src 'self' both fails to allow the inline payload and fails to distinguish framework chunks from any other same-origin file.
'strict-dynamic' propagates trust from a nonce-allowed script to any script element that script creates programmatically. It is what makes chunk loading work without enumerating chunk URLs.
Keeping 'unsafe-inline' and https: in script-src is a deliberate fallback, not a hole. A browser that understands nonces ignores 'unsafe-inline', and a browser that understands 'strict-dynamic' ignores every host expression in the same directive.
Ship Content-Security-Policy-Report-Only first. The enforcing header turns a policy mistake into a blank page; the report-only header turns the same mistake into a log line.

What does a Content Security Policy actually stop?

A Content Security Policy does not stop injection. It stops execution. If an attacker gets <script>fetch('/api/me')</script> into a comment field that I render with dangerouslySetInnerHTML, the markup still lands in the DOM — but a policy without 'unsafe-inline' means the browser refuses to run it and emits a violation report instead.

Four directives paid for themselves in my apps before I touched script-src at all, because none of them require a nonce and none of them break anything: object-src 'none' removes the legacy plugin vector, base-uri 'self' stops an injected <base> tag from silently repointing every relative URL on the page, form-action 'self' stops an injected form from posting credentials to another origin, and frame-ancestors 'none' is the modern replacement for X-Frame-Options. Those four can go in next.config.js under headers() and stay fully cacheable.

The expensive directive is script-src. That is the one that requires the nonce.

Why does Next.js need a nonce instead of a domain allowlist?

A domain allowlist cannot express what the App Router does at runtime. Next.js serializes the React Server Component payload into inline <script> tags on the document, and its client runtime then creates additional script elements to fetch route chunks on demand. script-src 'self' blocks the inline payload outright, and even if it did not, 'self' would happily execute any same-origin URL — including a user-uploaded file served from my own domain.

'strict-dynamic' is the CSP Level 3 keyword that fixes this. It says: any script element created by an already-trusted script inherits that trust. The inline bootstrap gets its trust from the nonce, and every chunk it loads afterwards inherits it. No chunk hashes, no build-time URL enumeration.

The counterintuitive part is what 'strict-dynamic' switches off. In a browser that implements it, all host-source expressions in the same directive — 'self', https:, a literal CDN domain — are ignored. That is why the recommended policy still lists them: they are a graceful degradation path for older browsers, not additional permission for modern ones.

How do I generate and propagate a CSP nonce in the App Router?

The nonce is generated once per request in middleware.ts, written to both the request headers and the response headers, and read back in a Server Component with headers(). Writing it onto the request matters: Next.js looks for a content-security-policy request header, extracts the nonce from it, and applies that nonce to the script tags it emits itself. Skip that step and the framework's own bootstrap is blocked by my own policy.

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
  const nonce = Buffer.from(crypto.randomUUID()).toString('base64');
  const dev = process.env.NODE_ENV !== 'production';

  const csp = [
    `default-src 'self'`,
    `script-src 'self' 'nonce-${nonce}' 'strict-dynamic' https: 'unsafe-inline'${dev ? " 'unsafe-eval'" : ''}`,
    `style-src 'self' 'unsafe-inline'`,
    `img-src 'self' blob: data:`,
    `connect-src 'self'`,
    `object-src 'none'`,
    `base-uri 'self'`,
    `form-action 'self'`,
    `frame-ancestors 'none'`,
    `upgrade-insecure-requests`,
  ].join('; ');

  const requestHeaders = new Headers(request.headers);
  requestHeaders.set('x-nonce', nonce);
  requestHeaders.set('content-security-policy', csp);

  const response = NextResponse.next({ request: { headers: requestHeaders } });
  response.headers.set('content-security-policy', csp);
  return response;
}

Reading it in the root layout is two lines. headers() returns a promise in Next.js 15 and later, so it must be awaited, and next/script forwards a nonce prop straight onto the emitted tag.

// app/layout.tsx
import { headers } from 'next/headers';
import Script from 'next/script';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const nonce = (await headers()).get('x-nonce') ?? undefined;

  return (
    <html lang="en">
      <body>
        {children}
        <Script src="https://plausible.io/js/script.js" nonce={nonce} strategy="afterInteractive" />
      </body>
    </html>
  );
}

Why did my static pages turn dynamic after I added CSP?

Because a nonce is only a security control while it is unpredictable, and a cached HTML response hands the same nonce to every visitor. A reused nonce is functionally identical to 'unsafe-inline': an attacker who can read one page's markup learns the token that unlocks script execution on every other copy of it. Next.js enforces the safe interpretation by treating headers() as a dynamic API — the moment my root layout calls it, every route under that layout renders per request.

That is a real bill. Marketing pages that were prerendered at build time became server-rendered on every hit, and Partial Prerendering could no longer treat the shell as static.

Strategy	Script safety	Rendering cost
Nonce + `'strict-dynamic'` everywhere	Strongest — no inline injection executes	Every matched route renders dynamically
Nonce scoped to authenticated routes, static policy elsewhere	Strong where user input is rendered	Marketing and docs pages stay static
No nonce, `script-src 'self' 'unsafe-inline'`	Weak — injected inline script still runs	Fully static

I landed on the middle row for content-heavy sites and the top row for anything behind a login. Scoping is done through the middleware matcher, and Next.js's documented example additionally excludes prefetch requests so a prefetched RSC payload does not burn a nonce it will never use.

export const config = {
  matcher: [
    {
      source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
      missing: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },
  ],
};

What breaks in development and with CSS-in-JS?

Development needs 'unsafe-eval' in script-src. React Fast Refresh and eval-based source maps both compile strings at runtime, so a production-grade policy gives me a console full of EvalError the moment I run the dev server. Gate it on process.env.NODE_ENV rather than shipping it everywhere.

style-src is where I stopped fighting. Next.js inlines critical CSS as <style> elements, and CSS-in-JS libraries inject more at runtime, frequently from code paths that never see my nonce. I keep 'unsafe-inline' in style-src deliberately: style injection is a far weaker vector than script injection, and the alternative is a policy that breaks on every dependency upgrade. If a threat model demands a style nonce, styled-components reads it from the __webpack_nonce__ global and Emotion accepts one via createCache({ nonce }).

Three more that caught me: next/image blur placeholders are data: URLs, so img-src needs data: and usually blob:; analytics beacons need their host in connect-src, not script-src, because the script is loaded but the beacon is a separate fetch; and embedded Stripe or YouTube iframes need frame-src, which does not inherit from default-src once you start listing directives explicitly.

How should I roll out CSP without breaking production?

Send the identical policy under Content-Security-Policy-Report-Only first and leave it there for a full traffic cycle — at minimum a week, so weekday and weekend behaviour both show up. The report-only header instructs the browser to evaluate the policy and report violations without blocking anything, which converts an outage into a log stream.

Collecting the reports takes one Route Handler. The legacy report-uri directive posts a single JSON object with content type application/csp-report; the newer Reporting API uses a Reporting-Endpoints response header plus a report-to directive and posts batched arrays as application/reports+json. Browsers are split across both, so I send both directives and normalise on arrival.

// app/api/csp-report/route.ts
export async function POST(request: Request) {
  const body = await request.json();
  const reports = Array.isArray(body) ? body : [body];

  for (const report of reports) {
    const blocked = report.body?.blockedURL ?? report['csp-report']?.['blocked-uri'] ?? '';
    if (blocked.startsWith('chrome-extension:') || blocked.startsWith('moz-extension:')) continue;
    console.warn('[csp]', JSON.stringify(report));
  }

  return new Response(null, { status: 204 });
}

Filter browser extensions before you alert on anything. The first day I collected reports, the overwhelming majority came from chrome-extension: and moz-extension: origins injecting scripts into pages — noise I cannot fix and should not page anyone about. What is left after that filter is the actual list of things my policy would have broken.

FAQ

Q: Does a CSP nonce protect me if I render untrusted HTML with dangerouslySetInnerHTML?
A: For script execution, yes. An injected <script> without the matching nonce will not run, and inline event handler attributes such as onerror are blocked by the same absence of 'unsafe-inline'. It does not stop the markup itself from rendering, so a CSP is not a substitute for sanitising with a library like DOMPurify.

Q: Can I use a nonce-based CSP with a statically exported Next.js site?
A: No. A nonce must be generated per request, and a static export has no request-time compute. The options are a hash-based script-src — which requires extracting the hashes of the inline bootstrap after every build, since they change per build — or serving the export behind an edge function that injects the header.

Q: Does adding 'strict-dynamic' make my policy weaker?
A: It makes it narrower. 'strict-dynamic' causes conforming browsers to ignore every host allowlist entry in script-src, so a CDN domain that was previously trusted wholesale is no longer trusted at all. Trust flows only from the nonce outward.

Q: Do I still need the X-Frame-Options header?
A: frame-ancestors supersedes it in every current browser, and where both are present frame-ancestors wins. Keeping X-Frame-Options: DENY alongside it costs nothing and covers very old clients.

Q: Should the CSP live in next.config.js or in middleware?
A: Put every static directive — frame-ancestors, object-src, base-uri, form-action — in the headers() function in next.config.js, because those responses stay cacheable. Only a policy containing a per-request nonce needs middleware, and only on the routes that require it.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Passkeys in Production: Field Notes on WebAuthn, Conditional UI, and the RP ID That Broke My Login

Ahmed Mahmoud — Thu, 13 Aug 2026 06:01:58 +0000

Headline: A passkey is a WebAuthn public-key credential held by the device's authenticator and permanently bound to one Relying Party ID (RP ID), and it replaces the password and the second factor in a single prompt. Three details caused nearly every bug I hit: the RP ID must be the origin's registrable domain or a parent of it, user.id must be an opaque handle rather than an email address, and the browser's autofill passkey chip only appears when you call navigator.credentials.get() with mediation: 'conditional'.

Key takeaways

RP ID is permanent and one-directional. A passkey registered with rp.id: 'example.com' is usable from app.example.com. A passkey registered with rp.id: 'app.example.com' is never usable from example.com. Pick the apex domain before your first user registers.
user.id is an opaque account handle, not an identifier. The WebAuthn spec caps it at 64 bytes and states it must not contain personally identifying information. An email address there is baked into the credential and cannot be rotated.
Usernameless sign-in requires a discoverable credential, requested with authenticatorSelection.residentKey: 'required'. Without it, authentication must send an allowCredentials list, which means you need the username first.
Conditional UI is a separate call. The passkey entry inside the browser's autofill dropdown needs autocomplete="username webauthn" on the input plus mediation: 'conditional'; a plain get() opens a blocking modal instead.
Do not delete the password on day one. Passkeys move the account-recovery problem, they do not remove it.

What is a passkey, and what does it actually replace?

A passkey is a WebAuthn credential whose private key never leaves the authenticator — a platform keychain such as iCloud Keychain, Google Password Manager, or Windows Hello, or a hardware security key — while the matching public key is stored on your server. Authentication is a signature: the server issues a random challenge, the authenticator signs it after a local user-verification gesture, and the server verifies the signature against the stored public key.

Because no shared secret ever crosses the network, there is nothing for a phishing site to capture. The stronger property is enforced by the browser, not by the user: the browser will only surface a credential whose RP ID matches the current origin's registrable domain, so a lookalike domain cannot get the authenticator to sign at all. That is the part TOTP never solved — a one-time code can be relayed to an attacker in real time, and a passkey signature cannot.

What a passkey replaces is the password plus the second factor, collapsed into one prompt. What it does not replace: session management, authorization, rate limiting, and account recovery.

How do I register a passkey from a Next.js App Router route handler?

Registration is two route handlers: one that generates options and stores the challenge server-side, and one that verifies the attestation and persists the credential. I use @simplewebauthn/server v13 rather than hand-rolling CBOR parsing.

// app/api/passkey/register/options/route.ts
import { generateRegistrationOptions } from '@simplewebauthn/server';

export async function POST() {
  const user = await requireSession();

  const options = await generateRegistrationOptions({
    rpName: 'Example',
    rpID: process.env.RP_ID!,   // 'example.com' — the apex, never the subdomain
    userID: user.handle,        // Uint8Array, <= 64 bytes, opaque, not the email
    userName: user.email,       // what the OS picker shows
    userDisplayName: user.name,
    attestationType: 'none',
    excludeCredentials: user.credentials.map((c) => ({
      id: c.id,
      transports: c.transports,
    })),
    authenticatorSelection: {
      residentKey: 'required',
      userVerification: 'preferred',
    },
  });

  await saveChallenge(user.id, options.challenge); // single use, short TTL
  return Response.json(options);
}

excludeCredentials is the field people skip, and skipping it lets the same authenticator enrol twice — the user then sees two identical entries in their picker and cannot tell them apart. attestationType: 'none' is the right default for a consumer app: requesting attestation gives you an authenticator provenance statement you almost certainly have no policy for.

I use userVerification: 'preferred' rather than 'required'. The 'required' value rejects authenticators that cannot perform a local biometric or PIN check, which quietly excludes some security keys and older Android configurations. 'preferred' still reports whether verification happened via the userVerified flag, so you can gate sensitive actions on it instead of gating registration.

The browser half is four lines. Note the v13 signature — startRegistration takes an options object, not a positional argument:

import { startRegistration } from '@simplewebauthn/browser';

const optionsJSON = await fetch('/api/passkey/register/options', { method: 'POST' })
  .then((r) => r.json());

const attestation = await startRegistration({ optionsJSON });

await fetch('/api/passkey/register/verify', {
  method: 'POST',
  body: JSON.stringify(attestation),
});

I use route handlers rather than Server Actions here. navigator.credentials only runs in the browser inside a user gesture and in a secure context, so the flow is client-driven either way.

Why does my passkey work on one subdomain and not another?

Because the browser matches the RP ID against the origin's registrable domain, and the match is one-directional: the RP ID may be the origin's domain or any parent domain of it, never a child. An origin of https://app.example.com may claim an rp.id of app.example.com or example.com. An origin of https://example.com may not claim app.example.com.

This is the mistake that is expensive to fix, because RP ID is written into the credential at registration and cannot be migrated. If you register users on app.example.com and later add a second product on dash.example.com, every existing passkey is stranded on the first subdomain.

For genuinely different sites — a per-country domain, or a separate brand — the mechanism is Related Origin Requests. The RP serves a JSON document at https://<rpID>/.well-known/webauthn with Content-Type: application/json:

{
  "origins": [
    "https://example.co.uk",
    "https://example.de",
    "https://example.app"
  ]
}

Related Origin Requests shipped in Chrome 128 and Safari 18. Browsers cap how many distinct registrable-domain labels they will process from that list — Chrome stops at five — so it is a mechanism for a handful of sibling domains, not a wildcard.

One local-development note: localhost is a secure context and works over plain HTTP, but any other dev hostname must be served over HTTPS, and the RP ID has to equal that hostname. A passkey registered against a local HTTPS dev hostname will never authenticate against production.

How do I make the passkey autofill prompt appear?

Conditional mediation is what puts a passkey inside the browser's autofill dropdown instead of a modal dialog. It needs three things together: a discoverable credential, an input marked autocomplete="username webauthn", and a get() call with mediation: 'conditional'.

import { startAuthentication } from '@simplewebauthn/browser';

useEffect(() => {
  const controller = new AbortController();

  (async () => {
    if (!(await PublicKeyCredential.isConditionalMediationAvailable?.())) return;

    const optionsJSON = await fetch('/api/passkey/auth/options').then((r) => r.json());

    try {
      const assertion = await startAuthentication({ optionsJSON, useBrowserAutofill: true });
      await submitAssertion(assertion);
    } catch (err) {
      if ((err as Error).name !== 'AbortError') throw err;
    }
  })();

  return () => controller.abort();
}, []);

Two traps live in that snippet. First, a conditional get() returns a promise that stays pending indefinitely — it resolves only when the user picks a passkey from the dropdown. Start it once when the sign-in form mounts and abort it on unmount; firing a second get() while one is outstanding throws instead of replacing it.

Second, conditional mediation only offers discoverable credentials and requires an empty allowCredentials. If your authentication options endpoint helpfully fills allowCredentials from a known username, the autofill chip silently never appears and you will blame the browser.

What must the server verify on every assertion?

The server must verify the challenge, the origin, the RP ID hash, the user-presence flag, and the signature — a client that reports success proves nothing, since the entire assertion arrives as attacker-controllable JSON.

import { verifyAuthenticationResponse } from '@simplewebauthn/server';

const verification = await verifyAuthenticationResponse({
  response: assertion,
  expectedChallenge: storedChallenge,
  expectedOrigin: 'https://example.com',
  expectedRPID: 'example.com',
  credential: {
    id: stored.id,
    publicKey: stored.publicKey,
    counter: stored.counter,
    transports: stored.transports,
  },
  requireUserVerification: false,
});

await deleteChallenge(storedChallenge); // delete on failure too
if (verification.verified) {
  await updateCounter(stored.id, verification.authenticationInfo.newCounter);
}

Delete the challenge whether verification succeeded or failed. A challenge that survives a failed attempt is a replay window, and it is the single most common flaw I find when reviewing a hand-written WebAuthn implementation.

The signature counter deserves a warning. It exists for clone detection, but most synced platform authenticators always report 0, so a naive rule of "reject unless the new counter is greater than the stored one" locks out every Apple and Google passkey user. Enforce monotonic increase only when the stored counter and the new counter are both non-zero.

Persist credentialBackedUp and credentialDeviceType from the registration result. Those flags tell you whether a credential is synced across a user's devices or bound to one piece of hardware.

Passkeys vs password and TOTP vs magic links — which do I ship?

Factor	Passkey (WebAuthn)	Password + TOTP	Magic link
Phishing resistance	Enforced by the browser via RP ID matching	None — codes can be relayed in real time	None — links are forwardable
Server stores a secret	No, only a public key	Yes, hash plus TOTP seed	No, but a live token sits in the mailbox
Sign-in steps	One gesture	Two fields plus an app switch	App switch to email, then back
Works on a borrowed device	Yes, via cross-device hybrid transport	Yes	Yes
Main failure mode	Recovery when every synced device is lost	Real-time phishing and seed loss	Email deliverability and mailbox compromise

My default is passkey-first with a password kept as recovery, and TOTP retained only for accounts that already had it. Magic links stay in the stack for onboarding, not for repeat sign-in, because they make routine login depend on email latency.

What breaks after a user deletes a passkey?

Nothing breaks on the server, and everything breaks in the operating system's picker: the platform passkey manager keeps offering a credential you deleted server-side, the user selects it, and they get an error they have no way to interpret. The WebAuthn Signal API exists to close that gap.

await PublicKeyCredential.signalAllAcceptedCredentials?.({
  rpId: 'example.com',
  userId: base64urlUserHandle,
  allAcceptedCredentialIds: remaining.map((c) => c.id),
});

There are three methods and they map to three events. signalAllAcceptedCredentials() runs after a user deletes a credential or right after a successful sign-in, and prunes stale entries. signalUnknownCredential() runs when an assertion arrives for a credential ID you have no record of, and removes that single orphan. signalCurrentUserDetails() runs after a user changes their name or email. The Signal API landed in Chromium 132, so optional-chain every call and treat it as progressive enhancement.

One server-side rule is worth enforcing regardless of browser support: never let a user delete their last credential unless another way in exists.

FAQ

Q: Can I set the RP ID to a subdomain and change it later?
A: No. RP ID is written into the credential at registration and cannot be migrated. A passkey registered with rp.id: 'app.example.com' will never work on example.com.

Q: Why doesn't the passkey appear in my browser's autofill dropdown?
A: Three causes, in order of likelihood: the input is missing autocomplete="username webauthn", the get() call is missing mediation: 'conditional', or the authentication options include a non-empty allowCredentials.

Q: What should I put in user.id?
A: A random opaque handle of at most 64 bytes — a UUID or 16 random bytes stored alongside the account row. The WebAuthn spec states user.id must not contain personally identifying information.

Q: Do I still need passwords after shipping passkeys?
A: Keep one recovery path until passkey recovery is genuinely solved for your users. A passkey synced to a single vendor's cloud is lost when the user loses access to that account.

Q: Should I reject a sign-in when the signature counter did not increase?
A: Only when both the stored counter and the new counter are non-zero. Most synced platform authenticators always report 0, so a strict monotonic check locks out the majority of real passkey users.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Modern CSS Deleted My Layout JavaScript: Field Notes on Container Queries, :has(), and Subgrid

Ahmed Mahmoud — Tue, 11 Aug 2026 06:01:52 +0000

Headline: Four CSS features — container queries, :has(), subgrid, and cascade layers — let me delete most of the JavaScript I used to write for layout and conditional styling. Container queries size a component against its container instead of the viewport, :has() styles a parent based on its children, subgrid makes a nested grid adopt its parent's track lines, and @layer makes override order explicit instead of a specificity race.

Key takeaways

container-type: inline-size on a wrapper plus @container (min-width: 30rem) styles a component by the width of its container, so one card works in a sidebar and in a full-width grid with no viewport media query.
:has() is the CSS parent selector: .card:has(> img) matches a card that contains an image, and it re-evaluates live as the DOM and form state change.
grid-template-rows: subgrid makes a nested grid adopt its parent's row lines, which is how sibling cards align their titles and footers without fixed heights.
Cascade layers — @layer reset, base, components, utilities — decide override order by layer rather than selector specificity, so a one-class utility in a later layer beats a three-class component selector.
Container queries, :has(), subgrid, and @layer all ship in Chrome, Safari, and Firefox. CSS anchor positioning and calc-size() are still Chromium-only, so I use them only as progressive enhancement.

When should I use container queries instead of media queries?

Use a container query whenever the thing you are styling can appear at more than one column width; keep media queries for page-level concerns. A container query is a CSS rule written with @container that resolves against the size of the nearest ancestor which declares container-type — not against the viewport.

.card-grid { container-type: inline-size; container-name: cards; }

.card { display: grid; gap: 0.5rem; }

@container cards (min-width: 30rem) {
  .card { grid-template-columns: 8rem 1fr; }
  .card__title { font-size: clamp(1rem, 4cqi, 1.5rem); }
}

This deleted a component I had shipped in three codebases: a wrapper that used ResizeObserver to measure its own width and toggle a .is-narrow class. That wrapper is always one frame late, because it reads layout after the browser has already painted — the component renders wide, then snaps narrow. A container query is resolved during layout, so there is no intermediate frame to see.

container-type: inline-size means only the inline axis is queryable and the element gets inline-axis size containment. The practical consequence: a container declared that way can no longer be sized by the width of its own contents, which is what breaks shrink-to-fit elements when people first adopt it. Container query units follow the same axis — 1cqi is one percent of the container's inline size, which is what makes the clamp() above scale type per card rather than per viewport.

The gotcha that cost me the most time: an element cannot query itself. If container-type lives on .card, a @container rule targeting .card will never match. The container must be an ancestor of everything the query styles.

What does the :has() selector actually replace?

:has() replaces the JavaScript that added a class to a parent because of something inside it. It is a relational pseudo-class: A:has(B) selects element A when a descendant (or, with a combinator, a child or sibling) matching B exists.

/* the wrapper reacts to the input inside it */
.field:has(input:user-invalid) { --field-border: #c0392b; }

/* layout changes only when the card really has a media child */
.card:has(> img) { grid-template-rows: auto 1fr; }

/* page-level scroll lock with no event listener */
body:has(dialog[open]) { overflow: hidden; }

That last rule removed a scroll-lock utility I had maintained for years — the one that stored window.scrollY, set position: fixed on the body, and restored it on close. :has() is live: it re-evaluates as [open], :checked, and :user-invalid change, so form and dialog state can drive layout with no listener at all.

Two rules worth internalizing. First, :has() takes the specificity of its most specific argument, so .card:has(#hero) carries an ID's weight — wrap the argument in :where() when you want it to stay cheap. Second, :has() cannot be nested inside another :has() and cannot contain pseudo-elements. On performance, the blanket ":has() is slow" advice is dated; the engines optimize it, and I keep the subject narrow — .card:has(> img), never *:has(img) — rather than avoiding it.

When do I need subgrid instead of a nested grid?

Use subgrid when children of separate grid items must line up with each other. A nested display: grid creates its own independent tracks sized by its own content, so three cards with different title lengths produce three different internal layouts. grid-template-rows: subgrid makes the child adopt the parent's row lines instead.

.cards { display: grid; grid-template-columns: repeat(3, 1fr); gap: 1rem; }

.card {
  display: grid;
  grid-row: span 3;              /* claim three parent rows */
  grid-template-rows: subgrid;   /* and adopt their lines */
}

The two lines work together: grid-row: span 3 makes the card occupy three rows of the parent grid, and subgrid tells the card to use those three row lines for its own children. Every card's title sits on the same line, every footer sits on the same line, and no card needs a fixed height. The alternatives I used before were all worse — hard-coded heights, -webkit-line-clamp to force titles to one length, or a JavaScript pass that measured the tallest card and wrote a pixel height onto the rest.

subgrid is per-axis: you can subgrid rows while defining your own columns, or the reverse. Gaps are inherited from the parent grid unless the subgrid explicitly sets its own.

How do cascade layers and @scope stop specificity wars?

Cascade layers make override order an explicit declaration instead of an emergent property of your selectors. Rules in a later layer beat rules in an earlier layer regardless of specificity.

@layer reset, base, components, utilities;
@import url("vendor.css") layer(vendor);

@layer components {
  .nav .nav__link.is-active { color: var(--brand); } /* specificity 0,3,0 */
}

@layer utilities {
  .text-muted { color: var(--muted); }               /* 0,1,0 — still wins */
}

The single most important rule about layers is the one that bites people: unlayered CSS beats every layer. One third-party stylesheet loaded outside a layer outranks your entire carefully ordered cascade, which is why the @import ... layer(vendor) line above matters. The second trap is that !important reverses layer order, so an !important declaration in an early layer beats a normal declaration in a later one.

@scope is the companion feature: @scope (.card) to (.card__content) applies rules only between a root and a lower boundary, which is real component isolation without BEM-length class names. It landed later than the other four features and Firefox was the last engine to ship it, so check current Baseline status before making it load-bearing.

Which CSS feature replaces which JavaScript?

JavaScript I deleted	CSS that replaced it	In every engine since
`ResizeObserver` + class toggle for component breakpoints	`container-type` + `@container`	Firefox 110 (Feb 2023)
Parent class toggles driven by child or form state	`:has()`	Firefox 121 (Dec 2023)
Measuring the tallest card and writing pixel heights	`grid-template-rows: subgrid`	Chrome 117 (Sept 2023)
Specificity hacks, `!important` chains, injection-order tricks	`@layer`	Safari 15.4 / Chrome 99 (2022)
Scroll-lock utility that saved and restored scroll position	`body:has(dialog[open]) { overflow: hidden }`	Firefox 121 (Dec 2023)

What is still not safe to ship in 2026?

CSS anchor positioning and keyword size interpolation are still Chromium-only, so I ship them only where losing them degrades cleanly. Anchor positioning — anchor-name, position-anchor, position-area — tethers a popover to its trigger without a JavaScript positioning library, and it has been in Chrome since version 125 without matching Safari and Firefox releases. interpolate-size: allow-keywords plus calc-size() finally animates height: auto, and it is in the same Chromium-only bucket.

@supports (anchor-name: --trigger) {
  .popover { position-anchor: --trigger; position-area: block-end span-inline-end; }
}

For expanding panels I use the grid-fraction trick as the everywhere-baseline, and treat calc-size() as a bonus rather than the mechanism:

.accordion { display: grid; grid-template-rows: 0fr; transition: grid-template-rows 200ms ease; }
.accordion[data-open] { grid-template-rows: 1fr; }
.accordion > .accordion__inner { overflow: hidden; }

The rule I follow: if a feature changes information architecture — whether the user can read the content or complete the task — it has to be supported in all three engines. If it only changes polish, I gate it behind @supports and let older engines get the plain version. That line has kept me from shipping a popover that lands in the wrong corner on Safari.

FAQ

Q: Do container queries replace media queries entirely?
A: No. Container queries size a component against its container; media queries still own page-level and environment concerns the container cannot know about — overall page layout, prefers-reduced-motion, prefers-color-scheme, and print styles.

Q: Is the :has() selector slow?
A: Treating :has() as automatically expensive is outdated advice; modern engines optimize it. Keep the subject narrow — prefer .card:has(> img) over *:has(img) — and profile style recalculation in DevTools if a specific page feels slow.

Q: Why doesn't my container query match anything?
A: Almost always because the element is trying to query itself. @container resolves against an ancestor that declares container-type, never against the element the rule styles. Move container-type onto a wrapper.

Q: What is the difference between subgrid and a nested grid?
A: A nested display: grid creates independent tracks sized by its own content. grid-template-rows: subgrid adopts the parent's track lines, so siblings align with each other instead of each sizing itself.

Q: Do cascade layers work with Tailwind CSS or CSS-in-JS?
A: Yes — Tailwind CSS v4 organizes its own output into @layer theme, base, components, utilities. The rule to remember is that unlayered CSS beats every layer, so pull third-party stylesheets into a named layer with @import url("x.css") layer(vendor) if you need to override them.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Background Jobs on Vercel in 2026: Field Notes on waitUntil, Queues, Workflow, and Cron

Ahmed Mahmoud — Mon, 10 Aug 2026 06:02:32 +0000

Headline: Serverless did not kill background work — it killed background work that outlives the response without telling the runtime. I now route every deferred task on Vercel through one of four primitives: waitUntil() for short best-effort side effects, Vercel Cron for clock-triggered sweeps, Vercel Queues for work that must survive a failing consumer, and Vercel Workflow for multi-step jobs that must survive a redeploy an hour later.

Key takeaways

waitUntil() from the @vercel/functions package extends a Vercel Function past its response so a pending promise can finish, but it is best-effort: no retries, no durability, and it dies with the invocation.
Vercel Queues is a durable event-streaming service with at-least-once delivery, which means every consumer must be idempotent — some message will eventually be delivered twice.
Vercel Workflow provides durable execution: an async function marked with the "use workflow" directive checkpoints each step, so a crash resumes at the last completed step instead of restarting from the top.
Vercel Cron is correct only for time-triggered work. A job triggered by a user action belongs in a queue, not on a schedule.
Vercel Functions default to a 300-second max duration on all plans in 2026, so a surprising amount of "this obviously needs a queue" work now fits inside a single invocation.

Why does background work disappear after I return a response?

Background work disappears because an unawaited promise has no owner. When a Vercel Function returns a Response, the platform is free to freeze or reclaim that instance immediately. Any promise still in flight is not tracked by anything, so it is cancelled at an arbitrary point.

The failure mode that cost me the most debugging time is not that the work never runs — it is that the work runs sometimes. Fluid Compute, the default compute model on Vercel, reuses a single function instance across concurrent requests instead of spinning up one instance per request. A dangling promise therefore often completes, because another request keeps the instance warm. Under low traffic it silently vanishes. Non-deterministic loss is far harder to notice in production than total loss.

// Wrong: this promise is unowned and may be killed mid-flight.
export async function POST(req: Request) {
  const body = await req.json();
  logToAnalytics(body); // no await, no waitUntil — dangling
  return Response.json({ ok: true });
}

When is waitUntil() enough?

waitUntil() is enough when losing the work occasionally is acceptable and the work finishes in single-digit seconds. The function waitUntil(promise) is exported from @vercel/functions and registers a promise with the runtime, so the invocation stays alive until that promise settles even though the response has already been sent.

import { waitUntil } from '@vercel/functions';

export async function POST(req: Request) {
  const body = await req.json();
  waitUntil(logToAnalytics(body)); // owned by the runtime now
  return Response.json({ ok: true });
}

Two honest limits I hit. First, waitUntil() has no retry semantics: if the promise rejects, nothing re-runs it, and the rejection surfaces only in runtime logs. Second, the deferred work still counts against the function's max duration and against Active CPU billing — waitUntil() defers the work relative to the response, not relative to the invocation. I use it for analytics events, cache warming, and log shipping. I do not use it for anything a user would file a support ticket about.

What does Vercel Queues actually solve?

Vercel Queues solves the case where the work must eventually happen even if the first attempt fails. Vercel Queues is a durable event-streaming system built on Fluid Compute, currently in public beta, that provides at-least-once delivery: a producer writes a message to a topic and returns immediately, and a separate consumer function processes that message with retries on failure.

The architectural win is decoupling latency budgets. Before a queue, the p95 of my API route was the p95 of the slowest third party it called — an email provider, a PDF renderer, a webhook fan-out. After a queue, the route's p95 is the cost of one durable write, and the third party's bad afternoon becomes a retry curve on the consumer instead of a timeout on the user's request.

The tax is idempotency, and it is not optional. At-least-once delivery means duplicate delivery is a certainty over a long enough window, not an edge case. My default pattern is a dedupe table with a unique constraint on the message id, written before the side effect runs:

// Consumer: insert-then-act. The unique index is the guard.
const inserted = await db
  .insert(processedMessages)
  .values({ messageId })
  .onConflictDoNothing()
  .returning({ id: processedMessages.id });

if (inserted.length === 0) return; // already handled, ack and move on
await sendReceiptEmail(payload);

The Queues API surface is still moving while it is in public beta, so treat the shape above as the pattern rather than a frozen signature and check the current docs before wiring it.

When should I use Vercel Workflow instead of a queue?

Use Vercel Workflow when the retry unit is a single step inside a longer job, not the whole message. Vercel Workflow is a durable execution framework: you mark an async function with the "use workflow" directive and its individual steps with "use step", and the runtime checkpoints each completed step's result so an interruption resumes from the last checkpoint instead of re-running everything.

That distinction is the whole decision for me. A queue message is atomic — if the handler throws on line 40, the entire message is redelivered and lines 1 through 39 run again. That is fine when those lines are pure. It is not fine when line 12 charged a card and line 40 failed to render a PDF.

'use workflow';

export async function onboardCustomer(customerId: string) {
  const account = await createAccount(customerId); // step 1, checkpointed
  await provisionResources(account.id);            // step 2, checkpointed
  await sleep('24 hours');                         // survives a redeploy
  await sendDayTwoEmail(account.id);               // step 4
}

The other thing Workflow buys is time. A durable workflow can sleep for hours or days and wait for an external event, because its state lives outside any single function invocation. A queue consumer cannot — it is still a function bounded by the 300-second max duration.

How do I pick between cron, waitUntil, Queues, and Workflow?

Primitive	Trigger	Durable?	Retries	Use it for
`waitUntil()`	Request	No	None	Analytics pings, cache warming, log shipping
Vercel Cron	Clock	Yes (the schedule)	Next tick	Nightly sweeps, expiry, report generation
Vercel Queues	Producer message	Yes	At-least-once redelivery	Email sends, webhook fan-out, image processing
Vercel Workflow	Explicit invocation	Yes (per step)	Per step, resumes at checkpoint	Onboarding sequences, multi-provider orchestration, long jobs

Vercel Cron is configured declaratively. In vercel.ts, the recommended TypeScript project configuration that replaces vercel.json, it is a crons array of path-and-schedule pairs:

import { type VercelConfig } from '@vercel/config/v1';

export const config: VercelConfig = {
  crons: [{ path: '/api/cleanup', schedule: '0 3 * * *' }],
};

What actually broke for me?

Three things broke, all of them in the gap between "the primitive works" and "my handler respects the primitive's contract."

A duplicate side effect from at-least-once delivery. A consumer that sent a confirmation email had no dedupe guard. A transient failure after the send but before the ack caused redelivery, and the same user got the same email twice. The fix was the insert-then-act pattern above: write the message id under a unique constraint first, and treat a conflict as "already done."

A long job parked in waitUntil(). I put a multi-minute document job behind waitUntil() because it was the smallest diff. It worked in staging and lost work in production during deploys, because a rolling deploy retires the old instance and the in-flight promise goes with it. That job belonged in a queue from day one; waitUntil() was the wrong contract, not a tuning problem.

Overlapping cron runs. A nightly sweep that normally took a few minutes grew past its own interval, and two invocations ran concurrently over the same rows. Vercel Cron does not serialize overlapping executions for you. I added a Postgres advisory lock at the top of the handler and made the second run exit immediately instead of contending.

The pattern behind all three: pick the primitive by the failure you can tolerate, not by the code you can write fastest. Best-effort work gets waitUntil(). Must-happen work gets a queue and an idempotency key. Must-happen-in-order work gets a workflow. Clock work gets cron and a lock.

FAQ

Q: Does waitUntil() let a Vercel Function run longer than its max duration?

A: No. waitUntil() keeps the invocation alive after the response is sent, but the invocation is still bounded by the function's max duration, which defaults to 300 seconds on all plans in 2026. It defers work relative to the response, not relative to the invocation.

Q: Do I still need a third-party queue like SQS, BullMQ, or Inngest on Vercel?

A: Not for the common cases. Vercel Queues covers durable at-least-once messaging and Vercel Workflow covers durable multi-step execution, both natively on Fluid Compute. Reach for an external system when you need semantics they do not offer, such as strict FIFO ordering per key or exactly-once processing enforced by the broker.

Q: What does at-least-once delivery mean in practice for my consumer code?

A: It means your consumer will receive the same message more than once at some point, so every side effect must be safe to repeat. Guard non-idempotent effects — charges, emails, external POSTs — with a dedupe record keyed by the message id and written under a unique constraint before the effect runs.

Q: Can Vercel Cron trigger a queue producer instead of doing the work itself?

A: Yes, and that is usually the better design for large sweeps. Have the cron route enumerate the work and publish one message per item, then let queue consumers process items in parallel with independent retries. The cron invocation stays short and a single bad item cannot fail the entire sweep.

Q: Does Fluid Compute change how I should write background work?

A: Yes, in one specific way: Fluid Compute reuses instances across concurrent requests, so dangling promises often complete by accident. That makes unowned background work look correct in testing and fail intermittently in production. Always register deferred work explicitly with waitUntil() or hand it to a queue.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Running AI-Generated Code Safely: Field Notes on Vercel Sandbox

Ahmed Mahmoud — Sun, 09 Aug 2026 06:01:49 +0000

Headline: Vercel Sandbox runs untrusted code — including code a model just wrote — inside an isolated, ephemeral microVM instead of inside my application's own process. I moved every "let the model write and execute a snippet" feature off ad-hoc child_process calls and onto Sandbox: one sandbox per execution, a hard timeout, an isolated filesystem, and no path back into my app's environment variables.

Key takeaways

Vercel Sandbox (@vercel/sandbox) runs code inside an isolated Firecracker microVM, not a container in your app's own process — a compromised sandbox can't read your Vercel Function's memory or environment variables.
A sandbox is ephemeral: you create one, run commands, read the output, then stop it. There is no persistent state between runs unless you explicitly persist it yourself.
sandbox.runCommand() executes a process inside the sandbox and returns stdout, stderr, and an exit code; sandbox.domain(port) exposes a running server on a public URL for a live preview.
The two cases I actually reach for it: an LLM-authored script that needs to run and return a result, and a user-facing "run this code" feature like an AI-generated component preview.
Sandbox is not the tool for trusted, first-party build or CI logic — that belongs in the deploy pipeline. Sandbox is for code you did not write and do not trust.

Why can't I just run AI-generated code inside my own Vercel Function?

A Vercel Function shares its process, filesystem, and environment with the rest of my app. Running an untrusted string as code in that same process — through child_process.exec or, worse, eval — puts every secret the function can see, API keys and database URLs included, inside the blast radius of whatever the model wrote. A generated snippet can read environment variables, open an outbound connection to exfiltrate them, or just spin the CPU and starve every other request the function is serving at the same time.

I treat any code I did not author myself as untrusted by default, and that includes code a model generates on request. Untrusted code needs its own compute boundary: its own filesystem, its own network context, and resource limits I can enforce and then throw away.

What is Vercel Sandbox actually running under the hood?

Vercel Sandbox provisions a Firecracker microVM for every sandbox — the same virtualization technology AWS Lambda uses to isolate tenants from each other, not a namespace or cgroup container. The practical difference is the escape hatch: breaking out of a container means crossing a kernel-namespace boundary inside a kernel the workload shares with its neighbors, while breaking out of a microVM means finding a hypervisor-level exploit against a kernel nothing else is using. Creating one is a single call:

import { Sandbox } from '@vercel/sandbox';

const sandbox = await Sandbox.create({
  runtime: 'node22',
  timeout: 60_000, // ms — hard ceiling before Vercel force-stops it
  resources: { vcpus: 2 },
});

runtime picks the base image, timeout is a hard ceiling I set per use case, and resources.vcpus controls how much CPU the microVM gets. I set the shortest timeout a feature can tolerate rather than reusing one default everywhere — a code-eval playground gets seconds, a batch-style job gets minutes.

How do I actually execute an LLM-generated snippet inside a sandbox?

Write the generated code to a file inside the sandbox, then run it as a subprocess — never pass model output through eval or the Function constructor inside your own function, sandboxed or not.

await sandbox.writeFiles([
  { path: 'snippet.js', content: Buffer.from(generatedCode) },
]);

const result = await sandbox.runCommand({
  cmd: 'node',
  args: ['snippet.js'],
});

const stdout = await result.stdout();
const exitCode = result.exitCode;

runCommand() gives me back exactly what a subprocess call would: stdout, stderr, and an exit code. The difference is where that process actually ran — inside a disposable microVM instead of next to my app's live secrets.

Does a Vercel Sandbox keep state between runs?

No. Sandboxes are ephemeral by design — each Sandbox.create() call provisions a fresh microVM with a clean filesystem, and calling sandbox.stop(), or hitting the timeout, tears it down completely, including anything written to disk. If a feature needs to remember something across runs — a multi-turn code-interpreter chat, for instance — that state has to live outside the sandbox: write results to a database or blob store from inside the sandboxed process, or persist a small manifest the caller rehydrates into a new sandbox next time. I treat each sandbox as disposable compute, never as a place to store anything.

Can I stream a sandbox's output back to the browser while it's running?

Yes. runCommand() accepts a detached option, which returns a handle you can read from as output is produced instead of waiting for the whole command to finish — the same pattern I use for streaming a model's token output, just piping a sandbox's stdout instead.

const result = await sandbox.runCommand({
  cmd: 'node',
  args: ['agent.js'],
  detached: true,
});

for await (const chunk of result.stdout) {
  controller.enqueue(chunk); // forward to a ReadableStream response
}

None of this needs the edge runtime — streaming a sandbox's output back through a Vercel Function works on the default Node.js runtime with no extra config, the same as streaming an LLM response.

What's the actual difference between Sandbox and child_process in a Function?

	child_process in a Function	Vercel Sandbox
Isolation boundary	Same process and container as your app	Separate Firecracker microVM
Filesystem	Shares the function's filesystem	Isolated, wiped on stop
Network egress	Shares the function's network context	Its own network namespace
Blast radius of a crash or hang	Can take the whole function down	Contained to the sandbox
Good for	Trusted, first-party subprocess calls you wrote yourself	Untrusted, LLM-authored, or user-submitted code

When should I not reach for Vercel Sandbox?

Not for code I trust and wrote myself — provisioning a microVM adds real latency compared to a subprocess in an already-warm function, and there's no isolation benefit to pay that cost for. Not for a full CI or build pipeline either; that belongs in the platform's own build step, not a runtime sandbox. I reach for Sandbox specifically when the code executing is either model-generated or submitted by a user I don't trust, and the feature genuinely needs to run something — a subprocess, a filesystem, an arbitrary language — rather than just call an LLM API and return text.

FAQ

Q: Is Vercel Sandbox the same thing as a Vercel Function?
A: No. A Vercel Function runs your own deployed code with your app's environment and network context. A Sandbox is a separate, ephemeral microVM you provision at runtime specifically to execute code you don't trust, with its own filesystem and no access to your function's secrets.

Q: What isolation technology does Vercel Sandbox use?
A: Firecracker microVMs — each sandbox gets its own kernel, not just a container namespace, the same class of isolation AWS Lambda uses between tenants.

Q: Can a sandbox access my environment variables or database?
A: Not unless you explicitly pass them in. A sandbox starts with a clean environment, and I only ever inject scoped, short-lived credentials into a sandbox that's about to run untrusted code.

Q: How long can a sandbox run?
A: You set a timeout when you create it, and the sandbox is force-stopped once that timeout hits. I set the shortest timeout the feature can tolerate — seconds for a "run this snippet" playground, longer for batch-style jobs.

Q: Should I use Sandbox to run my own build scripts?
A: No — that's what the deploy pipeline is for. Sandbox earns its cost, microVM provisioning latency and no persistent state, specifically for code you did not write: LLM output, user-submitted snippets, anything where the isolation boundary is the point.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.