DEV Community: Ahmed Mahmoud

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.

Node.js Has a Test Runner Now: Field Notes on Dropping Jest for Scripts and Libraries

Ahmed Mahmoud — Sat, 08 Aug 2026 06:32:54 +0000

Headline: Node.js ships a built-in test runner — node --test executes node:test files with no Jest, no Vitest, and no config file — and paired with type stripping it runs .ts tests with zero build. I moved my scripts and small libraries onto it: node:test for structure, node:assert/strict for assertions, the built-in mock for spies and fake timers, and --experimental-test-coverage for coverage. I kept Vitest for anything that touches the DOM or renders React.

Key takeaways

The Node.js test runner lives in the built-in node:test module and runs with node --test; it needs no dependency, no config file, and has been stable since Node.js 20.
Assertions come from the built-in node:assert module — import node:assert/strict so assert.equal uses strict (===) comparison.
The mock object from node:test gives you mock.fn(), mock.method(), and mock.timers without a separate mocking library; module mocking via mock.module() is still experimental.
Combined with type stripping, node --test "src/**/*.test.ts" runs TypeScript tests with no build step on Node.js 22.18+ and Node.js 24.
Coverage is available behind --experimental-test-coverage, and output format is chosen with --test-reporter (spec, tap, dot, junit, lcov).

Can Node.js run tests without Jest or Vitest?

Yes — Node.js has a built-in test runner, and it needs zero dependencies. The runner is the node:test core module, invoked with node --test; it landed experimentally in Node.js 18 and became stable in Node.js 20. It auto-discovers test files, runs each in its own child process for isolation, and reports in a TAP-based format.

// math.test.ts
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { add } from './math.ts';

test('add sums two numbers', () => {
  assert.equal(add(2, 3), 5);
});

Run it with node --test. No jest.config.js, no transform, no ts-jest.

How do I structure tests with node:test?

node:test exports test, plus describe/it and the hooks before, after, beforeEach, afterEach.

import { describe, it, beforeEach } from 'node:test';
import assert from 'node:assert/strict';

describe('Cart', () => {
  let cart: Cart;
  beforeEach(() => { cart = new Cart(); });

  it('starts empty', () => assert.equal(cart.total(), 0));
  it('sums item prices', () => {
    cart.add({ price: 10 });
    cart.add({ price: 5 });
    assert.equal(cart.total(), 15);
  });
});

Focus one test with { only: true } and --test-only, or filter with --test-name-pattern.

How do I mock functions and timers?

Mocking is built in through the mock object — no jest.fn to install.

import { test, mock } from 'node:test';
import assert from 'node:assert/strict';

test('notifies the customer once', () => {
  const notify = mock.fn();
  placeOrder({ items: [{ price: 10 }], notify });
  assert.equal(notify.mock.callCount(), 1);
});

mock.method(obj, 'name') spies on a real method, and mock.timers.enable({ apis: ['setTimeout'] }) plus mock.timers.tick(1000) gives deterministic fake timers. Full module mocking via mock.module() is still experimental, so I favor dependency injection instead.

Can I run TypeScript tests without a build step?

Yes, on Node.js 22.18+ and Node.js 24, because Node.js strips type annotations at load time.

node --test "src/**/*.test.ts"

Relative imports need the explicit .ts extension, and Node.js never type-checks — run tsc --noEmit as a separate CI gate. This removed ts-jest and the Vitest transform from every script and library repo I own.

How do I get coverage and CI reports?

Watch mode is node --test --watch. Coverage is a flag: node --test --experimental-test-coverage prints a per-file table. Reporters are chosen with --test-reporter, and you can emit several at once:

node --test \
  --test-reporter=spec \
  --test-reporter=junit --test-reporter-destination=junit.xml \
  --experimental-test-coverage

Thresholds like --test-coverage-lines=80 (Node.js 22+) fail the run below a percentage — enough to gate a PR without a coverage service.

When should I keep Vitest or Jest?

Keep them whenever a test needs a browser-like environment or a build transform the runtime lacks.

Need	Node.js test runner	Vitest / Jest
Dependencies	Zero (built in)	A framework + transform
DOM / React	No jsdom, no JSX	jsdom/happy-dom + JSX
TypeScript	Native via type stripping	esbuild/SWC transform
Snapshots	Basic, recent	Mature
Best for	Scripts, libraries, backend	Frontend, components, big suites

Backend and library code gets the built-in runner; anything that renders a component stays on Vitest.

FAQ

Q: Is the Node.js test runner production-ready?
A: Yes — the runner and node:test API are stable since Node.js 20. Only module mocking and coverage remain behind experimental flags.

Q: Do I need a config file?
A: No. node --test auto-discovers test files and takes options as CLI flags.

Q: Which assertion library does it use?
A: The built-in node:assert; import node:assert/strict for strict equality. Third-party assertion libraries still work.

Q: Can it test React components?
A: Not well — no DOM, no JSX transform. Use Vitest/Jest with jsdom for components.

Q: How does it mock ES modules?
A: Via mock.module(), still experimental. I prefer dependency injection for stable code.

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

Getting Typed JSON Out of LLMs: Field Notes on generateObject

Ahmed Mahmoud — Fri, 07 Aug 2026 06:01:52 +0000

Headline: The Vercel AI SDK's generateObject is the reliable way to get typed, schema-validated JSON out of a language model: I pass a Zod schema, the SDK constrains the model and validates the result, and I get a typed object instead of hand-parsing a string that is JSON most of the time. Four things carried the weight for me — generateObject for one-shot extraction, streamObject for progressive UI, the object/array/enum/no-schema output modes, and treating NoObjectGeneratedError as a first-class code path.

Key takeaways

generateObject({ model, schema, prompt }) returns a typed object validated against a Zod (or JSON) schema; on a schema mismatch it throws instead of handing you bad data.
streamObject streams a partial object through partialObjectStream so a form or table fills in field-by-field before the model finishes.
The AI SDK has four output modes: object (default), array (streams elements via elementStream), enum (single-label classification), and no-schema (freeform JSON).
Use generateObject to extract data and tool calling to take actions; experimental_output combines a tool-calling loop with a final typed object.
When a model returns invalid JSON the SDK throws NoObjectGeneratedError, which carries the raw text and usage; experimental_repairText and tighter schema descriptions recover most of those.

What does generateObject actually do?

generateObject is a Vercel AI SDK function that forces a language model to return JSON matching a schema I define, and validates the response before my code ever sees it. I pass a model, a Zod schema, and a prompt; I get back a typed object whose shape TypeScript already knows.

import { generateObject } from 'ai';
import { z } from 'zod';

const { object } = await generateObject({
  model: 'anthropic/claude-sonnet-5',
  schema: z.object({
    title: z.string(),
    tags: z.array(z.string()).max(5),
    sentiment: z.enum(['positive', 'neutral', 'negative']),
  }),
  prompt: `Summarise this support ticket: ${ticket}`,
});

object.sentiment; // typed as 'positive' | 'neutral' | 'negative'

The schema does double duty: it steers the model toward the right shape, and it validates the output. If the model returns a field that does not parse, generateObject throws rather than returning half-valid data.

Why not just parse JSON from generateText?

Because JSON.parse on a generateText string is exactly the failure mode generateObject exists to remove. A raw completion is a string that is well-formed JSON most of the time — until the model wraps it in a markdown fence, adds a trailing comment, or drops a required field, and the parse throws in production. generateObject injects the schema into the request, uses each provider's structured-output or tool machinery to constrain generation, and validates the result with your Zod schema before returning.

The win is not fewer characters of code. It is that the boundary between model output and typed value has one owner — the schema — instead of being smeared across a prompt, a regex, and a try/catch.

When should I use streamObject instead of generateObject?

Reach for streamObject when the object is big enough that waiting for the whole thing feels slow. streamObject returns a partialObjectStream that yields the object as it is built, so a UI can render fields the moment they arrive.

import { streamObject } from 'ai';

const { partialObjectStream } = streamObject({
  model: 'anthropic/claude-sonnet-5',
  schema: reportSchema,
  prompt,
});

for await (const partial of partialObjectStream) {
  render(partial); // partial is a deep-partial of Report
}

Each emitted value is a deep-partial of the schema, so every field can be undefined until the model fills it. For one-shot server work — a cron job, a route handler that returns once — generateObject is simpler and stays my default.

What output modes does the AI SDK support?

Mode	What you get	Use it for
`object` (default)	one validated object	extraction, summarization, a single record
`array`	elements via `elementStream`	lists where each row renders as it lands
`enum`	one string from a fixed set	classification, routing, yes/no gates
`no-schema`	arbitrary parsed JSON	exploratory prompts with an unknown shape

For enum I pass output: 'enum' and an enum: ['spam', 'not_spam'] list; the model can only return one of those exact strings, which is stricter and cheaper than an object with one enum field.

When do I use tool calling instead of generateObject?

Use generateObject to extract a value and tool calling to do something. generateObject has no side effects: it turns unstructured input into one typed object and stops. Tool calling — generateText or streamText with a tools map — lets the model decide to call functions, possibly several times in a loop, before it answers.

import { generateText, Output } from 'ai';

const { experimental_output } = await generateText({
  model: 'anthropic/claude-sonnet-5',
  tools: { searchOrders },
  experimental_output: Output.object({ schema: answerSchema }),
  prompt,
});

experimental_output — still flagged experimental — is the bridge: the model runs its tool-calling loop and then returns a final answer validated against a schema, so I get the actions and a typed result from one call.

How do I handle a model that returns invalid JSON?

When generation fails schema validation, the AI SDK throws NoObjectGeneratedError, and catching it explicitly is the difference between a graceful fallback and a 500. The error carries the raw text the model produced, plus usage and response.

import { generateObject, NoObjectGeneratedError } from 'ai';

try {
  const { object } = await generateObject({ model, schema, prompt });
  return object;
} catch (err) {
  if (NoObjectGeneratedError.isInstance(err)) {
    logger.warn({ text: err.text, usage: err.usage }, 'invalid object from model');
    return fallback;
  }
  throw err;
}

Three things cut my failure rate before the catch block runs. First, .describe() on every non-obvious field — the description is sent to the model, so z.string().describe('ISO 8601 date') beats hoping. Second, .nullable() over .optional() for fields the model might not know, because many models emit null more reliably than they omit a key. Third, experimental_repairText, a callback that can strip a code fence or trailing comma before the SDK re-parses. I only retry after those three, because a retry doubles latency and cost.

FAQ

Q: What is the difference between generateObject and generateText?
A: generateText returns a free-form string; generateObject returns a typed object validated against a schema and throws if the output does not match. Use generateText for prose, generateObject whenever you need machine-readable data.

Q: Does generateObject work with any model?
A: It works with any provider the AI SDK supports, but the mechanism varies — some use native structured-output JSON mode, others tool calling under the hood. You pass the same Zod schema regardless; models with native structured output are the most reliable.

Q: Can I stream a structured object to the browser?
A: Yes. streamObject returns a partialObjectStream of deep-partial objects. Render each field as it arrives and treat every field as possibly undefined until the stream completes.

Q: How do I classify text without an object wrapper?
A: Use output: 'enum' with an enum array of allowed labels. The model must return exactly one of the strings, which is stricter and cheaper than an object with a single enum field.

Q: What throws when the model output is malformed?
A: NoObjectGeneratedError. It exposes the raw text, usage, and response so you can log and fall back. Reduce its frequency with field .describe() hints, .nullable() over .optional(), and an experimental_repairText callback.

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

Node.js Runs TypeScript Now: Field Notes on Native Type Stripping

Ahmed Mahmoud — Sun, 02 Aug 2026 06:06:37 +0000

Headline: Node.js executes TypeScript files directly — node script.ts works with no loader, no ts-node, and no build step — by stripping type annotations at load time. Type stripping is on by default since Node.js 23.6 and ships in the 22.18 LTS release, but it only covers erasable syntax: I enforce that with TypeScript 5.8's erasableSyntaxOnly flag, moved type checking to tsc --noEmit in CI, and left my decorator-heavy NestJS services on their existing build.

Key takeaways

Node.js runs .ts files natively by replacing type annotations with whitespace, a mechanism called type stripping. It is enabled by default since Node.js 23.6 and in the 22.18 LTS release; on Node 22.6–22.17 it sits behind --experimental-strip-types.
Type stripping handles only erasable syntax. enum, namespace with runtime code, and constructor parameter properties need the separate --experimental-transform-types flag.
Node.js never type-checks and never reads tsconfig.json. The type checker is still tsc --noEmit, run in CI or a pre-commit hook.
TypeScript 5.8's erasableSyntaxOnly compiler option turns every non-erasable construct into a compile error, which guarantees a file Node.js can run.
Relative imports must spell out the .ts extension, and Node.js refuses to strip types inside node_modules — published packages still ship JavaScript.

Can Node.js run TypeScript without a build step?

Yes, for most application code. Node.js 22.6 introduced type stripping behind the --experimental-strip-types flag, Node.js 23.6 turned it on by default, and the 22.18 release brought the default-on behavior to the LTS line. On Node.js 24 — the current LTS and my daily runtime — node script.ts simply executes.

// hello.ts
const greet = (name: string): string => `Hello, ${name}`;
console.log(greet('Node 24'));
console.log(process.features.typescript); // 'strip'

The mechanism matters. In strip mode Node.js replaces every type annotation with whitespace instead of compiling the file, so line and column numbers in stack traces match the source exactly, with no source maps involved. process.features.typescript reports the active mode: 'strip', 'transform', or false. The first things I moved over were the places a build step hurt most: one-off utilities in scripts/, config files like drizzle.config.ts, and cron jobs that previously dragged in ts-node just to start.

What TypeScript syntax does type stripping not support?

Erasable syntax is anything that can be deleted without changing runtime behavior: type annotations, interface, type aliases, generics, satisfies, and as casts. Type stripping handles all of it. Four constructs generate JavaScript output and are therefore not erasable: enum, namespace with runtime values, constructor parameter properties (constructor(private db: Database)), and import x = require(). Files that use them need --experimental-transform-types, which switches Node.js from stripping to a full SWC-based transform with source maps.

I avoid the transform flag entirely and keep everything erasable. Enums were the only construct I actually had to migrate, and the replacement is arguably better TypeScript anyway:

// instead of: enum Role { Admin = 'admin', Editor = 'editor' }
const ROLES = ['admin', 'editor'] as const;
type Role = (typeof ROLES)[number];

A const array plus a derived union type is erasable, serializes cleanly, and produces none of the surprising runtime objects enums do.

How do I guarantee my code stays erasable?

TypeScript 5.8 added the erasableSyntaxOnly compiler option, which turns every non-erasable construct into a compile error. With it enabled, code that passes the type checker is guaranteed to run under Node.js strip mode — the constraint is enforced by tooling instead of code review.

{
  "compilerOptions": {
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "allowImportingTsExtensions": true,
    "noEmit": true,
    "module": "nodenext"
  }
}

Three companions earn their place. verbatimModuleSyntax forces type-only imports to be written as import type, so stripping an import can never change the runtime module graph. allowImportingTsExtensions permits the explicit ./util.ts specifiers Node.js requires — the runtime does not rewrite import paths. And one fact that reframes the whole setup: Node.js never reads tsconfig.json. The config exists for the editor and for tsc; the runtime ignores it in both strip and transform modes.

Where does type checking happen if Node strips types?

Nowhere at runtime. Node.js discards annotations without validating them, which is the same trade-off esbuild-based runners like tsx made years ago — the ecosystem already proved it workable. My setup: tsc --noEmit runs as a CI gate and in a pre-commit hook, and the editor surfaces errors live through the TypeScript language server. The honest failure mode: a file with a type error still executes, so the gate — not the runtime — is what keeps it from shipping. Type stripping makes broken types quieter, not safer, which is exactly why the gate stays mandatory.

What did I replace, and what still needs tsx or a build?

Native execution replaced ts-node and tsx for me in every script-shaped context, but not everywhere. The comparison I actually use:

Runner	Type checks?	Non-erasable syntax	When I reach for it
Node.js type stripping	No	No (strip mode)	Scripts, configs, cron jobs on Node 22.18+
tsx	No	Yes, plus JSX and path aliases	Older Node versions or tsconfig path aliases
ts-node	Optional	Yes	Legacy projects that already depend on it
tsc build	Yes	Yes	Published libraries and decorator-heavy apps

The dependency count is the underrated win. A repo whose scripts run on bare Node.js needs no loader in devDependencies and no --import wiring, and node --watch script.ts covers the dev loop that tsx's watch mode used to handle.

Which projects should keep their build step?

My NestJS services kept theirs. NestJS dependency injection relies on emitDecoratorMetadata, and Node.js emits no decorator metadata in either strip or transform mode, so constructor injection loses the type information it resolves providers with — native execution is not an option there. The other hard boundaries: JSX/TSX files are out of scope, Node.js does not resolve tsconfig path aliases, and type stripping deliberately skips node_modules, so anything published to npm must ship compiled JavaScript. Libraries need tsc for .d.ts output regardless.

FAQ

Q: Do I still need ts-node or tsx?

A: Not for erasable-syntax scripts on Node.js 22.18 or newer. tsx still earns its keep for JSX, tsconfig path aliases, and older Node versions; ts-node I no longer install at all.

Q: Does Node.js type-check the TypeScript it runs?

A: No. Type stripping discards annotations without validating them. Run tsc --noEmit in CI or a pre-commit hook to catch type errors before they ship.

Q: Does Node.js read tsconfig.json?

A: No. The runtime ignores it in both strip and transform modes. tsconfig.json configures the editor and tsc only.

Q: Can I use enums with native TypeScript execution?

A: Only behind --experimental-transform-types. A const array or const object with a derived union type is erasable and behaves more predictably — I migrated my enums instead of enabling the flag.

Q: Do TypeScript files inside node_modules work?

A: No. Node.js deliberately refuses to strip types in node_modules, so published packages must ship compiled JavaScript with declaration files.

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

AbortController Beyond fetch: The Cancellation Patterns I Use in Every React App

Ahmed Mahmoud — Sat, 01 Aug 2026 06:07:20 +0000

Headline: AbortController is the web platform's single cancellation primitive: one controller produces one AbortSignal, and that signal plugs into fetch, addEventListener, and most modern data libraries. Four patterns — abort-on-cleanup in useEffect, AbortSignal.timeout() for deadlines, AbortSignal.any() to merge cancel sources, and the signal option for bulk listener removal — eliminated a whole class of race conditions in my React apps.

Key takeaways

AbortController creates an AbortSignal; calling controller.abort(reason) flips signal.aborted to true and rejects any in-flight fetch that was given that signal.
An AbortController is one-shot. Once aborted it stays aborted, so every new request needs a fresh controller.
AbortSignal.timeout(ms) returns a signal that aborts with a TimeoutError DOMException — it replaces hand-rolled setTimeout + abort() + clearTimeout wiring.
AbortSignal.any([a, b]) merges cancellation sources: the returned signal aborts as soon as the first input signal aborts.
Aborting a request cancels the response, not the server-side work. Never use abort to undo a write; abort reads freely.

What is AbortController and how does the signal actually work?

AbortController is a built-in browser and Node.js class that produces a single AbortSignal, and that signal is the web platform's standard way to say stop this work. I create a controller, hand its signal to any API that accepts one, and call controller.abort(reason) when the work is no longer needed. Every consumer of the signal reacts at once: an in-flight fetch rejects, listeners registered with the signal are removed, and my own code can check signal.aborted or call signal.throwIfAborted() inside a loop.

const controller = new AbortController();
controller.signal.aborted; // false
controller.abort(new Error('user navigated away'));
controller.signal.aborted; // true
controller.signal.reason;  // Error: user navigated away

The part that trips people up: a controller is one-shot. There is no reset. Once abort() has been called, that signal is aborted forever, and any fetch started with it fails immediately. Every new request gets a new AbortController.

How do I cancel a stale fetch in a React useEffect?

The classic race condition: a search box fires one request per keystroke, and a slow early response resolves after a fast later one, overwriting fresh results with stale data. The fix is to abort the previous request in the effect cleanup, so only the latest request can ever reach setState.

useEffect(() => {
  const controller = new AbortController();
  fetch('/api/search?q=' + query, { signal: controller.signal })
    .then((r) => r.json())
    .then(setResults)
    .catch((err) => {
      if (err.name !== 'AbortError') setError(err);
    });
  return () => controller.abort();
}, [query]);

React runs the cleanup before re-running the effect, so fast typing aborts each stale request the moment the next one starts. The same cleanup fires on unmount, which kills the setState-after-unmount class of warnings at the source instead of guarding with an isMounted flag. TanStack Query does this automatically — the queryFn receives { signal }, and passing it through to fetch is all it takes.

What does AbortSignal.timeout() replace?

AbortSignal.timeout(ms) returns a signal that aborts automatically after the given number of milliseconds. It replaces the pattern most codebases hand-rolled for years: create a controller, call setTimeout(() => controller.abort(), ms), then remember to clearTimeout on success. Three lines of lifecycle management collapse into one expression.

const res = await fetch('/api/report', { signal: AbortSignal.timeout(8000) });

Two details matter. First, a timeout signal aborts with a TimeoutError DOMException, while a manual abort() produces an AbortError — error handling can tell a deadline from a deliberate cancel. Second, AbortSignal.timeout() works in all modern browsers and in Node.js 18+, so the same code runs in route handlers and server-side jobs too.

How do I combine a timeout with a user cancel button?

AbortSignal.any(signals) takes an array of signals and returns one that aborts as soon as any input aborts — the cancellation equivalent of Promise.race(). My most common use is a long AI generation request that should stop when the user clicks cancel or when a hard deadline passes, whichever comes first.

const controller = new AbortController(); // wired to a cancel button
const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(30_000)]);
const res = await fetch('/api/generate', { signal });

The merged signal's reason comes from whichever source fired first, so err.name still says whether the user cancelled (AbortError) or the deadline hit (TimeoutError). AbortSignal.any() is newer than the rest of the API — Chrome 116+, Safari 17.4+, Firefox 124+, Node.js 20.3+ — but that covers evergreen browsers, and I use it without a polyfill.

Can one signal remove many event listeners at once?

Yes. addEventListener accepts a signal option, and aborting that signal removes every listener registered with it. This is my default for drag interactions, keyboard-shortcut scopes, and any widget that attaches listeners to window or document: no stored function references, no matching removeEventListener calls, one abort() tears everything down.

const controller = new AbortController();
window.addEventListener('resize', onResize, { signal: controller.signal });
window.addEventListener('scroll', onScroll, { signal: controller.signal });
element.addEventListener('pointermove', onMove, { signal: controller.signal });

// teardown — all three listeners removed at once
controller.abort();

In React this pairs cleanly with useEffect: register every listener with one signal, return () => controller.abort() as the cleanup, and teardown can never drift out of sync with setup.

How do I tell a cancellation from a real failure?

An aborted fetch rejects, so cancellations land in the same catch block as genuine network errors — and reporting them blindly fills the error tracker with noise every time a user navigates away mid-request. The discriminator is the error's name property.

try {
  const res = await fetch(url, { signal });
  return await res.json();
} catch (err) {
  if (err instanceof DOMException && err.name === 'AbortError') return; // expected: we cancelled
  if (err instanceof DOMException && err.name === 'TimeoutError') {
    return reportTimeout(url); // deadline hit — worth counting
  }
  throw err; // real failure
}

Passing a custom value to abort(reason) makes that value the rejection instead of the default DOMException. That is useful when the abort should carry context, but it also means an AbortError name check will not match — pick one convention per codebase and stick to it.

When should I not abort a request?

Aborting cancels the response, not the server-side work. By the time abort() runs on a POST, the server may already have committed the write — closing the connection rolls nothing back. My rule: abort reads freely and aggressively; let writes finish. When a user genuinely needs to cancel a write, an idempotency key plus an explicit compensating request is the honest design; an aborted POST that maybe-committed is not. The rule has a server-side mirror: in a Next.js route handler, request.signal aborts when the client disconnects, and long streaming work should check it so the server stops paying for output nobody is reading.

FAQ

Q: Does aborting a fetch cancel the request on the server?
A: No. abort() closes the client connection, but work the server already started may run to completion. Treat abort as client-side cleanup, and design writes with idempotency keys if cancellation matters.

Q: Can I reuse an AbortController after calling abort()?
A: No. A controller is one-shot — once aborted, its signal stays aborted and any fetch given that signal rejects immediately. Create a new controller per request.

Q: What error does an aborted fetch throw?
A: A DOMException named AbortError for a manual abort(), or TimeoutError when the signal came from AbortSignal.timeout(). A custom reason passed to abort(reason) becomes the rejection value instead.

Q: Does TanStack Query use AbortController under the hood?
A: Yes. The queryFn receives an object containing signal; pass it to fetch and superseded or unmounted queries are aborted automatically.

Q: Is AbortSignal.any() safe to use without a polyfill?
A: For evergreen targets in 2026, yes: it shipped in Chrome 116, Safari 17.4, Firefox 124, and Node.js 20.3. For older browsers, feature-detect and fall back to a single controller.

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

One API Key for Every Model: Field Notes on the Vercel AI Gateway

Ahmed Mahmoud — Fri, 31 Jul 2026 14:13:21 +0000

Headline: The Vercel AI Gateway is a single endpoint that routes AI SDK calls to any model provider through a plain "provider/model" string. I removed @ai-sdk/anthropic, @ai-sdk/openai, and three separate provider API keys, and now switch models by editing one string instead of swapping SDK packages.

Key takeaways

The Vercel AI Gateway is a unified API, GA since August 2025, that sits between your app and multiple LLM providers so one credential and one code path reach any model.
With the AI SDK you select a model by a "provider/model" string — 'anthropic/claude-sonnet-5', 'openai/gpt-5' — instead of importing a provider-specific package like @ai-sdk/anthropic.
Model fallbacks let you declare an ordered list of models; if the primary is rate-limited or erroring, the gateway retries the next on the same request without your code branching.
The gateway adds observability (per-request cost, latency, tokens) and supports zero data retention, so switching providers no longer means re-instrumenting logging.
The gateway replaces per-provider SDK wiring and key management — not the AI SDK itself; you still call generateText, streamText, and the same tool-calling API.

What is the Vercel AI Gateway and what problem does it solve?

The Vercel AI Gateway is a hosted proxy that exposes a single OpenAI-compatible endpoint and forwards requests to whichever provider a model string names. Instead of holding an Anthropic key, an OpenAI key, and a Google key — each with its own SDK and rate-limit behavior — you hold one gateway credential and name the model inline. The problem it solves is provider lock-in at the code level: when a call is anthropic('claude-sonnet-5'), trying a different provider means a new import, a new client, and often a new logging shape. When the call is the string 'anthropic/claude-sonnet-5', trying 'openai/gpt-5' is a one-line diff.

How do I switch from a provider SDK to the gateway?

Drop the provider import and pass a "provider/model" string to the AI SDK's model field. The AI SDK resolves any bare string through the gateway by default.

// Before: provider SDK + provider-specific key
import { anthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const { text } = await generateText({
  model: anthropic('claude-sonnet-5'),
  prompt: 'Summarize this support ticket in two sentences.',
});

// After: gateway string routing, one AI_GATEWAY_API_KEY
import { generateText } from 'ai';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-5',
  prompt: 'Summarize this support ticket in two sentences.',
});

Everything downstream — streamText, generateObject, tool calling — stays identical. The model becomes configuration, not code.

When should I use model fallbacks?

Use fallbacks when a request must succeed even if your preferred provider is rate-limited or down. The gateway tries the primary, and on a provider error retries the next model transparently within the same call.

import { generateText } from 'ai';
import { gateway } from '@ai-sdk/gateway';

const { text } = await generateText({
  model: gateway('anthropic/claude-sonnet-5', {
    fallbacks: ['openai/gpt-5', 'google/gemini-2.5-pro'],
  }),
  prompt: 'Draft a release note from this git diff.',
});

I do not use fallbacks on background jobs where I want deterministic behavior — a nightly batch should fail loudly and retry the same model, not silently answer with a different one whose output I never evaluated. Fallbacks trade consistency for availability; spend that trade only where availability matters more.

What does the gateway replace, and what stays?

Concern	Before (per-provider SDK)	With the AI Gateway
Model selection	`anthropic('...')`, `openai('...')` imports	`'provider/model'` string
Credentials	One API key per provider	One gateway key
Switching provider	New import + client + key	Edit the model string
Fallback on outage	Hand-written try/catch	Ordered `fallbacks` list
Cost + latency	Per-provider dashboards	Unified per-request metrics
SDK call shape	`generateText`/`streamText`	Unchanged

What about cost, data retention, and observability?

The gateway reports cost, latency, and token counts per request in one place, so comparing two models on the same prompt no longer means stitching together two providers' billing pages. It also supports a zero data retention mode, meaning request and response bodies are not stored by the gateway — important when the prompt carries customer data and you need a clean data-flow answer for a security review. The practical win is measurement: when model choice is a string and metrics are unified, a real comparison — same prompt, three models, look at cost and latency — is a config change plus a dashboard read, not an engineering project.

What I'd watch before going all-in

One indirection layer means one more dependency in the request path — if the gateway is down, every model call is down, so I still keep the fallback list plus sane timeouts. And a bare string is only provider-agnostic until you rely on a provider-specific feature (a tool format, a cache-control header); then you're back to provider options, just passed through the gateway. Neither is a dealbreaker, but both are worth knowing before you delete the provider packages like I did.

FAQ

Q: Do I still need the AI SDK if I use the Vercel AI Gateway?
A: Yes. The gateway routes model requests; the AI SDK is still what you call in code (generateText, streamText, generateObject). It replaces provider-specific packages like @ai-sdk/anthropic, not the core ai package.

Q: How do I select a model through the gateway?
A: Pass a "provider/model" string to the model field, e.g. 'anthropic/claude-sonnet-5' or 'openai/gpt-5'. Bare model strings resolve through the gateway by default.

Q: What happens if my primary model is rate-limited?
A: With an ordered fallbacks list, the gateway retries the next model on the same request. Without fallbacks, the call returns the provider error for you to handle.

Q: Does the gateway store my prompts?
A: It supports a zero data retention mode where request and response bodies are not retained. Verify the setting for your account before sending sensitive data.

Q: Should I use provider-specific SDKs at all in 2026?
A: Default to gateway string routing for portability. Reach for a direct provider SDK only when you need a provider-specific capability the gateway doesn't surface.

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

WebSockets on Vercel Functions: Real-Time Without a Separate Server

Ahmed Mahmoud — Mon, 27 Jul 2026 22:34:52 +0000

Headline: Vercel Functions can now hold WebSocket connections open directly on Fluid Compute, the same runtime that already serves my regular API routes — I stopped standing up a dedicated Socket.IO server and a Redis pub/sub layer just to push live updates to a browser tab.

Key takeaways

Vercel Functions support WebSockets natively through experimental_upgradeWebSocket() from @vercel/functions, running on Fluid Compute — no standalone WebSocket server or third-party realtime service required.
Fluid Compute reuses a warm function instance across concurrent requests instead of spinning up one instance per request; that's what makes holding a long-lived socket open practical on a platform historically built around short request/response cycles.
Standard Node.js libraries like ws work inside a Vercel Function unchanged — I didn't rewrite client or server socket logic to move this off a dedicated server.
WebSockets still win over Server-Sent Events for anything bidirectional: chat input, collaborative cursors, live multiplayer state. SSE stays the simpler choice for one-way streaming.
Managed services like Pusher or Ably still earn their place at large fan-out scale or when you need built-in presence and room primitives; for a single app's realtime feature, self-hosting on Vercel Functions is now a realistic default.

Can a Vercel Function actually keep a WebSocket connection open?

Yes, as long as it runs on Fluid Compute, the default runtime for Vercel Functions. The old serverless mental model — one isolated container per invocation, torn down the moment the response finishes — never had a slot for a connection that stays open for minutes or hours.

Fluid Compute changes the unit of work: instances are reused across concurrent requests, so a function can keep a socket alive across that reused instance instead of dying the second it returns a response. That's also why the platform supports graceful shutdown and request cancellation on the same runtime — a function mid-stream when a deploy rolls out gets a chance to close connections cleanly instead of being killed mid-write.

For a chat feature or a live dashboard, that's the difference between a socket that silently drops on every deploy and one that reconnects predictably.

How do I upgrade a Vercel Function to a WebSocket connection?

I call experimental_upgradeWebSocket() from @vercel/functions inside a route handler, the same way I'd upgrade an HTTP connection on any Node.js server:

// app/api/live/route.ts
import { experimental_upgradeWebSocket } from '@vercel/functions';

export function GET(request: Request) {
  return experimental_upgradeWebSocket(request, {
    onOpen(ws) {
      ws.send(JSON.stringify({ type: 'connected' }));
    },
    onMessage(ws, event) {
      const payload = JSON.parse(event.data as string);
      ws.send(JSON.stringify({ type: 'ack', received: payload }));
    },
    onClose(ws, event) {
      // clean up per-connection state
    },
  });
}

On the client it's a plain WebSocket — nothing Vercel-specific to install:

const socket = new WebSocket('wss://your-app.vercel.app/api/live');
socket.onmessage = (event) => {
  const data = JSON.parse(event.data);
};

If I'm already using ws for connection pooling, rooms, or heartbeat handling, that code carries over — the upgrade point is the only thing that's Vercel-specific.

When should I reach for WebSockets instead of SSE or polling?

The deciding question is direction: does the client need to send frequent messages back, not just receive them? If yes, WebSockets are the right tool. If the client only ever listens, Server-Sent Events are simpler to operate and debug.

Concern	WebSocket	SSE	Polling
Direction	Bidirectional	Server → client only	Client-initiated, repeated
Protocol	Own upgrade (`ws://`, `wss://`)	Plain HTTP, `text/event-stream`	Plain HTTP requests
Reconnection	Manual	Built into `EventSource`	N/A
Good fit	Chat, collaborative editing, multiplayer cursors	Token streaming, notifications, live logs	Low-frequency status checks
Infra on Vercel	`experimental_upgradeWebSocket()` + Fluid Compute	Any Node.js runtime	None

I'd already covered SSE for token streaming in an earlier post — that's still the right call for one-way AI output. WebSockets are for the features where the browser talks back.

Do I still need Pusher, Ably, or a standalone WebSocket server?

Sometimes, but not by default anymore. Managed realtime platforms like Pusher and Ably handle two things that are genuinely hard to build yourself: fan-out across thousands of concurrent connections, and presence/room primitives as an out-of-the-box API. If your feature is at that scale, a managed service is still the pragmatic choice.

What changed is the baseline. Before, any WebSocket on Vercel meant running a separate always-on server elsewhere just to hold the socket. Now a single-feature realtime need can live entirely inside the same Vercel Function that serves the rest of your API. One deploy target, one auth model, one set of environment variables.

What connection limits and reconnection patterns do I need to handle myself?

WebSockets don't get automatic reconnection the way EventSource does for SSE — that logic is on you.

Exponential backoff on reconnect — retry with increasing delay (1s, 2s, 4s, capped around 30s) instead of hammering the endpoint immediately.
Heartbeat pings — send a ping on an interval, expect a pong back; if none arrives, treat the connection as dead and reconnect.
Idle timeouts are real — a connection with no traffic can be dropped by intermediate proxies; the heartbeat above doubles as keep-alive.
Resync state on reconnect — design the protocol so the server can answer "catch me up from X" rather than assuming the client saw every message.

None of this is Vercel-specific — it's the same discipline any WebSocket client needs — but it matters more here because there's no managed service hiding it from you.

FAQ

Q: Do I need the Edge runtime to use WebSockets on Vercel?

A: No. WebSocket support runs on Fluid Compute with the standard Node.js runtime — you don't need runtime = 'edge'.

Q: Can I use the ws npm package directly instead of experimental_upgradeWebSocket()?

A: experimental_upgradeWebSocket() performs the HTTP-to-WebSocket upgrade inside a Vercel Function; once open, existing socket-handling code, including logic built around ws, carries over largely unchanged.

Q: Is this the same as SSE for AI streaming?

A: No. SSE is one-way and remains the right choice for streaming AI tokens. WebSockets are bidirectional and fit features where the client also sends frequent messages back.

Q: Do WebSocket connections survive a new deployment?

A: Fluid Compute supports graceful shutdown and request cancellation, giving in-flight connections a chance to close cleanly during a deploy — but your client should still implement reconnect logic for the brief rollover window.

Q: Do I still need Redis for multi-instance fan-out?

A: If your app runs on a single reused Fluid Compute instance, in-memory broadcast is enough. Once traffic spans multiple instances, a shared layer like Redis pub/sub is still needed to fan messages out across them.

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

Next.js Middleware in 2026: Auth Guards, A/B Tests, and What Belongs at the Edge

Ahmed Mahmoud — Sun, 26 Jul 2026 21:03:49 +0000

Headline: Next.js Middleware (middleware.ts at the project root) runs before every matched request — before cache, before rendering, before the route. That position makes it right for auth redirects, A/B cookie bucketing, and locale detection. Wrong for database queries and heavy imports. In 2026, Middleware on Vercel runs on Fluid Compute (standard Node.js), so the constraint is latency budget, not API availability.

Key takeaways

Middleware runs before every matched request — before cache, rendering, or route handler — the right layer for auth, locale, and A/B bucketing.
Middleware can read requests, set cookies, redirect, rewrite, or return early — without the route running. DB queries and large packages add latency to every request.
On Vercel in 2026, Middleware runs on Fluid Compute (standard Node.js). The constraint is latency: every added millisecond is paid on every matched request.
Use matcher to scope Middleware to only the routes that need it; without it Middleware runs on every static asset request.
Auth in Middleware = verifying a self-contained JWT without a DB call. Full session validation belongs in the route.

I spent a long time only using Middleware for locale redirects. After shipping auth-protected routes and an A/B test, the full shape became clear.

What is Next.js Middleware and where does it run?

Middleware is exported from middleware.ts at the project root. It intercepts matched requests before route resolution, cache lookup, and Server Component execution. Returns one of four types: pass through (NextResponse.next()), redirect, rewrite (serve different content while keeping original URL in address bar), or a direct response.

export function middleware(request: NextRequest) {
  return NextResponse.next();
}
export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

Without matcher, Middleware runs on every request including static files. On Vercel in 2026, Middleware runs on Fluid Compute — standard Node.js. Aim for under 10 ms.

How do I write an auth guard?

Read a JWT from a cookie, verify locally with jose (no DB call), redirect to /login if missing or invalid. Delete the cookie on invalid tokens to prevent a redirect loop.

import { jwtVerify } from 'jose';
const SECRET = new TextEncoder().encode(process.env.JWT_SECRET!);

export async function middleware(request: NextRequest) {
  const token = request.cookies.get('session')?.value;
  if (!token) return NextResponse.redirect(new URL('/login', request.url));
  try {
    await jwtVerify(token, SECRET);
    return NextResponse.next();
  } catch {
    const res = NextResponse.redirect(new URL('/login', request.url));
    res.cookies.delete('session'); // prevent redirect loop
    return res;
  }
}
export const config = { matcher: ['/dashboard/:path*'] };

Redirect target must be a URL object, not a bare string.

How do I run A/B tests?

Check for a bucket cookie, assign one if absent, rewrite to the variant URL. The rewrite keeps the address bar showing the original URL — share links always go to control.

export function middleware(request: NextRequest) {
  if (!request.nextUrl.pathname.startsWith('/pricing')) return NextResponse.next();
  const existing = request.cookies.get('ab-pricing')?.value;
  const variant = existing ?? (Math.random() < 0.5 ? 'control' : 'variant-b');
  const url = request.nextUrl.clone();
  url.pathname = `/_experiments/pricing/${variant}/`;
  const res = NextResponse.rewrite(url);
  if (!existing) res.cookies.set('ab-pricing', variant, { maxAge: 86400 * 30, httpOnly: true });
  return res;
}

Variants live at app/_experiments/pricing/control/ and app/_experiments/pricing/variant-b/ — the _ prefix makes them private routes.

What can Middleware read and write?

Operation	API	Notes
Read cookies	`request.cookies.get('name')`	Typed helpers built-in
Set cookies	`response.cookies.set(...)`	On any NextResponse
Forward headers	`NextResponse.next({ request: { headers } })`	Pass locale, user ID downstream
Redirect (URL changes)	`NextResponse.redirect(url)`	Full URL object required
Rewrite (URL stays)	`NextResponse.rewrite(url)`	A/B tests, path aliases
Early response	`new NextResponse(body, { status })`	Rate limit, maintenance mode

What should NOT go in Middleware?

Database queries — every matched request pays the round trip before the route runs; use a self-verifiable JWT instead. Heavy npm imports — increase cold-start time; keep middleware.ts to jose and nothing else avoidable. Network-dependent rate limiting — a Redis timeout becomes a timeout on every request; put rate limiting in a Route Handler.

FAQ

Q: Does Middleware run on static file requests?
A: Only on routes matching config.matcher. Without it, runs on everything including _next/static. Use the standard negative lookahead.

Q: What's the difference between redirect and rewrite?
A: redirect sends 307/308 and the browser navigates — address bar changes. rewrite serves different content while keeping the original URL. Auth → redirect; A/B tests → rewrite.

Q: Can Middleware read the POST body?
A: No — buffering breaks streaming and prevents the route from reading it. Decisions on cookies, headers, and URL only.

Q: Is Middleware still on the Edge Runtime in 2026?
A: Not on Vercel — it runs on Fluid Compute (standard Node.js). Constraint is latency budget, not API availability.

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

Shipping a Bilingual Next.js App in English and Arabic: Routing, RTL, and What Crawlers Actually See

Ahmed Mahmoud — Sat, 25 Jul 2026 13:03:14 +0000

Headline: A bilingual Next.js site needs three things done right: one URL per language (a /en and /ar path prefix, not a cookie), a layout that flips through CSS logical properties instead of hand-patched left/right overrides, and hreflang metadata that tells search engines the two URLs are translations of each other. I learned the first one the hard way — a cookie-driven language switcher meant crawlers only ever indexed the English half of the site.

Key takeaways

Serve each language on its own URL. Path prefixes such as /en/services and /ar/services are the multilingual structure Google's documentation recommends; content that switches per cookie on a single URL gets exactly one language indexed.
Search engine crawlers do not persist cookies, and Googlebot crawls mostly from US IP addresses without varying its Accept-Language header — a cookie-based language toggle is invisible to them.
dir="rtl" on <html> plus CSS logical properties flip a layout automatically. Tailwind's ms-*, me-*, ps-*, pe-*, and text-start utilities map to margin-inline-start and friends.
Load Arabic fonts per locale with next/font — for example IBM_Plex_Sans_Arabic with the arabic subset — so English visitors never download the Arabic font and vice versa.
hreflang lives in generateMetadata through alternates.languages, must be reciprocal between the two locales, and needs an x-default pointing at the fallback URL.

Most of what I build serves users in both English and Arabic. The first bilingual site I shipped used a cookie-driven switcher: one URL, and the server rendered whichever language the cookie asked for. It felt elegant until I checked what search engines had indexed — English only, on every page. These field notes cover the move to URL-prefix routing in the Next.js App Router, treating RTL as a first-class layout mode instead of a patch, and the metadata that makes both languages visible to crawlers and answer engines.

How should I structure locale routing in the Next.js App Router?

Put the locale in the URL as the first path segment: an app/[locale]/ dynamic segment, so every page exists at /en/... and /ar/.... The locale layout reads the param and sets both lang and dir on the <html> element, and generateStaticParams prerenders both language trees.

// app/[locale]/layout.tsx
const locales = ['en', 'ar'] as const;

export function generateStaticParams() {
  return locales.map((locale) => ({ locale }));
}

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;
  return (
    <html lang={locale} dir={locale === 'ar' ? 'rtl' : 'ltr'}>
      <body>{children}</body>
    </html>
  );
}

Middleware handles exactly one job: a request to a bare path such as / or /services gets redirected to its localized twin, negotiated from a saved preference cookie first and the Accept-Language header second. After that redirect, the URL — not the cookie — is the single source of truth for language. Translations themselves are plain JSON dictionaries I await inside server components, so no translation strings ship in the client bundle; next-intl earns its place when you need ICU plurals, rich formatting, and typed message keys, but a two-locale marketing site does not need it on day one.

Why does cookie-based language switching hurt SEO?

Because a crawler is always a first-time visitor with an empty cookie jar: it requests the URL, receives the default language, and indexes that. Your second language never enters the index. Googlebot does not persist cookies between requests, crawls predominantly from US IP addresses, and does not systematically vary its Accept-Language header — Google's own documentation recommends separate URLs per language rather than dynamic content on one URL. Cookie switching also breaks hreflang outright, since hreflang maps languages to URLs and both languages share one. And it breaks humans too: a link copied by an Arabic reader opens in whatever language the recipient's cookie says, not what the sender was looking at.

Concern	Cookie-based switching	URL-prefix routing
URL shape	One URL, content varies	One URL per language
What crawlers index	Default language only	Both languages
hreflang possible	No — nothing to point at	Yes
Shared links keep language	No — recipient's cookie wins	Yes
CDN caching	Needs `Vary: Cookie`, poor hit rate	Plain per-URL caching
Switcher implementation	Set cookie + reload	Link to the same path in the other locale

The migration cost me less than I feared: the switcher became a link to the same pathname under the other prefix, and the cookie survives only to make the bare-URL redirect remember your choice.

How do I make a layout flip for RTL without rewriting the CSS?

Set dir="rtl" on <html> and write every style in CSS logical properties; the browser does the flipping. A physical property such as margin-left stays on the left in both directions, but the logical margin-inline-start means "the side where text starts" — left in English, right in Arabic. In Tailwind that is a mechanical substitution: ml-4 becomes ms-4, pr-6 becomes pe-6, text-left becomes text-start, border-l-2 becomes border-s-2.

// Physical utilities — the sidebar sticks to the wrong side in RTL
<aside className="ml-4 pr-6 text-left border-l-2">

// Logical utilities — flip automatically when dir="rtl"
<aside className="ms-4 pe-6 text-start border-s-2">

Flexbox and grid already follow the document direction, so most layout flips for free. What needs manual attention is a short list. Directional icons — back arrows, chevrons, "next" indicators — must mirror, which rtl:-scale-x-100 handles; logos, checkmarks, and media-playback icons must not. Mixed-direction text is the subtle one: an English product name, an email address, or a code identifier inside an Arabic sentence can drag punctuation to the wrong side, and wrapping the embedded token in <bdi> (or using dir="auto" on user-generated content) isolates it. For numerals, Intl.NumberFormat decides between Western digits and Eastern Arabic digits per locale — pick one convention and apply it everywhere.

How do I load Arabic fonts without shipping them to everyone?

Declare one font per script with next/font and attach only the active locale's font variable in the layout. next/font self-hosts and subsets at build time, so there is no runtime request to Google Fonts and no layout shift from late-loading glyphs.

import { Inter, IBM_Plex_Sans_Arabic } from 'next/font/google';

const inter = Inter({ subsets: ['latin'], variable: '--font-sans' });
const arabic = IBM_Plex_Sans_Arabic({
  subsets: ['arabic'],
  weight: ['400', '500', '700'],
  variable: '--font-sans',
});

// in app/[locale]/layout.tsx
<html lang={locale} dir={dir} className={locale === 'ar' ? arabic.variable : inter.variable}>

Two script-specific notes from shipping this. Arabic has no italic tradition — browsers synthesize a slant that reads as broken, so my Arabic styles never use font-style: italic and lean on weight for emphasis instead. And Arabic glyphs sit taller than Latin ones, so a line-height tuned for English headlines usually needs loosening for the Arabic rendering of the same component.

How do I wire hreflang so both languages get indexed?

Return alternates.languages from generateMetadata on every page, listing the absolute URL of each translation plus an x-default.

// app/[locale]/services/page.tsx
export async function generateMetadata({ params }: Props) {
  const { locale } = await params;
  const base = 'https://www.devya.dev';
  return {
    alternates: {
      canonical: `${base}/${locale}/services`,
      languages: {
        en: `${base}/en/services`,
        ar: `${base}/ar/services`,
        'x-default': `${base}/en/services`,
      },
    },
  };
}

Three rules keep it valid. The annotations must be reciprocal — the English page lists the Arabic URL and the Arabic page lists the English one, and each lists itself. The URLs must be absolute and canonical. And x-default names the page for visitors matching neither language, normally the English URL. Localize the rest of the metadata while you are there: an Arabic page with an English <title> and meta description looks broken in Arabic search results, and answer engines quoting the page inherit the mismatch.

FAQ

Q: Does Googlebot use cookies or Accept-Language to find my Arabic content?

A: No. Googlebot does not persist cookies and generally crawls without varying Accept-Language, mostly from US IPs. Content only reachable through a cookie or header switch stays unindexed — give each language its own URL.

Q: Should Arabic live on a path prefix, a subdomain, or a ccTLD?

A: A path prefix (/ar/) is the cheapest to operate: one deployment, one domain accumulating authority, and hreflang ties the variants together. Subdomains and country TLDs make sense for separate regional businesses, not for a language variant of one site.

Q: Does dir="rtl" break flexbox or grid?

A: No. Flex rows and grid columns follow the document direction automatically. Breakage comes from physical utilities (ml-*, text-left) and absolutely positioned elements pinned with left:/right: — replace them with logical equivalents.

Q: Do I need next-intl for a bilingual site?

A: Not necessarily. An app/[locale] segment plus JSON dictionaries awaited in server components covers a static bilingual site. next-intl pays off when you need ICU plurals, date and number formatting, and typed message keys across a large app.

Q: Which icons should flip in RTL?

A: Only directional ones — back and forward arrows, chevrons, progress indicators. Logos, checkmarks, and media-playback controls keep their orientation.

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

Streaming AI Responses in Next.js: SSE, Fetch Streams, and What Breaks in Production

Ahmed Mahmoud — Thu, 23 Jul 2026 06:07:41 +0000

Headline: Streaming an AI response in the Next.js App Router takes one Route Handler that returns a streaming Response and one client hook — the AI SDK's streamText and useChat handle the wire protocol. The hard parts live around that code: proxies that buffer the stream into a single blob, compression that swallows token chunks, refreshes that kill in-flight generations, and abort wiring that decides whether you keep paying for tokens nobody is reading.

Key takeaways

Streaming in the Next.js App Router is a Route Handler returning a streamed Response. The AI SDK's streamText plus toUIMessageStreamResponse() emit an SSE-based message stream, and the useChat hook from @ai-sdk/react consumes it.
Chat UIs do not use the browser EventSource API. EventSource only supports GET requests with no body, so AI chat clients POST with fetch and read the SSE-formatted response through a ReadableStream reader.
A stream that works locally but arrives all at once in production is almost always intermediary buffering — compression middleware, nginx proxy_buffering, or a corporate proxy. Cache-Control: no-transform and X-Accel-Buffering: no fix most cases.
Passing the request's AbortSignal into streamText means a closed tab cancels the upstream model call and stops token spend immediately.
A page refresh kills the default fetch stream. Persist finished messages in onFinish on the server; reach for resumable streams only when mid-generation continuity is a real product requirement.

Every AI fuature I have shipped in the past year — chat assistants, summarizers, report generators — streams its output token by token. Users will sit through a long generation when text appears immediately; they abandon a silent spinner much sooner. The streaming code itself has become short. The failure modes around it are what fill my notes.

What does it take to stream an AI response in Next.js?

One Route Handler and one hook. On the server, streamText from the AI SDK (Vercel's TypeScript toolkit for calling language models) starts the model call and returns immediately; toUIMessageStreamResponse() converts the result into a streaming Response that speaks the SDK's SSE-based UI message stream protocol. On the client, useChat from @ai-sdk/react POSTs the conversation, parses the stream, and re-renders as parts arrive.

// app/api/chat/route.ts
import { streamText, convertToModelMessages, type UIMessage } from "ai";

export const maxDuration = 300; // seconds — cap for long generations

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: "anthropic/claude-sonnet-4-6", // AI Gateway provider/model string
    messages: convertToModelMessages(messages),
    abortSignal: req.signal, // closed tab → cancel the model call
  });

  return result.toUIMessageStreamResponse();
}

"use client";
import { useChat } from "@ai-sdk/react";

export function Chat() {
  const { messages, sendMessage, stop, status } = useChat();
  // render messages; sendMessage({ text }) on submit; stop() aborts the stream
}

Two details matter on serverless. The function has to live as long as the generation, so I export a maxDuration from the route — on Vercel, Fluid Compute streams responses and the default execution cap is 300 seconds. And I pass the model as an AI Gateway provider/model string, which keeps switching providers a one-line change instead of a dependency swap.

Should I use SSE, WebSockets, or plain fetch streaming?

For streaming tokens from server to client, SSE format read over fetch is the right default, and it is what the AI SDK implements. Server-Sent Events (SSE) is a plain-HTTP wire format where the server writes data: lines down one long-lived response. WebSockets earn their place only when traffic is genuinely bidirectional — voice conversations, multiplayer cursors, collaborative editing. For a chat box they add connection state and infrastructure without buying anything.

The subtle point that took me a while to internalize: the browser's built-in EventSource API is not what chat apps use. EventSource can only issue GET requests and cannot attach a request body or custom headers, while a chat request needs to POST the conversation history. So the AI SDK sends a normal fetch POST and parses the SSE format off the response body with a ReadableStream reader. You get the SSE wire format without the EventSource limitations — at the cost of its automatic reconnection, which is exactly the gap resumable streams fill later.

Concern	fetch + SSE format	EventSource	WebSockets
Direction	Server → client	Server → client	Bidirectional
Request	Any method, body, headers	GET only, no body	Full duplex after upgrade
Reconnection	Manual (or resumable streams)	Automatic with Last-Event-ID	Manual
Serverless fit	Good	Good	Poor — needs a persistent connection
Best for	AI chat, token streams	Tickers, notifications	Voice, multiplayer, collab editing

Why does my stream work locally but arrive all at once in production?

Because something between your function and the browser is buffering. Compression middleware is the most common culprit: gzip and brotli want complete chunks to compress, so small token deltas sit in the compressor's buffer until the response ends and the stream arrives as one block. Reverse proxies are second: nginx's proxy_buffering collects the entire upstream response by default. Corporate proxies and some antivirus products do the same, and those are entirely outside your control.

// A raw streaming Response with buffering-hostile headers
return new Response(stream, {
  headers: {
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache, no-transform",
    "X-Accel-Buffering": "no", // tells nginx: do not buffer this response
  },
});

On Vercel, streaming responses pass through unbuffered out of the box, so I have only ever debugged this on self-hosted deployments — the classic broken case is Next.js behind an nginx config nobody has touched in a year. If you proxy through nginx, either send X-Accel-Buffering: no or disable proxy_buffering for the route, and exclude text/event-stream responses from any compression layer.

How do I stop paying for tokens nobody is reading?

Wire aborts end to end. The incoming Request carries an AbortSignal that fires when the user closes the tab, navigates away, or clicks stop (the useChat hook exposes a stop() that aborts the fetch). Passing it as streamText's abortSignal option propagates the cancellation to the model provider, which stops generating — and stops billing.

const result = streamText({
  model: "anthropic/claude-sonnet-4-6",
  messages: convertToModelMessages(messages),
  abortSignal: req.signal, // abort upstream on disconnect — saves tokens
});

// The opposite policy: finish the generation even if the client leaves,
// so onFinish can persist the complete message.
// result.consumeStream();

return result.toUIMessageStreamResponse({
  onFinish: async ({ messages }) => {
    await saveChat({ chatId, messages }); // completed messages survive refresh
  },
});

There is a genuine trade-off in that snippet. consumeStream() does the opposite of the abort signal: it detaches the generation from the client connection, so the model runs to completion and onFinish can persist the full message even after a disconnect. Abort-on-disconnect saves tokens but loses the partial response; consume-to-completion keeps the response but pays for every token. I wire the abort signal for cheap conversational chat and consume-plus-persist for expensive long-form generations. The mistake is choosing one policy globally instead of per feature.

What happens when the user refreshes mid-stream?

With the default setup, the fetch stream dies with the page, and if the abort signal is wired, the server-side generation dies with it. After the reload, the chat shows whatever onFinish had persisted: completed messages survive, the in-flight one vanishes. For most chat products I consider that acceptable — and more honest than pretending the message still exists somewhere.

When it is not acceptable — long report generations a user kicks off and checks back on — resumable streams close the gap. Chunks are published to a store such as Redis as they arrive, and a client that reconnects re-subscribes from where it left off, so the generation survives refreshes and network drops. The AI SDK supports this pattern, but it adds real infrastructure and operational state. My rule: persist finished messages always; add resumability only when a product requirement names it explicitly.

FAQ

Q: Do I need WebSockets to stream ChatGPT-style responses?

A: No. Token streaming is one-way, server to client, and SSE format over a fetch POST handles it on plain HTTP. WebSockets are for bidirectional traffic such as voice or collaborative editing.

Q: Why does my AI stream not work behind nginx?

A: nginx buffers upstream responses by default. Send X-Accel-Buffering: no on the response or disable proxy_buffering for the route, and make sure no compression layer re-buffers the stream.

Q: Does streaming work on serverless platforms like Vercel?

A: Yes. Vercel Functions stream responses, and Fluid Compute keeps the function alive for the whole generation — the default execution cap is 300 seconds, configurable per route with maxDuration.

Q: How do I save the AI message if the user closes the tab mid-stream?

A: Call consumeStream() on the server so the generation runs to completion and onFinish persists the full message. This conflicts with aborting to save tokens — each route picks one behavior.

Q: Can EventSource send a POST body?

A: No. EventSource issues GET requests only, with no body or custom headers, which is why AI chat clients read the SSE format from a fetch POST via a ReadableStream reader instead.

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

What Changed in Zod 4, and How I Migrated Production Schemas

Ahmed Mahmoud — Wed, 22 Jul 2026 06:01:49 +0000

Headline: Zod 4 is a rewrite of the TypeScript-first schema validation library, released as the stable major in 2025. Four changes hit my code directly: string formats moved to top-level functions (z.email() instead of z.string().email()), the four error options collapsed into one error parameter, error formatting moved to standalone helpers (z.flattenError, z.treeifyError, z.prettifyError), and .strict()/.passthrough() became z.strictObject()/z.looseObject(). The deprecated Zod 3 APIs still work with warnings, so I migrated incrementally.

Key takeaways

Zod 4 is the stable major of the TypeScript-first schema validator, released in 2025; it requires TypeScript 5.5 or newer.
String formats are now top-level tree-shakeable functions — z.email(), z.uuid(), z.url() — and z.string().email() is deprecated but still works.
A single error parameter replaces Zod 3's message, invalid_type_error, required_error, and errorMap.
Error formatting moved to z.flattenError (form fields), z.treeifyError (nested), and z.prettifyError (human-readable string).
The zod/mini build exposes the same validators through a functional, tree-shakeable API; z.infer, .parse(), and .safeParse() did not change.

I reach for Zod on almost every project to validate untrusted input at the boundary — request bodies, form data, environment variables, API responses. Zod 4 changed enough of the surface that a mechanical upgrade tripped a handful of files, so I mapped exactly what moved.

What actually changed in Zod 4?

Zod 4 is a ground-up rewrite of the TypeScript-first schema validation library, released as the stable major in 2025. The headline is performance: the Zod team's release notes report large reductions in TypeScript compiler instantiations and faster runtime parsing, which matters most in large codebases where schema types dominate type-check time. Four API changes touched my code directly — string formats moved to top-level functions, the four error options collapsed into one, error formatting moved to standalone helpers, and .strict()/.passthrough() became z.strictObject()/z.looseObject().

Why did z.string().email() become z.email()?

Zod 4 promotes string formats to standalone top-level functions — z.email(), z.uuid(), z.url(), and the ISO helpers under z.iso — instead of methods chained onto z.string(). The chained form still works but is deprecated and warns. The reason is tree-shaking: each format is its own function, so a bundle that only validates emails no longer ships the logic for every other format.

import * as z from "zod";

const User = z.object({
  id: z.uuid(),
  email: z.email(),
  website: z.url().optional(),
  age: z.number().int().min(18),
});

type User = z.infer<typeof User>;

How do I set custom error messages in Zod 4?

Zod 4 replaces four separate error options with a single error parameter. In Zod 3 you passed message, invalid_type_error, required_error, or a full errorMap. In Zod 4 you pass one error: a string for a fixed message, or a function that receives the issue and returns a message, letting you distinguish a missing value from a wrong type in one place.

// Zod 4: one error param — string or function
z.string({ error: "Name is required" });

z.string({
  error: (issue) =>
    issue.input === undefined ? "Name is required" : "Name must be text",
});

How do I turn a ZodError into form errors?

Zod 4 moves error formatting into three top-level helpers. z.flattenError(error) returns { formErrors, fieldErrors }, which maps onto a form's field-level messages. z.treeifyError(error) returns a nested object mirroring the schema shape. z.prettifyError(error) returns a human-readable multiline string for logs. The raw error.issues array is unchanged; error.format() and error.flatten() are deprecated in favor of these helpers.

const result = User.safeParse(await request.json());

if (!result.success) {
  const { fieldErrors } = z.flattenError(result.error);
  return Response.json({ errors: fieldErrors }, { status: 400 });
}

const user = result.data; // fully typed as User

When should I use zod/mini instead of the full zod package?

Use zod/mini when bundle size matters — client code, edge functions, a shipped widget — and the full zod package everywhere else. zod/mini exposes the same validators through a functional API: instead of chaining .optional() you wrap with z.optional(), and refinements use .check() rather than .refine(). It is more verbose, but with no method chain, unused code tree-shakes away. Both builds share the same core, so runtime behavior is identical.

import * as z from "zod/mini";

const User = z.object({
  email: z.email(),
  name: z.optional(z.string()),
});

Concern	zod (full)	zod/mini
API style	Chained methods (`.optional()`)	Functional wrappers (`z.optional()`)
Bundle size	Larger	Smaller, tree-shakeable
Ergonomics	Fluent, readable	More verbose
Same validators	Yes	Yes (same core)
Best for	Servers, general code	Edge/client, size-critical bundles

How do I migrate from Zod 3 without breaking everything?

Migrate incrementally, because Zod 4 keeps the deprecated Zod 3 APIs working with warnings rather than removing them. During the transition Zod published the new version under the zod/v4 import path (in zod@3.25) so you could adopt it file by file before zod@4.0; the legacy API stays reachable at zod/v3. My process: upgrade the package, run the type-checker and tests, then clear deprecation warnings in waves — rename string-format calls, collapse error options into error, and switch .strict()/.passthrough() to the new object functions. z.infer, .parse(), and .safeParse() did not change, so most schemas kept working untouched.

FAQ

Q: Is z.string().email() removed in Zod 4?
A: No. It still works but is deprecated and warns. The recommended form is the top-level z.email(), and both validate identically.

Q: What replaced errorMap and invalid_type_error in Zod 4?
A: A single error parameter — a string for a fixed message or a function that receives the issue for conditional messages.

Q: How do I get field-level errors for a form in Zod 4?
A: Call z.flattenError(error); its fieldErrors maps each schema key to its messages. Use z.treeifyError for nested shapes.

Q: Is zod/mini a separate library?
A: No. It is a build of Zod 4 with the same validators exposed through a functional, tree-shakeable API for smaller bundles.

Q: Does Zod 4 require a specific TypeScript version?
A: Yes. Zod 4 requires TypeScript 5.5 or newer.

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