DEV Community: Waseem Anjum

Zod vs Valibot vs ArkType for MCP Tool Schemas

Waseem Anjum — Sat, 07 Nov 2026 06:14:45 +0000

Cross-posted from my blog. The original, with any updates, lives on fabwaseem.com.

When I built the NestJS MCP server earlier this week, I used Zod for the tool schemas without thinking about it, because every SDK example does. Then I noticed the v2 TypeScript SDK types inputSchema as "any Standard Schema that can also emit JSON Schema", and the docstring names Zod 4, Valibot and ArkType. So today I wrote the same tool schema in all three, registered them on one MCP server, and measured what actually changes.

Short version: all three work. The differences that mattered were in the JSON Schema the model sees, how each one treats a datetime with a +05:00 offset, cold start, bundle size, and one ArkType setting that made the same schema about 18x slower.

What I ran

Everything is on one shared 8 vCPU Xeon VM with 16 GB, on November 7, 2026:

Node.js 24.22.1
zod 4.6.7, valibot 1.5.0 with @valibot/to-json-schema 1.8.0, arktype 2.2.9
@modelcontextprotocol/server and @modelcontextprotocol/client 2.4.0, connected with InMemoryTransport
tinybench 6.2.3 for the parse numbers, esbuild 0.28.2 for bundle sizes

Load average sat around 0.7 to 1.7 during the runs. It's a shared box, so treat the numbers as relative, not absolute.

One tool, three schemas

The tool is a create_task with a title, optional body, a priority enum with a default, a tag list with a default, an optional due date and an optional assignee email. That's roughly what my real tools look like: a few strings with limits, an enum, an array, and two formats.

import * as z from "zod";

export const zodTask = z.object({
  title: z.string().min(1).max(120),
  body: z.string().max(5000).optional(),
  priority: z.enum(["low", "normal", "high"]).default("normal"),
  tags: z.array(z.string().max(30)).max(10).default([]),
  dueAt: z.iso.datetime().optional(),
  assigneeEmail: z.email().optional(),
});

import * as v from "valibot";
import { toStandardJsonSchema } from "@valibot/to-json-schema";

const valibotTaskRaw = v.object({
  title: v.pipe(v.string(), v.minLength(1), v.maxLength(120)),
  body: v.optional(v.pipe(v.string(), v.maxLength(5000))),
  priority: v.optional(v.picklist(["low", "normal", "high"]), "normal"),
  tags: v.optional(v.pipe(v.array(v.pipe(v.string(), v.maxLength(30))), v.maxLength(10)), []),
  dueAt: v.optional(v.pipe(v.string(), v.isoTimestamp())),
  assigneeEmail: v.optional(v.pipe(v.string(), v.email())),
});

// Plain Valibot schemas don't carry ~standard.jsonSchema, so wrap them.
export const valibotTask = toStandardJsonSchema(valibotTaskRaw);

import { type } from "arktype";

export const arkTask = type({
  title: "1 <= string <= 120",
  "body?": "string <= 5000",
  priority: type("'low' | 'normal' | 'high'").default("normal"),
  tags: type("(string <= 30)[] <= 10").default(() => []),
  "dueAt?": "string.date.iso",
  "assigneeEmail?": "string.email",
});

Registering them is the same call for all three:

import { McpServer, InMemoryTransport } from "@modelcontextprotocol/server";
import { Client } from "@modelcontextprotocol/client";

const server = new McpServer({ name: "tasks", version: "1.0.0" });
for (const [name, schema] of [["zod", zodTask], ["valibot", valibotTask], ["arktype", arkTask]] as const) {
  server.registerTool(
    `create_task_${name}`,
    { description: `Create a task (${name})`, inputSchema: schema },
    async (args) => ({ content: [{ type: "text", text: JSON.stringify(args) }] }),
  );
}

const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
await server.connect(serverSide);
const client = new Client({ name: "test", version: "1.0.0" });
await client.connect(clientSide);
console.log((await client.listTools()).tools);

The one Valibot gotcha: if you pass valibotTaskRaw directly, registerTool accepts it without complaint. The error only shows up later, when a client calls tools/list:

Schema library "valibot" does not implement StandardJSONSchemaV1 (`~standard.jsonSchema`). Upgrade to a version that does, or wrap your JSON Schema with fromJsonSchema().

So a server that boots fine can still be broken for every client. The fix is the toStandardJsonSchema() wrap above. Zod 4.2+ and ArkType 2.2 have ~standard.jsonSchema built in. I'd add a test that calls listTools() once, so this fails in CI instead of in front of a user.

What the model sees in tools/list

This is the part I care about most for MCP, because the JSON Schema is what the LLM reads when it decides how to call your tool. The SDK asks every library for draft 2020-12 and stamps type: "object" on the root.

Same fields, three different outputs:

Field	Zod 4.6.7	Valibot 1.5.0	ArkType 2.2.9
`priority`	enum + `type: "string"` + `default: "normal"`	enum + `type: "string"` + `default: "normal"`	enum only, sorted alphabetically, no default
`tags`	`maxItems`, items, `default: []`	`maxItems`, items, `default: []`	`maxItems`, items, no default
`dueAt`	`format: "date-time"` + a long regex `pattern`	`format: "date-time"`	ISO 8601 regex `pattern`, no `format`
`assigneeEmail`	`format: "email"` + regex	`format: "email"`	`format: "email"` + regex

Valibot gave the cleanest schema. Zod's is correct but the datetime regex is about 400 characters of noise in every tools/list response. ArkType dropping the defaults surprised me. The model has no way to know priority falls back to "normal", so it'll either guess or always send it. If your tool descriptions rely on defaults, put them in .describe() text as well.

Validation errors the model gets back

When a call fails validation, the SDK returns isError: true with the issues joined into one string. I sent title: "", priority: "urgent", 11 tags and assigneeEmail: "nope":

zod:     title: Too small: expected string to have >=1 characters, priority: Invalid option: expected one of "low"|"normal"|"high", tags: Too big: expected array to have <=10 items, assigneeEmail: Invalid email address
valibot: title: Invalid length: Expected >=1 but received 0, priority: Invalid type: Expected ("low" | "normal" | "high") but received "urgent", tags: Invalid length: Expected <=10 but received 11, assigneeEmail: Invalid email: Received "nope"
arktype: title: title must be non-empty, tags: tags must be at most length 10 (was 11), priority: priority must be "high", "low" or "normal" (was "urgent"), assigneeEmail: assigneeEmail must be an email address (was "nope")

All three are good enough for a model to fix its own call. ArkType's read most like English. Valibot and ArkType echo the bad value back, which helps when the model sent something weird.

The datetime trap

I'm in Pakistan (UTC+5), so the first thing I tried was local time with an offset, which is what I'd expect an assistant to send for someone here. Five strings in total:

Input	Zod `z.iso.datetime()`	Valibot `isoTimestamp()`	ArkType `string.date.iso`
`2026-11-07T11:00:00Z`	pass	pass	pass
`2026-11-07T11:00:00+05:00`	fail	pass	pass
`2026-11-07`	fail	fail	pass
`2026-11-07T11:00Z`	fail	fail	pass
`next friday`	fail	fail	fail

Zod's datetime only accepts Z unless you opt in. I'd have shipped that bug without this test:

dueAt: z.iso.datetime({ offset: true }).optional(),

ArkType goes the other way. string.date.iso is any ISO 8601 date, so a bare date passes. If the tool needs a full timestamp, that's the wrong keyword and you need your own pattern.

Parse speed, and the ArkType clone setting

First run, the full task schema with a valid input, then an invalid one, calling each library's normal parse (safeParse, v.safeParse, arkTask(x)):

	valid input, mean	invalid input, mean
Zod	679 ns	1,612 ns
Valibot	710 ns	1,149 ns
ArkType	4,914 ns	11,634 ns

That's the opposite of ArkType's reputation, so I split the schema apart. With no defaults and no formats, ArkType was the fastest by far: 71 ns against Zod's 295 ns and Valibot's 453 ns. Adding the email check took it to 123 ns. Adding .default() on any single field took it to about 4,900 ns.

The cause is cloning. When a schema has morphs (and defaults count), ArkType clones the input before applying them so your original object isn't mutated. You can turn that off:

// arktype.config.ts, imported before anything that imports "arktype"
import { configure } from "arktype/config";
configure({ clone: false });

With clone: false the default-only schema ran at 55 ns, and the full task schema at 270 ns, which includes about 47 ns for the { ...good } spread I added so each call got a fresh object. The trade-off is real: with cloning off, ArkType writes priority: "normal" into the object you passed in. I checked, and the returned value is the same object as the input. For MCP tool args I'm fine with that, since the args object comes straight from the parsed request. I ran the ArkType tool through the MCP client again with clone: false and the handler still got {"title":"x","tags":[],"priority":"normal"}. For shared config objects I'd leave cloning on.

To be fair, even 5 µs per tool call doesn't matter next to an LLM round trip. I only went looking because the number looked wrong.

Cold start and bundle size

Cold start matters more to me than parse speed, because my MCP servers on Vercel are stateless and build a fresh server per request. I timed import plus first parse in a fresh Node process, 21 runs each, median:

	import + first parse
Valibot	5.8 ms
Zod	43.7 ms
ArkType	159.6 ms

Bundle size, esbuild --bundle --minify --format=esm --platform=browser, entry imports one schema and calls parse once:

	minified	gzip
Valibot	5.3 KB	2.0 KB
Valibot + `@valibot/to-json-schema`	19.2 KB	5.3 KB
Zod Mini (`zod/mini`)	20.9 KB	7.1 KB
Zod	85.4 KB	25.1 KB
ArkType	156.4 KB	47.6 KB

Zod and ArkType include JSON Schema output already, so adding the conversion call barely changed their size. Valibot needs the extra package, and it's still the smallest. On a server none of these sizes matter much, but the cold start difference follows the same order.

What I'm doing in my own MCP servers

I'm keeping Zod in the NestJS server. It's what the MCP and AI SDK examples use, its JSON Schema output was accurate here, and I already know its quirks. Any datetime field I add there gets { offset: true } from now on.

For the next serverless MCP endpoint I build, I'll try Valibot. It had the cleanest tools/list output and the fastest cold start, and the only extra step is one toStandardJsonSchema() wrap.

ArkType I'd pick for hot validation paths outside MCP, where the defaults-clone cost is easy to turn off and I don't care what JSON Schema it emits. For MCP tools specifically, the missing defaults in tools/list put me off.

I only tested one schema shape on one VM. If your schemas are mostly nested unions or recursive types, the order could change, and I'd like to hear what you see. The scripts are small enough to rerun in a few minutes. If you're testing your own server end to end, my notes on testing an MCP server and MCP security cover the rest of what I check before shipping.

FAQ

Can I use Valibot or ArkType instead of Zod for MCP tool schemas?

Yes. The MCP TypeScript SDK v2 (I tested @modelcontextprotocol/server 2.4.0) accepts any Standard Schema that also implements ~standard.jsonSchema. Zod 4.2+ and ArkType 2.2 do this out of the box. Valibot needs toStandardJsonSchema() from @valibot/to-json-schema.

Why does my Valibot MCP tool fail at tools/list?

A plain Valibot schema has no ~standard.jsonSchema, so the SDK can't turn it into JSON Schema. registerTool accepts it, but tools/list throws 'Schema library "valibot" does not implement StandardJSONSchemaV1'. Wrap the schema with toStandardJsonSchema().

Why is ArkType slower than Zod in my benchmark?

In my test ArkType was the fastest on a schema without defaults (71 ns vs Zod 295 ns), but any .default() made it clone the input first, which pushed a parse to about 4.9 microseconds. configure({ clone: false }) from arktype/config brought the full schema to 270 ns, at the cost of mutating the input object.

Does Zod accept ISO datetimes with a timezone offset?

Not by default. In Zod 4.6.7, z.iso.datetime() accepted 2026-11-07T11:00:00Z but rejected 2026-11-07T11:00:00+05:00. Use z.iso.datetime({ offset: true }) if clients or LLMs may send local times.

Which validation library has the smallest bundle?

Valibot. In my esbuild test the task schema bundled to 2.0 KB gzip with Valibot (5.3 KB with JSON Schema conversion), 7.1 KB with zod/mini, 25.1 KB with Zod and 47.6 KB with ArkType.

Originally published on fabwaseem.com.

NestJS Rate Limiting: In-Memory vs Redis vs Postgres

Waseem Anjum — Fri, 06 Nov 2026 06:18:16 +0000

Cross-posted from my blog. The original, with any updates, lives on fabwaseem.com.

I shipped a NestJS API with the default @nestjs/throttler storage last year and only noticed the hole when we ran two instances behind a load balancer. Each process kept its own counter, so a client that should have been cut off at 100 requests in a minute quietly got closer to 200. Today I re-tested that on NestJS 12 with three storages on the same box: in-memory, Redis, and Postgres.

What I tested

Everything ran on one 8 vCPU / 16 GB Linux VM on November 6, 2026:

Node.js 24.22.1, NestJS 12.3.3, @nestjs/throttler 6.7.1
Redis 7.2.11 with persistence off, via @nestjs-redis/throttler-storage 2.0.1 and the redis 5.12.1 client
PostgreSQL 18.6 with a small custom storage that upserts into one throttler_hits table
Limit: 100 requests / 60 seconds, tracker keyed on x-forwarded-for so localhost tests don't all share 127.0.0.1

I measured three things: p50/p95 latency of allowed requests, whether request 101 returns 429, and whether two Nest processes behind the same storage still stop at 100 total.

If you're comparing Nest to thinner frameworks, I wrote about Hono vs Express and the NestJS 12 upgrade separately. Redis vs Postgres as infrastructure shows up again in my pg-boss vs BullMQ and BullMQ pipeline posts.

Wiring `@nestjs/throttler`

The default setup is tiny. Global guard, one named throttler:

ThrottlerModule.forRoot({
  throttlers: [{ name: 'default', ttl: seconds(60), limit: 100 }],
  getTracker: async (req) => {
    const xf = req.headers['x-forwarded-for'];
    if (typeof xf === 'string' && xf.length) return xf.split(',')[0].trim();
    return req.ip;
  },
}),
// providers: [{ provide: APP_GUARD, useClass: ThrottlerGuard }]

That uses the built-in in-memory storage. Fine for a single process. Wrong the moment you scale out.

Redis storage

I used @nestjs-redis/throttler-storage, which implements ThrottlerStorage with a Lua script so the increment is atomic:

const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

ThrottlerModule.forRoot({
  throttlers: [{ name: 'default', ttl: seconds(60), limit: 100 }],
  storage: new RedisThrottlerStorage(redis),
  getTracker: /* same as above */,
});

Pass an existing client. The package does not manage connect/disconnect for you.

Postgres storage (custom)

There isn't an official Nest Postgres throttler storage, so I wrote one. One row per key, upsert that resets when the window expires:

CREATE TABLE throttler_hits (
  key text PRIMARY KEY,
  hits integer NOT NULL DEFAULT 0,
  expires_at timestamptz NOT NULL,
  is_blocked boolean NOT NULL DEFAULT false,
  block_expires_at timestamptz
);

// inside increment():
INSERT INTO throttler_hits (key, hits, expires_at)
VALUES ($1, 1, now() + ($2 || ' milliseconds')::interval)
ON CONFLICT (key) DO UPDATE SET
  hits = CASE WHEN throttler_hits.expires_at <= now() THEN 1
              ELSE throttler_hits.hits + 1 END,
  expires_at = CASE WHEN throttler_hits.expires_at <= now()
                    THEN now() + ($2 || ' milliseconds')::interval
                    ELSE throttler_hits.expires_at END
RETURNING hits, expires_at, is_blocked, block_expires_at;

I wrap that in a transaction and set is_blocked when hits > limit, matching how the in-memory storage behaves. No SKIP LOCKED here: a single-row upsert is enough for a counter. SKIP LOCKED is the pattern I use for job claiming, not for rate-limit tallies.

Latency (allowed requests)

Eighty requests under the limit, median of three runs. Raw Node http with no Nest is the baseline.

Storage	p50 (ms)	p95 (ms)
none (raw http)	0.34	0.57
memory	0.36	0.64
redis	0.38	0.81
postgres	1.00	1.42

On localhost, memory and Redis are basically free. Postgres adds about 0.6 ms at p50 versus the raw baseline. That is one round trip plus the upsert. Across a network to a remote Postgres the gap will be larger; across a network to Redis it will grow too, just usually less.

Reject correctness

Single process, LIMIT + 20 requests with the same client IP:

Storage	200s	429s	First 429 at request #
memory	100	20	101
redis	100	20	101
postgres	100	20	101

All three cut off exactly after 100. So the bug is not "throttler is wrong". The bug is sharing.

Multi-instance correctness

Two Nest processes, same Redis or Postgres (or none for memory), alternating requests for the same IP, LIMIT + 30 = 130 total:

Storage	Allowed	Blocked	Shared limit held?
memory	130	0	No
redis	100	30	Yes
postgres	100	30	Yes

Memory allowed every request. Each process only saw 65 hits, both under 100. That is the load-balancer failure mode. Redis and Postgres stopped at 100 total across both processes.

What I'd pick

One instance, local or edge: in-memory. Lowest moving parts. Don't pretend it will survive a second replica.
Already running Redis (BullMQ, cache, sessions): use @nestjs-redis/throttler-storage. Latency matched memory on this box and shared correctly.
Postgres only, no Redis: the custom upsert storage works. Expect roughly a millisecond of overhead on localhost, more over the network. Keep the table tiny and index-free beyond the primary key.

I would not put rate-limit counters in the same hot transactional tables as orders or payments. A dedicated table (or Redis) keeps the lock footprint small.

One caveat: this is one machine, client and storage on localhost, Nest 12.3.3, throttler 6.7.1. It answers "does shared storage actually share" and "how much does each storage add on this box". It does not answer global multi-region limits or abuse at the CDN layer. Put a WAF or edge limit in front when that matters.

If you only remember one number from today: memory let 130 through where Redis and Postgres stopped at 100. That is the whole reason to change the storage.

FAQ

Does NestJS @nestjs/throttler work across multiple instances?

Only if you swap the default in-memory storage for a shared one. With two Nest processes and a limit of 100, in-memory allowed all 130 alternating requests in my test because each process only saw 65. Redis and Postgres both stopped at 100 total.

What Redis storage should I use with @nestjs/throttler?

I used @nestjs-redis/throttler-storage 2.0.1 with the redis 5.x client on NestJS 12. You pass an existing Redis client; the package runs the increment in a Lua script so it stays atomic.

Can I store NestJS rate limits in Postgres?

Yes, with a custom ThrottlerStorage. I used a single throttler_hits table and an INSERT ... ON CONFLICT upsert that resets hits when the TTL window expires. On localhost it added about 0.6 ms at p50 versus a raw HTTP baseline.

How much latency does NestJS rate limiting add?

On one 8 vCPU box with localhost storage, allowed-request p50 was 0.36 ms for in-memory, 0.38 ms for Redis 7.2.11, and 1.00 ms for PostgreSQL 18.6, against a 0.34 ms raw HTTP baseline. Remote Redis or Postgres will cost more.

Is in-memory rate limiting OK for production NestJS?

It is fine for a single instance. The moment you run two replicas behind a load balancer, each keeps its own counter, so clients can exceed the limit. Switch to Redis or Postgres (or an edge/WAF limit) before you scale out.

Originally published on fabwaseem.com.

Run TypeScript in Node.js Without a Build Step: Type Stripping Tested on Node 22, 24 and 26

Waseem Anjum — Wed, 04 Nov 2026 18:23:40 +0000

Cross-posted from my blog. The original, with any updates, lives on fabwaseem.com.

You can now run a .ts file with plain node app.ts, no tsx, no ts-node, no build step. Type stripping has been on by default since Node.js 22.18.0 and 23.6.0, and it became stable in Node.js 24.12.0 and 25.2.0. On Node.js 26 LTS it is simply how Node works.

But "Node runs TypeScript" has sharp edges. Enums fail. Parameter properties fail. Decorators fail. Imports without .ts fail. And Node never checks your types. I tested every one of these on Node.js 22.20.0, 24.22.2 and 26.13.0, and this post shows the exact errors, the tsconfig.json that catches all of them before runtime, and how startup time compares to tsx and precompiled JavaScript.

How Node.js type stripping works

Node replaces TypeScript type annotations with whitespace and runs what is left as JavaScript. It does not type-check, it ignores tsconfig.json, and it only accepts erasable syntax: TypeScript that disappears completely when you delete the types.

From the Node.js TypeScript docs history table:

Node.js version	Change
v22.6.0	Type stripping added behind `--experimental-strip-types`
v23.6.0, v22.18.0	Enabled by default
v24.3.0, v22.18.0	No more experimental warning
v24.12.0, v25.2.0	Marked Stable
v26.0.0	`--experimental-transform-types` flag removed

You can check it at runtime: node -p "process.features.typescript" printed strip on all three versions I tested.

What works out of the box

This file ran unchanged with node ok.ts on Node 22.20, 24.22 and 26.13:

// ok.ts
interface User { id: number; name: string }
type Role = 'admin' | 'user';
import type { Stats } from 'node:fs';
import { greet } from './util.ts';

const u: User = { id: 1, name: 'Waseem' };
const role: Role = 'admin';
function size<T>(xs: T[]): number { return xs.length; }
const s = undefined as Stats | undefined;

console.log(greet(u.name), role, size([1, 2, 3]), s);
// hi Waseem admin 3 undefined

Interfaces, type aliases, generics, as casts, import type and annotated functions are all erasable, so they just work. Add "type": "module" to package.json; without it, Node prints a MODULE_TYPELESS_PACKAGE_JSON warning and reparses the file as ESM.

What fails (tested on Node 22, 24 and 26)

All three versions gave the same result for every case below.

TypeScript feature	What Node prints
`enum Color { Red, Green }`	`SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode`
`namespace A { export const x = 1 }`	`SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript namespace declaration is not supported in strip-only mode`
`constructor(public name: string)`	`SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript parameter property is not supported in strip-only mode`
`import { greet } from './util'`	`Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../util'`
`import { User } from './types.ts'` (User is an interface)	`SyntaxError: The requested module './types.ts' does not provide an export named 'User'`
`@log class K {}`	`SyntaxError: Invalid or unexpected token`
A `.tsx` file	`TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".tsx"`
A `.ts` file inside `node_modules`	`Error [ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING]`

Three of these surprise people the most:

Type-only imports must say import type. Node removes the type but keeps the import statement, so it looks for a runtime export called User and crashes.
Decorators don't run. That means NestJS, TypeORM entities and anything with @Injectable() still needs a compile step or a loader like tsx or SWC.
Packages can't ship raw .ts. Node refuses to strip types under node_modules, so libraries still need to publish JavaScript.

`--experimental-transform-types` is gone in Node 26

On Node 24, node --experimental-transform-types enum.ts ran the enum (with an ExperimentalWarning). On Node 26.13.0 the same command printed:

node: bad option: --experimental-transform-types

If you relied on that flag for enums, Node 26 is the point where you have to remove them or go back to a loader.

The tsconfig.json that catches every failure

Node ignores tsconfig.json, but your editor and tsc don't. With this config, tsc flagged every runtime failure above (except decorators, see below) before I ran anything:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "strict": true,
    "skipLibCheck": true
  }
}

Output from tsc -p . with TypeScript 5.9.3:

enum.ts(1,6): error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.
ns.ts(1,11): error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.
paramprop.ts(1,23): error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.
noext.ts(1,23): error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'.
typeimport.ts(1,10): error TS1484: 'User' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled.

What each option does:

erasableSyntaxOnly (TypeScript 5.8+) errors on enums, namespaces and parameter properties.
verbatimModuleSyntax forces import type for type-only imports.
allowImportingTsExtensions lets you write ./util.ts, which is what Node needs. It requires noEmit (or rewriteRelativeImportExtensions if you also emit).
module: nodenext makes tsc require file extensions like Node does.

The gap: decorators. TypeScript 5.9 accepts standard decorators, so tsc passed dec.ts, but Node 26 still threw a SyntaxError. If your code uses decorators, keep a build step for that code.

Run tsc --noEmit in CI and in a pre-commit hook. Node won't check types for you.

Replacing enums

The usual erasable replacement is a const object plus a type:

export const Color = { Red: 0, Green: 1 } as const;
export type Color = (typeof Color)[keyof typeof Color];

Startup time: node vs tsx vs precompiled JS

Same ok.ts (two small files), Node 26.13.0, 30 interleaved runs each, wall time for the whole process:

How it ran	Median	p90
`node js/ok.js` (precompiled with `tsc`)	27.7 ms	33.0 ms
`node ok.ts` (type stripping)	62.6 ms	67.2 ms
`tsx ok.ts` (tsx 4.23.15)	116.9 ms	128.5 ms

Built-in stripping was about half the startup time of tsx, but about 35 ms slower than running precompiled JavaScript on this machine. For scripts, CLIs, dev servers and tests that difference doesn't matter. For a serverless function where cold start counts, shipping compiled JavaScript is still faster.

When to use built-in type stripping

Use node file.ts for:

Scripts, seeds, migrations and one-off tools
CLIs and internal services you control end to end
Running tests with node --test on .ts files
Dev mode with node --watch src/server.ts

Keep a build step (tsc, SWC, esbuild or tsx) for:

NestJS and anything else that uses decorators
React and .tsx files
Libraries you publish to npm
Code that relies on paths aliases in tsconfig.json (Node ignores them)
Serverless functions where cold start matters

If you're upgrading Node at the same time, see Node 24 vs Node 26 for the other breaking changes, and TypeScript 7 for where the TypeScript compiler itself is going.

FAQ

Can Node.js run TypeScript directly?

Yes. Since Node.js 22.18.0 and 23.6.0, node file.ts works without a flag, and the feature is marked stable from Node.js 24.12.0 and 25.2.0. Node only strips types; it does not type-check and it does not support enums, namespaces, parameter properties or decorators.

Does Node.js type stripping check types?

No. Node replaces types with whitespace and runs the result. A file with type errors runs fine as long as the JavaScript is valid. Run tsc --noEmit separately to check types.

Why does my enum fail in Node.js?

Enums generate runtime code, so they aren't erasable. Node prints ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX: TypeScript enum is not supported in strip-only mode. Replace them with a const object and a union type, and turn on erasableSyntaxOnly so tsc warns you.

Is --experimental-transform-types available in Node 26?

No. It was removed in Node.js 26.0.0. On Node 26.13.0 the flag fails with bad option: --experimental-transform-types. It still works with a warning on Node 24.

Do I still need tsx or ts-node?

Only for code that uses non-erasable syntax, decorators, .tsx, or tsconfig paths. For plain erasable TypeScript, node is enough and started about twice as fast as tsx in my test.

Why do I need .ts in import paths?

Node resolves files exactly like it does for JavaScript ESM: no extension guessing. import './util' fails with ERR_MODULE_NOT_FOUND; write import './util.ts' and enable allowImportingTsExtensions in tsconfig.json.

Originally published on fabwaseem.com.

NestJS vs Hono vs Fastify (2026): Benchmarked on Node.js 26

Waseem Anjum — Wed, 04 Nov 2026 18:23:34 +0000

Cross-posted from my blog. The original, with any updates, lives on fabwaseem.com.

"NestJS vs Hono vs Fastify" is one of the most common backend questions I see from TypeScript developers in 2026, and most answers are either opinion or benchmarks from 2023. So I ran my own: the same three routes on Express 5.3, Fastify 5.12, Hono 4.13, NestJS 12.3 on Express and NestJS 12.3 on Fastify, all on Node.js 26.13 (the current LTS), on the same machine, with the same load generator.

This post gives you the numbers, the exact code, and a straight answer on which one to pick for an API, a SaaS backend or an edge function.

The test setup

Machine: one 8-vCPU Intel Xeon Linux VM. The server was pinned to one CPU core with taskset -c 0 (Node runs your JavaScript on one thread, so this is a fair per-process number). The load generator, autocannon 8, ran on 6 other cores.
Runtime: Node.js v26.13.0.
Versions: express 5.3.0, fastify 5.12.8, hono 4.13.16 with @hono/node-server 2.1.6, @nestjs/core 12.3.3 with @nestjs/platform-express and @nestjs/platform-fastify 12.3.3. NestJS was compiled with TypeScript 5.9.3.
Load: 100 connections, no pipelining, 3-second warm-up, then 8 seconds per route.
Rounds: 3 full rounds, run one framework after another (interleaved), and I report the median of the 3.
Routes:
- GET /json returns {"hello":"world"}
- GET /users/:id returns the route parameter as JSON
- POST /echo parses a small JSON body and sends it back

No logging, no validation, no database. This measures framework overhead only. Every request returned 2xx.

The code

Express 5:

import express from 'express';
const app = express();
app.use(express.json());
app.get('/json', (req, res) => res.json({ hello: 'world' }));
app.get('/users/:id', (req, res) => res.json({ id: req.params.id }));
app.post('/echo', (req, res) => res.json(req.body));
app.listen(3000);

Fastify 5:

import Fastify from 'fastify';
const app = Fastify({ logger: false });
app.get('/json', async () => ({ hello: 'world' }));
app.get('/users/:id', async (req) => ({ id: req.params.id }));
app.post('/echo', async (req) => req.body);
await app.listen({ port: 3000 });

Hono 4 on Node.js:

import { Hono } from 'hono';
import { serve } from '@hono/node-server';
const app = new Hono();
app.get('/json', (c) => c.json({ hello: 'world' }));
app.get('/users/:id', (c) => c.json({ id: c.req.param('id') }));
app.post('/echo', async (c) => c.json(await c.req.json()));
serve({ fetch: app.fetch, port: 3000 });

NestJS 12 (one file, the adapter is picked by an env variable):

import 'reflect-metadata';
import { Body, Controller, Get, Module, Param, Post } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { FastifyAdapter } from '@nestjs/platform-fastify';

@Controller()
class AppController {
  @Get('json') json() { return { hello: 'world' }; }
  @Get('users/:id') user(@Param('id') id: string) { return { id }; }
  @Post('echo') echo(@Body() body: unknown) { return body; }
}

@Module({ controllers: [AppController] })
class AppModule {}

async function bootstrap() {
  const app = process.env.ADAPTER === 'fastify'
    ? await NestFactory.create(AppModule, new FastifyAdapter(), { logger: false })
    : await NestFactory.create(AppModule, { logger: false });
  await app.listen(3000);
}
bootstrap();

Results: requests per second (one core, higher is better)

Framework	GET /json	GET /users/:id	POST /echo
Fastify 5.12	85,448	82,040	59,746
Hono 4.13 (Node)	83,184	80,728	51,192
NestJS 12 + Fastify	70,082	69,010	48,596
Express 5.3	48,564	45,476	32,969
NestJS 12 + Express	43,844	39,340	29,563

Median of 3 rounds. Latency was low for all of them at this load: p50 was 1-3 ms and p99 was 2-11 ms. The highest p99 (11 ms) was NestJS on Express for POST /echo.

Results: startup time and memory

Framework	Start to first 200	RSS idle	RSS after load
Hono 4.13	90 ms	65.6 MB	110.5 MB
Express 5.3	115 ms	66.9 MB	115.7 MB
Fastify 5.12	158 ms	73.8 MB	116.5 MB
NestJS 12 + Fastify	404 ms	104.9 MB	136.2 MB
NestJS 12 + Express	486 ms	105.2 MB	149.9 MB

"Start" is the time from spawning the process to the first successful response, polled every 5 ms.

What the numbers say

1. Fastify and Hono are close; Express is roughly half as fast. On simple GET routes Fastify and Hono were within 3% of each other. Both did about 1.7-1.8x the requests of Express 5. Express 5 is a big cleanup (async errors, better path matching), but it did not change the performance picture.

2. Fastify wins on JSON bodies. On POST /echo, Fastify did 17% more requests than Hono (59,746 vs 51,192). Fastify has its own body parser and a compiled serializer path. Hono on Node goes through the Web Request adapter in @hono/node-server, and c.req.json() pays for that.

3. NestJS costs you about 16-19% on Fastify, and the adapter matters more than the framework. NestJS on Fastify kept 81-84% of raw Fastify's throughput on every route. NestJS on Express kept 87-90% of raw Express. But NestJS + Fastify was 60-75% faster than NestJS + Express on GET routes. If you already run NestJS, switching the adapter is the cheapest performance win you have.

4. NestJS starts 3-5x slower and uses ~40 MB more memory. That's the DI container, the module scan and reflect-metadata. It does not matter for a long-running API. It does matter for serverless cold starts and for scale-to-zero containers.

5. Hono starts fastest and uses the least memory. 90 ms and 65.6 MB idle. Add the fact that the same Hono app runs on Cloudflare Workers, Bun, Deno and Vercel, and it is the best default for small services and edge functions.

Caveats (read these before quoting the numbers)

This is framework overhead with trivial handlers. A real handler that hits Postgres for 2-5 ms will flatten these differences. At 30,000+ requests per second per core, the framework is rarely your bottleneck.
One VM, one core per server, 100 connections. Your hardware will give different absolute numbers; the ranking is what to take away.
Express used express.json(); Fastify and Nest used their default parsers. No schemas, so Fastify's schema-based serialization was not used. Fastify can serialize faster with a response schema; I did not test that here.
Hono was tested on Node.js through @hono/node-server. Hono on Bun or Workers is a different test.

Which one should you choose?

If you are building...	Pick	Why
A large team API with modules, DI, guards, OpenAPI	NestJS on the Fastify adapter	Structure and conventions; the Fastify adapter kept 81-84% of raw Fastify speed here
A high-throughput Node.js JSON API	Fastify	Fastest here, especially on POST bodies; mature plugin ecosystem
Edge functions, Workers, multi-runtime code, small services	Hono	Near-Fastify speed on Node, fastest startup, smallest memory, runs everywhere
An existing Express app	Stay on Express 5 unless you have a measured performance problem	Migration cost is real; the gap only matters at high load

My own default: Hono for small services and anything that might run on the edge, NestJS with Fastify when a SaaS backend needs structure and several developers. I covered the Express side in more depth in Hono vs Express, and what changed in NestJS itself in NestJS 12.

How to reproduce

Install the same versions, start each server pinned to one core, and run autocannon:

npm i hono@4.13.16 @hono/node-server@2.1.6 fastify@5.12.8 express@5.3.0 \
  @nestjs/core@12.3.3 @nestjs/common@12.3.3 @nestjs/platform-express@12.3.3 \
  @nestjs/platform-fastify@12.3.3 reflect-metadata rxjs autocannon@8

taskset -c 0 node fastify.mjs &
npx autocannon -c 100 -d 8 http://127.0.0.1:3000/json
npx autocannon -c 100 -d 8 -m POST -H content-type=application/json \
  -b '{"name":"Waseem","tags":["a","b","c"],"n":7}' http://127.0.0.1:3000/echo

Run each framework a few times, alternate the order, and use the median.

FAQ

Is Hono faster than Fastify?

Not on Node.js in my test. On simple GET routes they were within 3% (Fastify 85,448 vs Hono 83,184 requests per second on one core). On a JSON POST body Fastify was 17% faster. Hono started faster (90 ms vs 158 ms) and used less memory.

Is NestJS slower than Express?

NestJS adds overhead on top of whatever adapter it uses. NestJS on Express did about 10% fewer requests than plain Express on GET /json. NestJS on the Fastify adapter was faster than plain Express by about 44% on the same route.

Should I use the Fastify adapter in NestJS?

If you don't depend on Express-only middleware, yes. In this benchmark NestJS on Fastify served 60-75% more GET requests per second than NestJS on Express, started faster (404 ms vs 486 ms) and used less memory under load.

Is Express 5 faster than Express 4?

I did not benchmark Express 4 in this test. Express 5 focuses on modern behaviour (promise-aware error handling, updated path matching) rather than speed, and in this test it was still about 43% behind Fastify on GET routes.

Which is best for a SaaS backend in 2026?

For a team project with auth, modules and many endpoints, NestJS on the Fastify adapter gives you structure without giving up much speed. For a small API or one that needs to run on Cloudflare Workers or Bun too, Hono is the simpler choice.

Originally published on fabwaseem.com.

How to Build an MCP Server in NestJS: Streamable HTTP, Guards and DI (Tested)

Waseem Anjum — Wed, 04 Nov 2026 06:45:24 +0000

Cross-posted from my blog. The original, with any updates, lives on fabwaseem.com.

To build an MCP server in NestJS, install the official MCP TypeScript SDK (@modelcontextprotocol/server and @modelcontextprotocol/node), build one createMcpHandler inside an injectable service, and call it from a @Post('mcp') controller method that takes @Req() and @Res(). Put a Nest guard in front for the bearer token and Origin check, pass req.body to the handler, and your tools can use any provider through normal dependency injection.

I built exactly that on November 4, 2026 and tested it end to end: with curl, the MCP Inspector CLI, and 8 e2e tests that use the official MCP client against both protocol versions. Below is the full code, how the pieces fit, and five problems I hit that most tutorials skip, including one that turns every request into a Parse error.

Is there an official NestJS MCP module?

No. There is no @nestjs/mcp package: the npm registry returned 404 for it on November 4, 2026. You have two real options:

Wire the official SDK yourself, which is what this guide does. It came to about 180 lines across a provider, a service, a guard, a controller and two modules, and you control auth, scopes and errors.
Use the community module @rekog/mcp-nest (MIT, version 2.0.9, about 384,000 npm downloads in the week of October 27 to November 2, 2026). Its README describes it as a NestJS microservice transport strategy: tools are @Tool() methods on @McpController() classes, so Nest guards, pipes, interceptors and filters apply, and it serves Streamable HTTP and STDIO. It peer-depends on the same v2 SDK packages and isn't maintained by the NestJS team.

Hand-wiring is worth understanding even if you end up on the module, because the gotchas below come from how Nest and the SDK share one Express request.

What I tested

Everything ran on one Linux VM (8 vCPUs) on Node.js 24.22.1:

NestJS 12.3.2 with @nestjs/platform-express (Express 5.3.0)
@modelcontextprotocol/server 2.4.0 and @modelcontextprotocol/node 2.1.2, the v2 SDK
@modelcontextprotocol/client 2.4.0 for the e2e tests, MCP Inspector 2.13.0 for manual calls
Zod 4.6.7, TypeScript 6.0.3, tests on node:test

The demo is a small notes API: a NotesService provider, a search_notes tool any token can call, and a create_note tool only a write-scoped token can see. If you're new to the SDK itself, my guide on building an MCP server in Next.js covers tools, schemas and the v1 to v2 changes in more depth.

Step 1: Install the packages

npm install @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata rxjs \
  @modelcontextprotocol/server @modelcontextprotocol/node zod
npm install -D typescript @types/node @types/express @nestjs/testing @modelcontextprotocol/client

NestJS 12 ships as ES modules ("type": "module" in @nestjs/core), so set "type": "module" in your package.json and use .js extensions in relative imports. The tsconfig.json I used:

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "target": "ES2023",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strict": true,
    "strictPropertyInitialization": false,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "."
  },
  "include": ["src", "test"]
}

Step 2: A normal Nest provider for your data

The tools should call the same services your REST controllers already use. Here an in-memory store stands in for a Prisma or TypeORM repository:

// src/notes/notes.service.ts
import { Injectable } from "@nestjs/common";

export interface Note { id: number; title: string; body: string; owner: string; createdAt: string }

@Injectable()
export class NotesService {
  private notes: Note[] = [];
  private nextId = 1;

  search(owner: string, q?: string): Note[] {
    const needle = q?.toLowerCase();
    return this.notes.filter(
      (n) => n.owner === owner && (!needle || `${n.title} ${n.body}`.toLowerCase().includes(needle)),
    );
  }

  create(owner: string, title: string, body: string): Note {
    const note = { id: this.nextId++, title, body, owner, createdAt: new Date().toISOString() };
    this.notes.push(note);
    return note;
  }
}

Export it from a NotesModule (providers: [NotesService], exports: [NotesService]) like any shared provider.

Step 3: The MCP service (handler, tools and DI)

This is the core. createMcpHandler takes a factory that returns a fresh McpServer, and the SDK's HTTP guide says the factory runs once per HTTP request and receives the request context, including authInfo. That gives you two things in Nest:

The factory is an arrow function inside an @Injectable() class, so every tool handler can use this.notes or any other injected provider.
You can register a different set of tools per caller. A token without the write scope never sees create_note in tools/list.

// src/mcp/mcp.service.ts
import { Injectable, Logger, OnModuleDestroy } from "@nestjs/common";
import { createMcpHandler, McpServer, type McpRequestContext } from "@modelcontextprotocol/server";
import { toNodeHandler } from "@modelcontextprotocol/node";
import * as z from "zod/v4";
import { NotesService } from "../notes/notes.service.js";

@Injectable()
export class McpService implements OnModuleDestroy {
  private readonly logger = new Logger(McpService.name);

  // Built once. The factory runs once per HTTP request, so every request gets a fresh McpServer.
  private readonly handler = createMcpHandler((ctx) => this.createServer(ctx), {
    responseMode: "json",
    onerror: (err) => this.logger.warn(err.message),
  });
  readonly node = toNodeHandler(this.handler);

  constructor(private readonly notes: NotesService) {}

  private createServer({ authInfo }: McpRequestContext): McpServer {
    const owner = authInfo?.clientId ?? "anonymous";
    const scopes = authInfo?.scopes ?? [];
    const server = new McpServer({ name: "notes", version: "1.0.0" });

    server.registerTool(
      "search_notes",
      {
        title: "Search notes",
        description: "Search the caller's notes by a word in the title or body. Returns at most 20.",
        inputSchema: z.object({ q: z.string().max(200).optional().describe("Text to match; omit to list all") }),
        annotations: { readOnlyHint: true },
      },
      async ({ q }) => {
        const hits = this.notes.search(owner, q).slice(0, 20);
        return { content: [{ type: "text", text: JSON.stringify(hits) }] };
      },
    );

    // Only tokens with the write scope ever see this tool in tools/list.
    if (scopes.includes("notes:write")) {
      server.registerTool(
        "create_note",
        {
          title: "Create note",
          description: "Save a new note for the caller.",
          inputSchema: z.object({ title: z.string().min(1).max(120), body: z.string().max(5000) }),
          outputSchema: z.object({ id: z.number(), title: z.string() }),
        },
        async ({ title, body }) => {
          const note = this.notes.create(owner, title, body);
          const out = { id: note.id, title: note.title };
          return { content: [{ type: "text", text: JSON.stringify(out) }], structuredContent: out };
        },
      );
    }
    return server;
  }

  async onModuleDestroy() {
    await this.handler.close();
  }
}

Notes on the choices:

toNodeHandler from @modelcontextprotocol/node adapts the fetch-style handler to Node's (req, res, parsedBody), which is what Express (and so Nest) gives you.
responseMode: "json" answers modern requests with one JSON body. The SDK prints a console warning when you set it, because progress and log notifications sent before the result are dropped. Leave it out if your tools stream progress.
handler.close() in onModuleDestroy aborts in-flight requests when Nest shuts down. Call app.enableShutdownHooks() so the hook runs on SIGTERM.
The owner comes from authInfo, not from tool arguments. The model can't ask for someone else's notes by passing a different user ID.

Step 4: A guard for the bearer token and Origin

The SDK checks no tokens and no Origin header on its own: authInfo is pass-through. A Nest guard is the natural place for both. The MCP transport spec says servers must validate Origin to stop DNS rebinding, and the SDK exports validateOriginHeader for that.

// src/mcp/mcp-auth.guard.ts
import { CanActivate, ExecutionContext, ForbiddenException, Injectable, UnauthorizedException } from "@nestjs/common";
import { createHash, timingSafeEqual } from "node:crypto";
import { validateOriginHeader, type AuthInfo } from "@modelcontextprotocol/server";
import type { Request, Response } from "express";

const sha = (s: string) => createHash("sha256").update(s).digest();
const same = (a: string, b: string) => timingSafeEqual(sha(a), sha(b));

// token -> who it belongs to and what it may do. Load from env or a DB in a real app.
function tokenTable(): Array<{ token: string; clientId: string; scopes: string[] }> {
  return [
    { token: process.env.MCP_READ_TOKEN ?? "", clientId: "reader", scopes: ["notes:read"] },
    { token: process.env.MCP_WRITE_TOKEN ?? "", clientId: "writer", scopes: ["notes:read", "notes:write"] },
  ].filter((t) => t.token.length >= 32);
}

const ALLOWED_ORIGINS = (process.env.MCP_ALLOWED_ORIGINS ?? "localhost,127.0.0.1").split(",");

@Injectable()
export class McpAuthGuard implements CanActivate {
  canActivate(ctx: ExecutionContext): boolean {
    const http = ctx.switchToHttp();
    const req = http.getRequest<Request & { auth?: AuthInfo }>();

    // DNS rebinding / CSRF: a browser Origin must be on the list. No Origin (CLI, agents) passes.
    const origin = validateOriginHeader(req.headers.origin, ALLOWED_ORIGINS);
    if (!origin.ok) throw new ForbiddenException(origin.message);

    const m = /^Bearer\s+(\S+)$/i.exec(req.headers.authorization ?? "");
    const hit = m && tokenTable().find((t) => same(m[1], t.token));
    if (!hit) {
      http.getResponse<Response>().setHeader("WWW-Authenticate", 'Bearer realm="mcp"');
      throw new UnauthorizedException("Invalid or missing bearer token");
    }

    req.auth = { token: m[1], clientId: hit.clientId, scopes: hit.scopes };
    return true;
  }
}

The guard sets req.auth, and toNodeHandler reads exactly that property and hands it to your factory as authInfo. That one line is the bridge between Nest's auth and the MCP server. Hashing both tokens before timingSafeEqual keeps the comparison constant-time even when lengths differ, and tokens shorter than 32 characters are ignored so an empty env var can't open the endpoint. For OAuth instead of static tokens, see the MCP authorization spec and my notes on MCP security.

Step 5: The controller

// src/mcp/mcp.controller.ts
import { All, Controller, Header, HttpCode, Post, Req, Res, UseGuards } from "@nestjs/common";
import type { Request, Response } from "express";
import { McpAuthGuard } from "./mcp-auth.guard.js";
import { McpService } from "./mcp.service.js";

@Controller("mcp")
export class McpController {
  constructor(private readonly mcp: McpService) {}

  @Post()
  @UseGuards(McpAuthGuard)
  async handle(@Req() req: Request, @Res() res: Response): Promise<void> {
    // With @Res() the SDK writes the response itself, so set headers on res directly.
    res.setHeader("Cache-Control", "no-store");
    // Pass req.body: Nest's JSON parser has already read the stream.
    await this.mcp.node(req, res, req.body);
  }

  // Stateless server: no GET stream, no DELETE session.
  @All()
  @HttpCode(405)
  @Header("Allow", "POST")
  notAllowed() {
    return { error: "Method not allowed" };
  }
}

Then the module and main.ts:

// src/mcp/mcp.module.ts
import { Module } from "@nestjs/common";
import { NotesModule } from "../notes/notes.module.js";
import { McpController } from "./mcp.controller.js";
import { McpService } from "./mcp.service.js";

@Module({ imports: [NotesModule], controllers: [McpController], providers: [McpService] })
export class McpModule {}

// src/main.ts
import "reflect-metadata";
import { NestFactory } from "@nestjs/core";
import type { NestExpressApplication } from "@nestjs/platform-express";
import { AppModule } from "./app.module.js";

const app = await NestFactory.create<NestExpressApplication>(AppModule);
// Express's JSON parser defaults to 100kb; the MCP SDK itself allows 4 MiB.
app.useBodyParser("json", { limit: "4mb" });
app.enableShutdownHooks();
await app.listen(Number(process.env.PORT ?? 3000), "127.0.0.1");
console.log(`MCP endpoint: ${await app.getUrl()}/mcp`);

AppModule just imports McpModule. Build with tsc, start with two tokens, and the endpoint is http://127.0.0.1:3000/mcp.

Step 6: Test it (curl, Inspector, e2e)

First the cheap checks with curl. Against my running server:

Request	Result
`POST /mcp` with no token	`401`, `WWW-Authenticate: Bearer realm="mcp"`
`POST /mcp` with `Origin: https://evil.example`	`403` `Invalid Origin: evil.example`
`GET /mcp`	`405`
`tools/list` with the read token	`search_notes` only
`tools/list` with the write token	`search_notes`, `create_note`

Then a real tool call with the MCP Inspector CLI. It takes the bearer token through --header:

npx @modelcontextprotocol/inspector --cli http://127.0.0.1:3000/mcp \
  --transport http --header "Authorization: Bearer $MCP_WRITE_TOKEN" \
  --method tools/call --tool-name create_note --tool-arg title=Hello --tool-arg body=From-inspector

It printed "structuredContent": { "id": 1, "title": "Hello" }.

For CI, boot the real Nest app on a random port with @nestjs/testing and drive it with the official client. This is a trimmed version of my test file; the full one has 8 tests and all passed:

// test/mcp.e2e.test.ts
import "reflect-metadata";
import { after, before, describe, it } from "node:test";
import assert from "node:assert/strict";
import { randomBytes } from "node:crypto";
import { Test } from "@nestjs/testing";
import type { INestApplication } from "@nestjs/common";
import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";

process.env.MCP_READ_TOKEN = randomBytes(24).toString("hex");
process.env.MCP_WRITE_TOKEN = randomBytes(24).toString("hex");
const { AppModule } = await import("../src/app.module.js");

let app: INestApplication;
let url: URL;

async function connect(token: string, mode: "auto" | "legacy" = "auto") {
  const client = new Client({ name: "e2e", version: "1.0.0" }, { versionNegotiation: { mode } });
  await client.connect(
    new StreamableHTTPClientTransport(url, { requestInit: { headers: { Authorization: `Bearer ${token}` } } }),
  );
  return client;
}

describe("NestJS MCP endpoint", () => {
  before(async () => {
    const mod = await Test.createTestingModule({ imports: [AppModule] }).compile();
    app = mod.createNestApplication({ logger: false });
    await app.listen(0, "127.0.0.1");
    url = new URL(`${await app.getUrl()}/mcp`.replace("[::1]", "127.0.0.1"));
  });
  after(() => app.close());

  for (const mode of ["auto", "legacy"] as const) {
    it(`scopes the tool list per token (${mode} handshake)`, async () => {
      const reader = await connect(process.env.MCP_READ_TOKEN!, mode);
      const writer = await connect(process.env.MCP_WRITE_TOKEN!, mode);
      assert.deepEqual((await reader.listTools()).tools.map((t) => t.name), ["search_notes"]);
      assert.deepEqual((await writer.listTools()).tools.map((t) => t.name).sort(), ["create_note", "search_notes"]);
      await reader.close(); await writer.close();
    });
  }

  it("runs tools through Nest DI and keeps data per caller", async () => {
    const writer = await connect(process.env.MCP_WRITE_TOKEN!);
    const reader = await connect(process.env.MCP_READ_TOKEN!);
    const created = await writer.callTool({ name: "create_note", arguments: { title: "Deploy notes", body: "rotate MCP tokens" } });
    assert.deepEqual(created.structuredContent, { id: 1, title: "Deploy notes" });
    const theirs = await reader.callTool({ name: "search_notes", arguments: { q: "rotate" } });
    assert.equal(JSON.parse((theirs.content as any)[0].text).length, 0);
    await writer.close(); await reader.close();
  });
});

The auto client negotiated protocol 2026-07-28 (the modern era) and the legacy client 2025-11-25, and the same factory served both. If you want the testing side in more depth (in-memory transport, Vitest, snapshots of tools/list), I wrote a separate guide on how to test an MCP server.

Five things that broke (and the fixes)

1. Forgetting req.body gives -32700 Parse error. Nest's JSON body parser reads the request stream before your controller runs. When I called this.mcp.node(req, res) without the third argument, every request got 400 with {"code":-32700,"message":"Parse error: Invalid JSON"}, because the SDK found an empty stream. Always pass req.body.

2. Nest's 100kb body limit answers before the SDK does. A 200 KB tools/call got 413 request entity too large from Express, not from the MCP server, so the client sees a plain HTTP error instead of a JSON-RPC one. The SDK's own default limit is 4 MiB (maxRequestBodySize). If your tools accept documents, raise Nest's limit with app.useBodyParser("json", { limit: "4mb" }). With that change, the same oversized call reached the SDK and came back as a normal tool error from Zod (q: Too big: expected string to have <=200 characters).

3. responseMode: "json" only shapes modern traffic. I logged the responses from both client modes. The 2026-07-28 client made two POSTs and got application/json both times. The 2025-11-25 client got text/event-stream for its requests even with responseMode: "json", plus a 202 for the initialized notification and a GET that my controller answered with 405. That's documented in the option's type comments: legacy traffic is served by a stateless fallback transport. Don't put a proxy in front that breaks SSE, or old clients fail.

4. @Header() is the wrong tool on the MCP route. With @Res(), the SDK calls writeHead itself. I set Cache-Control: no-store on res before handing it over: modern JSON responses kept it, but on legacy SSE responses the SDK's own Cache-Control: no-cache, no-transform replaced it. Both stop caching, so it's fine, but set headers on res, not with decorators.

5. A hidden tool is a protocol error, not a tool error. When the read token called create_note, the client threw Tool create_note not found rather than returning an isError result. That's what you want for scoping: the tool doesn't exist for that caller. Bad arguments are different: an empty title came back as a normal result with isError: true and Input validation error: ... title: Too small, so the model can fix the call and retry.

How fast is a per-request MCP server in NestJS?

Fast enough to ignore. I made 500 sequential search_notes calls from one connected client after 50 warm-up calls, three runs per protocol mode, on localhost:

Mode	p50	p95	p99
`2026-07-28` (modern)	1.36 to 1.69 ms	1.94 to 2.73 ms	2.97 to 5.56 ms
`2025-11-25` (legacy)	1.39 to 1.71 ms	2.05 to 2.97 ms	2.94 to 5.27 ms

The ranges are the lowest and highest of the three runs. That's the whole round trip: Nest routing, the guard, a fresh McpServer from the factory, Zod validation, the tool and the response. Your database call will dominate. A fresh server per request is how the SDK's HTTP guide says createMcpHandler works, and I covered the trade-offs of that stateless design in stateless MCP servers.

Should you use @rekog/mcp-nest instead?

Use the community module if you want decorators: tools declared as @Tool() methods on @McpController() classes, with Nest pipes and interceptors around them, and STDIO as well as HTTP. Hand-wire the SDK, as above, if you want per-token tool lists, your own guard and error format, or fewer dependencies between you and SDK updates. The SDK's v2 line only went stable in July 2026 (@modelcontextprotocol/server 2.0.0), so expect changes; with the hand-wired version I upgrade two packages and rerun my e2e tests. Either way, connect clients the same way: my guide on adding a remote MCP server to Cursor, Claude Code and VS Code shows the config for each.

FAQ

Is there an official NestJS MCP package?

No. As of November 4, 2026 the npm registry has no @nestjs/mcp package. You can wire the official MCP TypeScript SDK into a Nest controller yourself, or use the community module @rekog/mcp-nest (MIT, version 2.0.9), which is not maintained by the NestJS team.

Can I use NestJS dependency injection inside MCP tools?

Yes. Create the handler with createMcpHandler inside an @Injectable() service and register tools in a factory method on that class. Tool handlers then call injected providers through this, like any other Nest service. The factory runs once per HTTP request.

How do I add authentication to a NestJS MCP server?

Use a Nest guard on the POST /mcp route. Verify the bearer token, reject bad Origin headers with 403, and set req.auth to an object with token, clientId and scopes. The @modelcontextprotocol/node adapter passes req.auth to your server factory as authInfo, so you can scope data and tools per caller.

Why does my NestJS MCP endpoint return Parse error -32700?

Nest's JSON body parser has already consumed the request stream. Pass the parsed body as the third argument: toNodeHandler(handler)(req, res, req.body). Without it the SDK reads an empty stream and answers 400 with Parse error: Invalid JSON.

Does a NestJS MCP server work with older MCP clients?

Yes. createMcpHandler serves 2025-era clients through a stateless fallback by default. In my tests one endpoint answered a 2026-07-28 client with JSON and a 2025-11-25 client over SSE. Set legacy: "reject" if you only want the modern protocol.

Originally published on fabwaseem.com.

pnpm vs npm Security in 2026: Install Scripts and Release Age, Tested

Waseem Anjum — Wed, 04 Nov 2026 06:44:58 +0000

Cross-posted from my blog. The original, with any updates, lives on fabwaseem.com.

Most npm malware runs the moment you install it, through a postinstall script, and it usually ships as a fresh patch release that gets pulled within hours or days. So the two package-manager settings that matter most for supply chain security are: does it run dependency install scripts by default, and will it install a version that was published an hour ago. I tested both on pnpm vs npm tonight with a harmless canary package and a real package that had just shipped a release. The defaults are not what most people assume, and they differ between npm 11 and npm 12.

pnpm vs npm security: results with default settings

Tested November 3, 2026 on Linux with Node 26.13.0.

	npm 11.20.0 (bundled with Node 26.13)	npm 12.2.1 (`latest`)	pnpm 12.16.1
Dependency `postinstall` script	ran, with a warning	blocked, with a warning	blocked, install exits with an error
Installs a version published 17 hours ago	yes	yes	no (waits 1 day)
Approve a package's scripts	`npm approve-scripts <pkg>`	`npm approve-scripts <pkg>`	`allowBuilds` in `pnpm-workspace.yaml`
Release-age setting	`min-release-age` (days, off by default)	`min-release-age` (days, off by default)	`minimumReleaseAge` (minutes, default 1440)

Node 24.22.2 bundles npm 11.19.1, which has the same script settings as 11.20. If you use the npm that came with Node, you're on npm 11.

Test 1: does the install script run?

I made a local package whose only job is to write a file when its postinstall runs:

{
  "name": "install-canary",
  "version": "1.0.0",
  "scripts": {
    "postinstall": "node -e \"require('fs').writeFileSync('/tmp/canary','ran')\""
  }
}

Then I packed it with npm pack and installed the tarball into an empty project with each tool, deleting /tmp/canary before each run.

npm 11.20.0 printed a warning and then ran the script anyway. /tmp/canary existed afterwards:

npm warn install-scripts 1 package has install scripts not yet covered by allowScripts:
npm warn install-scripts   install-canary@1.0.0 (postinstall: node -e "...")
npm warn install-scripts Run `npm install-scripts ls` to review, or `npm install-scripts approve <pkg>` to allow.

npm 12.2.1 printed a similar warning, but worded as "had install scripts blocked", and the canary file was not created.

pnpm 12.16.1 didn't run the script and exited with code 1:

× adding a new package
╰─▶ Ignored build scripts: install-canary@file:../canary/install-canary-1.0.0.tgz
help: Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

The packages were still written to node_modules, but the failing exit code means CI stops instead of quietly continuing. pnpm's docs call this strictDepBuilds, and it's on by default.

I got the same pattern with esbuild@0.28.2, a real package with a legitimate postinstall: npm 11 ran it with a warning, npm 12 blocked it, and pnpm blocked it and failed.

Allowing the scripts you trust

With npm (11.19+ and 12), approve per package. The approval is pinned to the exact version:

npm approve-scripts esbuild
node -p "JSON.stringify(require('./package.json').allowScripts)"
# {"esbuild@0.28.2":true}

Because the approval is pinned, a new esbuild release will be flagged again, which is exactly when you want to look.

With pnpm, list trusted packages in pnpm-workspace.yaml:

allowBuilds:
  esbuild: true

With that file in place, pnpm add esbuild@0.28.2 finished with exit code 0. pnpm approve-builds gives you an interactive picker for the same thing.

Test 2: will it install a brand-new release?

The ai package published 7.0.162 at 01:19 UTC on November 3, about 17 hours before I ran this. The previous releases were 7.0.161 and 7.0.160 on November 2, and 7.0.159 on October 30.

Command	Installed
`npm i ai` (npm 11.20.0)	7.0.162
`npm i ai` (npm 12.2.1)	7.0.162
`npm i ai --min-release-age=1` (npm 11.20.0)	7.0.159
`pnpm add ai` (pnpm 12.16.1, defaults)	7.0.159

Both npm versions installed the newest release by default. pnpm skipped everything younger than 24 hours because minimumReleaseAge defaults to 1440 minutes, as described in pnpm's supply chain security docs. npm's min-release-age does the same once you set it, but it's measured in days and is off by default.

Note that the cooldown cuts both ways. A real security fix published today also waits. Both tools let you exempt packages: min-release-age-exclude in npm, minimumReleaseAgeExclude in pnpm. With minimumReleaseAgeExclude: [ai] in pnpm-workspace.yaml, pnpm installed 7.0.162 straight away.

Recommended settings for each

npm

In the project's .npmrc:

min-release-age=3
strict-allow-scripts=true

Then approve the few packages that genuinely need install scripts with npm approve-scripts <pkg>, and commit the allowScripts field in package.json. If you're still on npm 11, upgrading to npm 12 gets you blocking by default: npm i -g npm@12.

pnpm

In pnpm-workspace.yaml:

minimumReleaseAge: 4320        # 3 days, in minutes
trustPolicy: no-downgrade      # refuse a version with weaker publish provenance than earlier ones
allowBuilds:
  esbuild: true
  sharp: true

Script blocking, strictDepBuilds and blockExoticSubdeps (no git or tarball URLs deep in the tree) are already on by default.

Both

Commit the lockfile and install with npm ci / pnpm install --frozen-lockfile in CI. The release-age window matters when versions get resolved, which is when the lockfile changes, so review lockfile diffs in pull requests.
Don't run installs with secrets in the environment. If a script does slip through, it can read whatever env vars the install step has.
Build Docker images from the lockfile. My Next.js Dockerfile installs from the lockfile in a separate deps stage.

If you write server code that fetches user-supplied URLs, SSRF protection in Node.js covers the other half of keeping a Node app safe.

So, is pnpm more secure than npm?

With default settings, yes, in both tests: pnpm blocked the install script and failed the install, and it refused a 17-hour-old release. npm 12 now blocks install scripts by default too, but still installs brand-new releases unless you set min-release-age. npm 11, which is what ships with Node 24 and Node 26 today, only warns about install scripts. Configured properly, npm 11.19+ and npm 12 can match pnpm on both points. The difference is what you get if you never touch the config.

FAQ

Does pnpm run postinstall scripts?

Not for dependencies, unless you allow them. pnpm 12.16.1 skipped my canary's postinstall and exited with Ignored build scripts. Allow trusted packages with allowBuilds in pnpm-workspace.yaml or by running pnpm approve-builds.

Does npm block install scripts by default?

npm 12 does: version 12.2.1 blocked my canary's postinstall. npm 11.20.0, the version bundled with Node 26.13.0, only printed a warning and ran the script. Set strict-allow-scripts=true or upgrade to npm 12.

What is minimumReleaseAge in pnpm?

It's the number of minutes a version must have been published before pnpm will install it. It defaults to 1440 (one day). In my test, pnpm installed ai@7.0.159 instead of the 17-hour-old 7.0.162.

What is min-release-age in npm?

An npm config option, measured in days, that makes npm ignore versions published more recently than that. It's off by default. npm i ai --min-release-age=1 installed 7.0.159 instead of the 17-hour-old 7.0.162.

Is pnpm safer than npm?

With default settings, pnpm blocked more in my tests: it refused to run dependency install scripts and refused a release under 24 hours old. npm can be configured to do both with strict-allow-scripts and min-release-age.

Originally published on fabwaseem.com.

Next.js Middleware to Proxy: How to Migrate middleware.ts to proxy.ts in Next.js 16

Waseem Anjum — Tue, 03 Nov 2026 18:22:35 +0000

Cross-posted from my blog. The original, with any updates, lives on fabwaseem.com.

In Next.js 16, middleware.ts is deprecated and renamed to proxy.ts. Your existing middleware still runs, but every build now prints a deprecation warning, and a few things behave differently: the function name changes, Proxy always runs on the Node.js runtime, and having both files in a project fails the build. This guide covers the Next.js middleware to proxy migration step by step, with the exact warnings and errors I got from Next.js 16.4.5 on a small test app, so you know what to expect before you run the codemod.

Next.js middleware vs proxy: what actually changed

The behavior is the same feature under a new name. From the Next.js proxy docs:

	`middleware.ts` (Next.js 12–15)	`proxy.ts` (Next.js 16+)
File name	`middleware.ts`	`proxy.ts`
Exported function	`middleware` (or default)	`proxy` (or default)
`config.matcher`	same	same
`NextRequest` / `NextResponse`	same	same
Runtime	Edge by default, Node.js opt-in since 15.5	Node.js only; `runtime` config throws
Status in 16.x	deprecated, still runs with a warning	recommended

The Next.js team says they renamed it because "middleware" was getting confused with Express-style middleware and encouraged using it for too much. "Proxy" describes what it is: a layer in front of your routes that can redirect, rewrite, set headers or return a response.

Step 1: see the deprecation warning

I started with a typical auth-redirect middleware on Next.js 16.4.5:

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

export function middleware(request: NextRequest) {
  const session = request.cookies.get('session')?.value
  if (!session) {
    const url = new URL('/login', request.url)
    url.searchParams.set('next', request.nextUrl.pathname)
    return NextResponse.redirect(url)
  }
  const headers = new Headers(request.headers)
  headers.set('x-user', session)
  return NextResponse.next({ request: { headers } })
}

export const config = {
  matcher: ['/dashboard/:path*'],
}

next build succeeds, but prints:

⚠ The "middleware" file convention is deprecated. Please use "proxy" instead.

  To migrate automatically, run:
  npx @next/codemod@canary middleware-to-proxy .

The route table already labels it ƒ Proxy (Middleware).

Step 2: run the middleware-to-proxy codemod

npx @next/codemod@canary middleware-to-proxy .

On my test app the codemod renamed middleware.ts to proxy.ts and the exported function from middleware to proxy. Nothing else changed:

- // middleware.ts
- export function middleware(request: NextRequest) {
+ // proxy.ts
+ export function proxy(request: NextRequest) {

After that, next build ran with no deprecation warning. I checked it with next start: /dashboard without a cookie returned a 307 to /login?next=%2Fdashboard, and with session=waseem the page rendered the x-user header the proxy set.

Commit the codemod change on its own so the diff stays easy to review.

Step 3: migrate by hand (if you can't run the codemod)

It's two edits:

Rename middleware.ts to proxy.ts, in the same place (project root, or src/ if you use it).
Rename the exported function to proxy, or use a default export.

// proxy.ts
import type { NextProxy } from 'next/server'

export const proxy: NextProxy = (request, event) => {
  // same logic as before
}

The NextProxy type infers request as NextRequest and event as NextFetchEvent, so event.waitUntil() for background logging still works. If you customized pageExtensions, the file name follows it, for example proxy.page.ts.

Errors you may hit during the migration

"Both middleware file and proxy file are detected"

If the old file is still there after you create proxy.ts, the build fails:

Error: Both middleware file "./middleware.ts" and proxy file "./proxy.ts" are detected.
Please use "./proxy.ts" only.

Delete middleware.ts. This one bites when a merge brings the old file back from another branch.

"Proxy does not support Edge runtime"

Proxy always runs on Node.js. If your old middleware had runtime: 'edge' in its config and you carry it over, the build fails:

Error: Next.js can't recognize the exported `config` field in route.
Proxy does not support Edge runtime.

Remove runtime from the config. For context, keeping middleware.ts with runtime: 'edge' on 16.4.5 also failed, asking for 'experimental-edge', and that value builds but warns that the Edge Runtime is deprecated. Either way, the direction is Node.js.

Running on Node.js is mostly good news: you can use Node APIs and regular npm packages (database clients, jose, crypto) in Proxy. The cost is that you can't rely on Edge-only behavior, so if you self-host behind your own server this changes nothing, and on platforms that ran middleware at the edge you should check where Proxy runs.

What doesn't change

Matchers. config.matcher strings, arrays, regex and has / missing conditions work the same. Matchers must still be constants.
Execution order. Proxy runs after headers and redirects from next.config.js and before filesystem routes.
Request header pattern. Use NextResponse.next({ request: { headers } }) to pass data to your app. NextResponse.next({ headers }) sends them to the browser instead.
Config flags. skipMiddlewareUrlNormalize is now skipProxyUrlNormalize. skipTrailingSlashRedirect is unchanged.
Testing helpers. The current docs show unstable_doesProxyMatch, but the 16.4.5 package I installed still only exports unstable_doesMiddlewareMatch from next/experimental/testing/server, so check your installed version before renaming it in tests.

Don't use proxy.ts as your only auth check

The Next.js docs point out that Server Functions are handled as POST requests to the page that uses them, so a matcher that excludes a path also skips Server Function calls on that path. Moving a Server Function or changing a matcher can silently remove Proxy coverage. Treat Proxy as the fast redirect for signed-out users, and check the session again inside each Server Action, Route Handler and data function.

I go through that pattern with a real auth library in Better Auth with Next.js, and the October Next.js patches in this security update post are a good reminder of why defense in depth matters.

Migration checklist

[ ] Run npx @next/codemod@canary middleware-to-proxy . or rename the file and function by hand
[ ] Delete any leftover middleware.ts
[ ] Remove runtime: 'edge' from the Proxy config
[ ] Rename skipMiddlewareUrlNormalize to skipProxyUrlNormalize in next.config (the old name is marked @deprecated in 16.4.5's types)
[ ] Re-run next build and confirm the warning is gone and the route table shows Proxy
[ ] Re-check auth inside Server Actions and Route Handlers, not only in Proxy

FAQ

Is Next.js middleware deprecated?

Yes. In Next.js 16.0.0 the middleware file convention was deprecated and renamed to proxy. On 16.4.5, middleware.ts still runs, but next build prints a deprecation warning that points to the codemod.

What is the difference between middleware.ts and proxy.ts in Next.js?

The file name and the exported function name. The API (NextRequest, NextResponse, config.matcher) is the same. The one behavior change is that Proxy always runs on the Node.js runtime and setting runtime in its config is an error.

How do I migrate from middleware to proxy in Next.js 16?

Run npx @next/codemod@canary middleware-to-proxy .. It renames middleware.ts to proxy.ts and the middleware function to proxy. Then delete any leftover middleware.ts, remove runtime: 'edge' if present, and rebuild.

Can I keep both middleware.ts and proxy.ts?

No. On Next.js 16.4.5 the build fails with "Both middleware file and proxy file are detected. Please use ./proxy.ts only."

Does Next.js proxy run on the Edge runtime?

No. Proxy uses the Node.js runtime, and the build fails with "Proxy does not support Edge runtime" if you set runtime: 'edge' in its config.

Originally published on fabwaseem.com.

Node 24 vs Node 26: Benchmarks, Breaking Changes and Should You Upgrade (2026)

Waseem Anjum — Tue, 03 Nov 2026 18:22:32 +0000

Cross-posted from my blog. The original, with any updates, lives on fabwaseem.com.

Node.js 26 became the Active LTS line on October 28, 2026 with v26.13.0 "Lithium", and Node 24 moved to Maintenance LTS on October 20. If you're deciding between Node 24 vs Node 26 for a production app, this post covers what changes, what breaks, and how the two compare on a few benchmarks I ran on the same machine tonight. The short version: Node 26 was faster at JSON serialization, async-heavy code and a plain node:http server, but slower in two places you might not expect, fetch() and inserting a million keys into a Map.

Node 24 vs Node 26 at a glance

	Node 24 "Krypton"	Node 26 "Lithium"
Version tested	v24.22.2	v26.13.0
Status (Nov 2026)	Maintenance LTS since Oct 20, 2026	Active LTS since Oct 28, 2026
End of life	April 30, 2028	April 30, 2029
V8	13.6	14.6
Undici (powers `fetch`)	7.30.1	8.12.2
`NODE_MODULE_VERSION`	137	147
Bundled npm	11.19.1	11.20.0
`Temporal` global	not available	on by default

Dates come from the Node.js release schedule. Versions are what process.versions printed on each binary.

What's new in Node 26

From the Node 26.0.0 release notes and checked on v26.13.0:

Temporal is enabled by default. Temporal.Now.plainDateISO('Asia/Karachi') works with no flag. On Node 24, Temporal is undefined.
V8 14.6 brings Map.prototype.getOrInsert() / getOrInsertComputed() (the upsert proposal) and Iterator.concat().
Undici 8, so the global fetch() is a different major version of the HTTP client.
TypeScript type stripping still works out of the box for .ts files, as it does on Node 24. --experimental-transform-types was removed, so enums and namespaces that need transformation won't run without a build step.

// Node 26 only
const counts = new Map();
for (const word of ['a', 'b', 'a']) {
  counts.set(word, counts.getOrInsert(word, 0) + 1);
}

const today = Temporal.Now.plainDateISO('Asia/Karachi');
console.log(today.add({ days: 30 }).toString());

const all = Iterator.concat([1, 2].values(), [3].values()).toArray(); // [1, 2, 3]

Breaking changes to check before upgrading

These are the ones most likely to hit a typical Node.js, NestJS or Next.js codebase:

Native addons must be rebuilt. NODE_MODULE_VERSION went from 137 to 147. Anything with a compiled .node file (bcrypt, sharp, better-sqlite3, canvas) needs a fresh install on Node 26. Delete node_modules in your Docker build rather than copying it from a Node 24 stage.
http.ServerResponse.prototype.writeHeader() is gone. It was a legacy alias. On v26.13.0 typeof res.writeHeader is undefined. Use writeHead().
The _stream_* legacy modules are removed (_stream_readable, _stream_writable and friends). Old dependencies that require('_stream_readable') will crash at import.
module.register() is runtime-deprecated. Running a loader that calls it prints DEP0205 DeprecationWarning: module.register() is deprecated. Use module.registerHooks() instead. It still works, but plan to move custom loaders to registerHooks().
--experimental-transform-types is removed. If you run .ts with enums directly through Node, switch to erasableSyntaxOnly style code or keep a compiler step.

A quick way to find the first two in a codebase:

grep -rn "writeHeader(\|_stream_readable\|_stream_writable\|module.register(" src/ node_modules/.pnpm 2>/dev/null | head

Node 24 vs Node 26 performance: benchmark setup

I ran these on November 3, 2026 on one Linux VM with 8 vCPUs (Intel Xeon) and 16 GB RAM. The machine was shared with other work (load average around 1.5 before starting), so treat small differences as noise. To limit that:

Each benchmark process was pinned to one CPU with taskset.
Node 24 and Node 26 runs were interleaved over 5 rounds, and I report the median of the 5 rounds.
The HTTP load generator (autocannon, 100 connections, 10 s) always ran on Node 24 on separate CPUs, so only the server changed.
The fetch() test sent 20,000 requests with 50 concurrent loops to a fixed Node 24 server, so only the client changed.

The scripts are plain .mjs files: JSON.parse/JSON.stringify on a 20,000-item document, sorting 300,000 numbers, setting 1 million string keys in a Map, a global regex replace, SHA-256 over 16 MB, allocating 2 million small class instances, and 1 million sequential awaits.

Benchmark results

Lower is better for times, higher is better for requests per second. Median of 5 rounds.

Test	Node 24.22.2	Node 26.13.0	Change
`JSON.parse` (20k items)	11.79 ms	10.46 ms	11% faster
`JSON.stringify` (20k items)	7.20 ms	4.53 ms	37% faster
Sort 300k numbers	54.6 ms	51.7 ms	5% faster
`Map.set` 1M string keys	396.7 ms	507.5 ms	28% slower
Regex replace	2.06 ms	1.72 ms	16% faster
SHA-256 over 16 MB	9.57 ms	9.17 ms	4% faster (within noise)
2M class instances	47.8 ms	35.0 ms	27% faster
1M sequential `await`	58.6 ms	35.0 ms	40% faster
`node -e 0` startup	22.3 ms	20.7 ms	7% faster
RSS after startup	41 MB	41 MB	same
`node:http` server, req/s	73,079	79,653	9% more
`node:http` p99 latency	3 ms	2 ms	lower
`fetch()` client, req/s	8,442	7,601	10% fewer

What stood out:

JSON.stringify and await got much cheaper. Those two show up everywhere in API servers, so the 9% higher node:http throughput is consistent with them.
fetch() was slower in 4 of 5 rounds. Node 26 ships Undici 8. If your service makes lots of outbound HTTP calls, measure your own workload before and after.
Map.set with 1 million new string keys was slower in every round. The Node 24 numbers for this test varied a lot (336 to 513 ms), so the size of the gap is uncertain, but the direction was consistent. Code that builds very large maps in a hot path is worth profiling.

These are microbenchmarks on one VM. They tell you where to look, not what your app will do.

How to upgrade from Node 24 to Node 26

# 1. Switch locally
nvm install 26 && nvm use 26     # or: fnm use 26 / volta install node@26

# 2. Reinstall so native addons rebuild against ABI 147
rm -rf node_modules && npm ci

# 3. Surface deprecations your code triggers
NODE_OPTIONS=--trace-deprecation npm test

Then update the places that pin the version:

# Dockerfile
FROM node:26-alpine AS deps

// package.json
{ "engines": { "node": ">=26" } }

Also update .nvmrc, your CI matrix and the Node version in your hosting panel. If you deploy Next.js in Docker, the multi-stage setup in my Next.js Dockerfile guide works the same with node:26-alpine as the base image.

Should you upgrade to Node 26 now?

New projects: start on Node 26. It's the Active LTS line and is supported a year longer than Node 24.
Existing Node 24 apps: there's no rush. Node 24 gets security fixes until April 30, 2028. Upgrade when you next touch your Docker base image, after rebuilding native addons and running your tests with --trace-deprecation.
Services that are mostly outbound HTTP: benchmark your own fetch() traffic first, because that was the one place Node 26 was clearly slower in my test.

If you're also weighing runtimes rather than versions, I compared Bun vs Node on real workloads earlier.

FAQ

Is Node 26 LTS?

Yes. Node 26 entered Active LTS on October 28, 2026 with v26.13.0, codename "Lithium". It stays Active LTS until October 20, 2027, then Maintenance LTS until April 30, 2029.

When does Node 24 reach end of life?

April 30, 2028. Node 24 has been in Maintenance LTS since October 20, 2026, which means security and critical fixes only.

Is Node 26 faster than Node 24?

In my benchmarks on one 8-vCPU VM, Node 26 was faster at JSON.stringify (37%), sequential await (40%) and as a node:http server (9% more requests per second). It was slower for the fetch() client (10% fewer requests per second) and for inserting 1 million keys into a Map (28% slower). Measure your own workload.

What breaks when upgrading from Node 24 to Node 26?

The common ones are native addons that need rebuilding (NODE_MODULE_VERSION 147), the removed res.writeHeader() alias, the removed _stream_* modules, the removed --experimental-transform-types flag, and a runtime deprecation warning for module.register().

Does Node 26 have Temporal?

Yes. The Temporal global is enabled by default in Node 26. In the official Node 24.22.2 binary, typeof Temporal is 'undefined'.

Originally published on fabwaseem.com.

Vitest vs Jest vs node:test in 2026: Benchmarked on a Real TypeScript Project

Waseem Anjum — Tue, 03 Nov 2026 06:43:36 +0000

Cross-posted from my blog. The original, with any updates, lives on fabwaseem.com.

I ran the same TypeScript test suite under Vitest 5.1, Jest 30.5 and Node's built-in node:test, and timed cold runs, warm runs, single files, watch mode and coverage. The suite is 39 test files and 183 tests against a small NestJS-style orders service, an HTTP API and an MCP server. The result surprised me: with default settings, Jest with @swc/jest was the fastest full run, and Vitest was the slowest of the three. Change one isolation setting and the order flips. Below are the numbers, the setup for each runner, and the TypeScript and ESM problems I hit along the way.

What I tested

Everything ran on November 3, 2026 on one Linux VM with 8 vCPUs (Intel Xeon) and 16 GB of RAM, on Node.js 24.22.1:

Vitest 5.1.0 (Vite 8.3.5), @vitest/coverage-v8 5.1.0
Jest 30.5.2 with @swc/jest 0.2.39 and @swc/core 1.16.21, and separately with ts-jest 29.4.15
node:test from Node 24.22.1, using Node's built-in type stripping (no loader)
TypeScript 6.0.3 for type checks. ts-jest 29.4.15 declares typescript >=4.3 <7, so it doesn't support TypeScript 7.0.2, the current latest on npm.

The code under test is real, not generated: money math with cent allocation, slugs, cursor pagination, an LRU cache, a token-bucket rate limiter, retry with backoff, a CSV parser, an event bus, Zod order schemas, a pricing service, an orders service with status transitions, a node:http JSON API, and the MCP server from my MCP testing guide. That's 387 lines of source and 501 lines of tests. The HTTP and MCP tests start real servers on random ports and call them with fetch and the official MCP SDK client.

To keep the suite identical, every test file imports describe, it and hooks from #t, a one-line shim that each runner maps to its own API, and asserts with node:assert/strict. Fakes are hand-written, so no runner-specific mocking runs inside the benchmark. I compare the mocking APIs separately below.

How I measured: a script ran each configuration 10 times in shuffled order. "Cold" means I deleted the runner's caches first (jest --clearCache, and node_modules/.vite plus node_modules/.vitest-cache for Vitest). "Warm" is the next run with caches in place. Times are whole-process wall clock, and I report the median. Every run had to exit 0 with all 183 tests passing.

One honest caveat: this VM is shared, and other jobs were running (load average between 3 and 13 on 8 cores). Absolute times are noisy, so read the ranking more than the decimals. I ran the main configurations in two separate batches, and Vitest, Jest and node:test each landed within about 0.1 s of their first-batch medians.

Results: the full suite

39 files, 183 tests, median of 10 runs:

Runner and config	Cold	Warm
Vitest 5.1, defaults (`forks` pool, isolated)	1.59 s	1.51 s
Vitest, `--pool=threads`	1.55 s	1.42 s
Vitest, `--pool=vmThreads`	0.91 s	0.91 s
Vitest, `--no-isolate`	0.75 s	0.68 s
Vitest, `--fsModuleCache`	1.63 s	1.52 s
Jest 30.5 + `@swc/jest` (CommonJS output)	0.99 s	0.81 s
Jest + `@swc/jest`, native ESM (`--experimental-vm-modules`)	1.19 s	1.01 s
Jest + `ts-jest` (type-checks every file)	4.30 s	3.13 s
Jest + `ts-jest`, `isolatedModules: true`	1.44 s	1.14 s
`node --test` (process per file)	1.23 s	1.24 s
`node --test --test-isolation=none`	0.52 s	0.51 s

The threads, vmThreads and --test-isolation=none rows come from the second batch. In that batch, the Vitest default, Jest + @swc/jest and node --test rows measured 1.52/1.40 s, 0.95/0.80 s and 1.14/1.23 s.

What the numbers say:

Isolation is most of the cost. Vitest's default forks pool starts a fresh child process for each test file, and its own summary told me so: "39 workers spawned, ~81ms startup each". node --test also runs each file in its own process. Jest isolates each file in a separate vm context but reuses its 7 worker processes. Turn isolation off and Vitest (0.68 s) and node:test (0.51 s) both beat Jest.
vmThreads is the middle ground for Vitest. It kept per-file isolation and cut the run from 1.51 s to 0.91 s. The catch is that it runs each file in a vm sandbox, like Jest does. Vitest's docs warn that this leaks memory on large suites (workers restart when they pass vmMemoryLimit) and that objects from Node APIs such as fetch's response.json() and structuredClone() have a different prototype. That's the same realm problem I hit with Jest below, and this suite only passed under vmThreads because I had already fixed those tests.
ts-jest with type checking costs about 2.3 seconds here. It was 3.13 s warm against 0.81 s for @swc/jest. With isolatedModules: true it skips the type checker and drops to 1.14 s. Running tsc --noEmit on the whole project separately took about 1.5 s (median of 5), so a separate type-check step is cheaper than type-checking inside Jest.
Caches barely mattered at this size. Cold and warm runs differ by 0.1 to 0.2 s for Vitest and Jest with SWC. Vitest 5 made fsModuleCache stable, but on a project this small it made no measurable difference. node --test has no transform cache at all, because type stripping is cheap.

Results at 4x the size

To see how the gap scales, I copied the test tree three more times: 156 files and 732 tests, same source. Median of 7 runs:

Runner and config	Cold	Warm
Vitest, defaults	5.15 s	5.03 s
Vitest, `--pool=vmThreads`	2.29 s	1.99 s
Vitest, `--no-isolate`	1.32 s	1.08 s
Jest + `@swc/jest`	1.75 s	1.52 s
`node --test`	4.32 s	4.26 s
`node --test --test-isolation=none`	1.08 s	1.10 s

The per-file process cost grows with the file count. Isolated Vitest went from 1.5 s to 5.0 s, while Jest went from 0.8 s to 1.5 s. Without isolation, Vitest and node:test stay around one second. On a busy machine, process startup is exactly the thing that gets slower, so your numbers on a quiet laptop may be closer together, but the direction should hold.

One file, the inner loop

Running only test/orders/service.create.test.ts (4 tests), warm, median of 7:

Runner	Time
`node --test`	0.18 s
Jest + `@swc/jest`	0.39 s
Vitest	0.40 s
Jest + `ts-jest`	1.40 s

Node has nothing to boot except itself. Vitest and Jest each spend about 0.2 s more starting their runner.

Watch mode

I started each runner in watch mode, waited for the first run, then edited a source file and timed the rerun (median of 5). money.ts is imported by 3 test files. events.ts is imported by the shared test fixtures, so 18 files depend on it.

Watch command	Edit `money.ts`	Edit `events.ts`
`vitest --watch`	0.23 s, 3 files	0.97 s, 18 files
`jest --watch` (needs git)	0.25 s, 3 files	0.52 s, 18 files
`jest --watchAll`	0.66 s, all 39 files	0.61 s, all 39 files
`node --test --watch`	0.31 s, 3 files	0.94 s, 18 files

All three rerun only the affected test files. Vitest follows the module graph, and node:test did the same in my test. Jest's --watch uses git to find changed files, and outside a git repo it refuses to start ("--watch is not supported without git/hg, please use --watchAll"). Vitest's interactive watch UI is the nicest of the three (filter by name, rerun failed tests, the optional browser UI), but on raw rerun speed they're close.

Coverage

Full suite with coverage on, median of 5 runs after one warm-up:

Runner	Time	Lines reported
Vitest, `@vitest/coverage-v8`	1.99 s	97.38%
Jest + `@swc/jest`, default (Babel/Istanbul)	0.99 s	97.81%
Jest + `@swc/jest`, `--coverageProvider=v8`	1.66 s	98.44%
`node --test --experimental-test-coverage`	1.36 s	100% lines, 95.79% branches

Coverage added about 0.5 s to Vitest and less to Jest with Istanbul. The percentages aren't comparable between tools, because each counts lines, statements and branches differently. Node said 100% of lines while the others found a few uncovered lines in the same code. Pick one tool for your coverage threshold and stay with it. Node's coverage is still behind the --experimental-test-coverage flag on Node 24.

Setup for each runner

Vitest

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    include: ["test/**/*.test.ts"],
    coverage: { provider: "v8", include: ["src/**"] },
    // isolate: false,   // 0.68 s instead of 1.51 s, if your tests don't leak state
    // pool: "vmThreads", // keeps isolation, 0.91 s here
  },
});

That's all it needed. ESM, TypeScript, .ts extensions in imports, top-level await and import.meta all worked without extra config. The exception is decorators: a class with a legacy decorator and a constructor parameter property failed with "SyntaxError: Invalid or unexpected token" under my bare config, even with experimentalDecorators in tsconfig.json. Adding unplugin-swc 2.0.0 to the plugins, with experimentalDecorators and emitDecoratorMetadata in tsconfig, fixed it. If you're on NestJS 12, the Vitest config that nest new generates already handles this. I covered that in my NestJS 12 migration guide.

Jest with @swc/jest

// jest.config.cjs
/** @type {import('jest').Config} */
module.exports = {
  testEnvironment: "node",
  testMatch: ["<rootDir>/test/**/*.test.ts"],
  transform: { "^.+\\.ts$": ["@swc/jest"] },
};

This works if SWC compiles your ESM TypeScript to CommonJS, which is what happens when you don't list .ts in extensionsToTreatAsEsm. It broke in three places:

Top-level await and import.meta. My MCP server file had an if (import.meta.url === ...) block with a top-level await to start the server when run directly. As CommonJS, Jest failed to parse it: "await is only valid in async functions and the top level bodies of modules". I moved the entry point to its own main.ts, which is cleaner anyway, and used the same code for all three runners.
Realm mismatches with node:assert. Jest runs each file in a vm context with its own Object.prototype. Objects created by Node's globals, like Response.json() from fetch or structuredClone(), come from the outer realm. assert.deepStrictEqual checks prototypes, so it failed with "Compared values have no visual difference". Jest's own expect().toEqual() and toStrictEqual() passed on the same objects. Vitest's default pool and node:test didn't have the problem. I changed those tests to JSON.parse(await r.text()) for all runners.
jest.mock hoisting. With @swc/jest 0.2.39, a jest.mock() call wasn't hoisted when jest was imported from @jest/globals. The real module ran, and my "must not send email" guard threw. Using the global jest object fixed it, and so did ts-jest, which hoisted the same file correctly.

For native ESM, add extensionsToTreatAsEsm: [".ts"], tell SWC to keep ES modules, and start Node with --experimental-vm-modules. On Node 24.22, Jest 30.5 still printed "VM Modules is an experimental feature" for every worker. In this mode, module mocks use jest.unstable_mockModule() followed by a dynamic import().

// jest.esm.config.cjs, run with NODE_OPTIONS=--experimental-vm-modules
module.exports = {
  testEnvironment: "node",
  testMatch: ["<rootDir>/test/**/*.test.ts"],
  extensionsToTreatAsEsm: [".ts"],
  transform: { "^.+\\.ts$": ["@swc/jest", { module: { type: "es6" } }] },
};

Jest with ts-jest

ts-jest uses the TypeScript compiler, so it type-checks your tests, which explains the 3.1 s run. It also brings tsconfig friction. My project tsconfig uses "module": "nodenext" and verbatimModuleSyntax in a "type": "module" package, and ts-jest's CommonJS mode failed every file with TS1295: "ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'". I needed a separate tsconfig.jest.json with "module": "commonjs", verbatimModuleSyntax: false, and a paths entry for the #t import (Node-style imports aren't resolved with node10 resolution). You also can't move to TypeScript 7 with ts-jest yet, because of the <7 peer range.

node:test

{
  "scripts": {
    "test": "node --test \"test/**/*.test.ts\"",
    "test:watch": "node --test --watch \"test/**/*.test.ts\"",
    "test:cov": "node --test --experimental-test-coverage --test-coverage-include=\"src/**\" \"test/**/*.test.ts\""
  }
}

No dependencies and no config. Node 24 strips types by default, and the test runner finds .ts files from the glob. The price is that your TypeScript has to be erasable: Node removes types but doesn't compile anything. I checked each case on Node 24.22.1:

Syntax	`node file.ts`	`--experimental-transform-types`
`enum Status { ... }`	ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX	works
`constructor(private readonly repo: Repo)`	ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX	works
`@Injectable()` decorator	ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX	SyntaxError

So a NestJS codebase full of decorators and parameter properties can't run under plain node --test. My orders service is written NestJS-style, with constructor injection, but it assigns dependencies to private fields by hand instead of using parameter properties. That makes it erasable, and "erasableSyntaxOnly": true in tsconfig keeps it that way. You also need .ts extensions in relative imports (allowImportingTsExtensions plus noEmit for tsc) and import type for type-only imports (verbatimModuleSyntax).

Mocking APIs compared

The same two jobs in each runner: replace an ES module that sends email, and fake a 60-second timer. All three files below passed.

// Vitest: vi.mock is hoisted above the imports
import { vi, it, expect } from "vitest";
import { sendReceipt } from "./receipts.ts";
import { sendEmail } from "./mailer.ts";
vi.mock("./mailer.ts", () => ({ sendEmail: vi.fn(async () => ({ id: "msg_1" })) }));

it("mocks an ES module", async () => {
  expect(await sendReceipt("a@b.co", 7)).toBe("msg_1");
  expect(sendEmail).toHaveBeenCalledWith("a@b.co", "Receipt for order #7");
});
// timers: vi.useFakeTimers(); vi.advanceTimersByTime(60_000);

// Jest (CommonJS output): use the global jest object so jest.mock gets hoisted
import { sendReceipt } from "./receipts.ts";
import { sendEmail } from "./mailer.ts";
jest.mock("./mailer.ts", () => ({ sendEmail: jest.fn(async () => ({ id: "msg_1" })) }));
// timers: jest.useFakeTimers(); jest.advanceTimersByTime(60_000);

// node:test: needs --experimental-test-module-mocks, then a dynamic import
import { mock, it } from "node:test";
import assert from "node:assert/strict";
const sendEmail = mock.fn(async (_to: string, _subject: string) => ({ id: "msg_1" }));
mock.module("./mailer.ts", { exports: { sendEmail } });
const { sendReceipt } = await import("./receipts.ts");

it("mocks an ES module", async () => {
  assert.equal(await sendReceipt("a@b.co", 7), "msg_1");
  assert.deepEqual(sendEmail.mock.calls[0].arguments, ["a@b.co", "Receipt for order #7"]);
});
// timers: mock.timers.enable({ apis: ["setTimeout"] }); mock.timers.tick(60_000);

Vitest has the smoothest module mocking for ESM. Jest's is fine in CommonJS but needs unstable_mockModule and dynamic imports in ESM. Node's mock.module() works, but it's experimental: without the flag, mock.module is not a function. Node 24 also prints a deprecation warning if you use the older namedExports option instead of exports. Node's mock.fn(), mock.method() and mock.timers need no flag and covered everything else I needed. For most service code, constructor injection with hand-written fakes, like this suite uses, avoids module mocking altogether.

Which test runner should you use?

Pick Vitest for a new TypeScript or ESM project, a Vite or React frontend, or a NestJS 12 app. It needed the least configuration, handled ESM and top-level await without flags, and has the best mocking and watch experience. Its default per-file process isolation is the slowest option at scale, so try pool: "vmThreads" or isolate: false once your suite is stable. Those settings made it the fastest or close to it in my runs.

Keep Jest if you have a large, working Jest suite, especially CommonJS. With @swc/jest it was the fastest default configuration here, and moving to Vitest is mostly an API rename (jest.fn to vi.fn) that buys you little speed unless you also change isolation. Swap ts-jest for @swc/jest and run tsc --noEmit separately: that alone took this suite from 3.13 s to 0.81 s.

Pick node:test for libraries, CLIs and backend code written in erasable TypeScript, where zero dependencies matters. It had the fastest single-file runs (0.18 s) and the fastest full run without isolation (0.51 s). You give up a rich expect, snapshot ergonomics and stable module mocking, and decorator-heavy code won't run. If you're comparing runtimes too, I measured Bun against Node separately, and I covered what changes in TypeScript 7 for build tooling.

FAQ

Is Vitest faster than Jest?

Not with default settings in my test. On a 39-file TypeScript suite, Jest 30.5 with @swc/jest took 0.81 s warm and Vitest 5.1 took 1.51 s, because Vitest's default forks pool starts a process per test file. With isolate: false Vitest took 0.68 s, and with pool: vmThreads 0.91 s. At 156 files the default gap grew to 1.52 s for Jest against 5.03 s for Vitest.

Can node:test run TypeScript without a loader?

Yes, on Node 24 type stripping is on by default and node --test picks up .ts files from a glob. It only removes types, so enums, constructor parameter properties and decorators fail with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX. You also need .ts extensions in relative imports and import type for type-only imports.

Should I use ts-jest or @swc/jest?

Use @swc/jest and run tsc --noEmit as a separate step. In my runs ts-jest took 3.13 s warm because it type-checks every file, against 0.81 s for @swc/jest, while tsc on the whole project took about 1.5 s. ts-jest 29.4.15 also declares typescript below 7, so it doesn't support TypeScript 7 yet.

Does Jest support ESM in 2026?

Yes, but still behind Node's --experimental-vm-modules flag. Jest 30.5 on Node 24.22 ran my suite as native ESM in 1.01 s warm, but printed an experimental warning for every worker, and module mocks need jest.unstable_mockModule plus a dynamic import. Compiling to CommonJS with @swc/jest avoids the flag but breaks top-level await and import.meta.

Which test runner has the fastest watch mode?

They were close. After editing a file imported by 3 test files, Vitest reran in 0.23 s, jest --watch in 0.25 s and node --test --watch in 0.31 s, and all three reran only the affected files. jest --watch needs a git repository; jest --watchAll reruns every file.

Originally published on fabwaseem.com.

Postgres LISTEN/NOTIFY vs Redis Pub/Sub: Latency, Write Cost and Failure Cases, Tested

Waseem Anjum — Mon, 02 Nov 2026 13:14:34 +0000

Cross-posted from my blog. The original, with any updates, lives on fabwaseem.com.

If you already run Postgres, you can push realtime events to your app without adding Redis: NOTIFY sends a message on commit, and every connection that ran LISTEN gets it. I measured Postgres 18 LISTEN/NOTIFY against Redis 8 Pub/Sub for delivery latency, fan-out, and the cost to the transactions that send the events. I also checked what each one does when a message is too big, when a transaction rolls back, and when a listener disconnects. The short answer: Postgres is fast enough for most realtime features, and it's the safer choice when the event describes a database write. Redis has steadier tail latency under load.

What I tested

Everything ran on one 8 vCPU / 16 GB Linux VM on October 30, 2026: PostgreSQL 18.6 (fsync and synchronous_commit on, shared_buffers=512MB), Redis 8.0.2 with persistence off, Node.js 22.20, pg 8.23.1 and ioredis 6.0.0. Subscribers ran in separate Node processes. Publishers sent 100-byte JSON messages with a timestamp, and subscribers measured the time until the message arrived. Each fan-out test ran 10 seconds, and I report the median of 3 runs.

This is one machine with client and server on localhost, so the numbers show how the two compare, not what you'll see across a network.

Delivery latency and fan-out

Subscribers	Messages/s	Postgres p50	Postgres p99	Redis p50	Redis p99
1	1,000	0.34 ms	0.99 ms	0.17 ms	0.92 ms
1	10,000	0.18 ms	2.60 ms	0.19 ms	1.07 ms
1	25,000	0.39 ms	5.65 ms	0.16 ms	0.69 ms
10	1,000	0.22 ms	2.60 ms	0.17 ms	1.15 ms
10	10,000	0.34 ms	9.83 ms	0.23 ms	0.96 ms
100	1,000	0.52 ms	4.32 ms	0.36 ms	2.39 ms

Neither lost a message in any run. The typical (p50) delivery time is under a millisecond for both. The difference is in the tail: as the message rate or listener count goes up, Postgres p99 climbs faster, and it spikes more between runs. With 10 listeners at 10,000 messages a second, Postgres p99 ranged from 5.8 ms to 79.6 ms across the three runs, while Redis stayed between 0.9 and 2.2 ms. One Postgres run at 25,000 messages a second hit a 113.7 ms p99.

For chat messages, notifications, dashboard refreshes and "your export is ready" events, a few milliseconds at p99 doesn't matter. For a high-rate stream where tail latency matters, Redis is the steadier option.

What NOTIFY costs the writer

Latency is only half of it. The bigger question is what happens to the transactions that send the events. I ran 16 and 64 clients, each doing BEGIN, an INSERT into an events table, and COMMIT, for 10 seconds:

Mode	16 clients (tx/s)	64 clients (tx/s)
Plain INSERT	22,990	25,346
INSERT + `pg_notify` in the same statement	13,668 to 17,360	14,246 to 17,254
INSERT with an `AFTER INSERT` trigger calling `pg_notify`	18,596	13,760 to 15,716
INSERT, commit, then Redis `PUBLISH`	20,756	19,334 to 19,506

The ranges are separate 10-second runs, with and without a listener connected. These runs were noisy, so read them as a band, not exact figures. Sending a notification in the transaction cost roughly 20 to 45% of commit throughput in my runs. Committing a transaction that sent a NOTIFY adds its messages to a single shared queue, and Postgres holds a database-wide lock while it does that so notifications stay in commit order. The commits that notify take turns.

Publishing to Redis after the commit costs the database much less, because Postgres does nothing extra. But you get that speed by giving up the guarantee in the next section.

Behavior checks: where they really differ

I scripted each of these against both systems. Here's what I found:

Check	Postgres LISTEN/NOTIFY	Redis Pub/Sub
Message sent inside a transaction that rolls back	Not delivered	Delivered if you published before the rollback: the subscriber got an event for a row that doesn't exist
When listeners see it	Only after `COMMIT` (0 seen before, 1 after)	Immediately on `PUBLISH`
Payload size	7,999 bytes OK, 8,000 bytes fails with "payload string too long"	1 MB delivered fine
Same channel and payload sent 6 times in one transaction	Collapsed: listener got 2 (the 2 distinct payloads)	Every publish delivered
Listener offline while 10 messages were sent	0 received after reconnect	0 received after reconnect
Slow consumer	A listener stuck in an open transaction holds the queue: 200,000 notifications of 1 KB filled 2.4% of it, cleared after the listener committed	Subscriber was disconnected after about 35 MB of unread messages (`client-output-buffer-limit pubsub 32mb 8mb 60`)

Three of these matter in practice.

NOTIFY is transactional. If the insert rolls back, nobody hears about it. With Redis you either publish before the commit and risk announcing a write that never happened, or publish after it and risk losing the event if the process crashes between COMMIT and PUBLISH. For "this row changed" events, Postgres gets this right without extra code.

Both are fire-and-forget. A listener that is disconnected misses everything sent while it was gone. Neither system queues messages for you. If you need delivery guarantees, use a job queue or Redis Streams. I compared Postgres job queues with BullMQ separately.

Postgres collapses duplicates in a transaction. If you send the same channel and payload twice in one transaction, listeners get it once. That's good for "something changed, refetch" signals and surprising if you use NOTIFY as a counter.

The pattern I use: NOTIFY as a doorbell, the table as the truth

Because notifications can be missed and payloads are capped below 8,000 bytes, I don't put the data in the notification. I write the event to a table, send only the row id in the NOTIFY, and let the server read the row. A reconnecting client catches up from the table using the last id it saw. Here's the whole thing with Node's built-in HTTP server and Server-Sent Events, one LISTEN connection per process, fanned out to browsers by room:

// server.mjs: one LISTEN connection per Node process, fanned out to many SSE clients.
// The events table is the source of truth; NOTIFY is only the doorbell.
import http from 'node:http';
import pg from 'pg';

const cfg = { connectionString: process.env.DATABASE_URL };
const pool = new pg.Pool(cfg);
const rooms = new Map(); // room -> Set<{ res, lastId }>

function send(client, row) {
  const id = Number(row.id); // bigserial comes back from pg as a string: compare numbers, not strings
  if (id <= client.lastId) return; // already sent (backfill + notify can overlap)
  client.res.write(`id: ${id}\ndata: ${JSON.stringify(row)}\n\n`);
  client.lastId = id;
}

async function backfill(room, client) {
  const { rows } = await pool.query(
    'SELECT id, room, body FROM events WHERE room = $1 AND id > $2 ORDER BY id LIMIT 500',
    [room, client.lastId],
  );
  for (const row of rows) send(client, row);
}

async function listen() {
  const listener = new pg.Client(cfg);
  let chain = Promise.resolve(); // handle notifications one at a time so ids stay in order
  listener.on('notification', ({ payload }) => {
    chain = chain.then(async () => {
      const { id, room } = JSON.parse(payload); // payload stays tiny: ids only (8000-byte limit)
      const subs = rooms.get(room);
      if (!subs?.size) return;
      const { rows } = await pool.query('SELECT id, room, body FROM events WHERE id = $1', [id]);
      if (rows[0]) for (const c of subs) send(c, rows[0]);
    }).catch(console.error);
  });
  listener.on('error', (err) => console.error('listener error:', err.message));
  listener.on('end', () => {
    // Notifications sent while we're disconnected are gone. Reconnect, then backfill from the table.
    setTimeout(() => listen().catch(console.error), 500);
  });
  await listener.connect();
  await listener.query('LISTEN events');
  for (const [room, subs] of rooms) for (const c of subs) await backfill(room, c);
}

http.createServer(async (req, res) => {
  const url = new URL(req.url, 'http://x');
  if (url.pathname === '/events') {
    const room = Number(url.searchParams.get('room'));
    const client = { res, lastId: Number(req.headers['last-event-id'] ?? 0) };
    res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
    res.write(': connected\n\n');
    if (!rooms.has(room)) rooms.set(room, new Set());
    rooms.get(room).add(client);
    req.on('close', () => rooms.get(room)?.delete(client));
    await backfill(room, client); // catch up after a browser reconnect (Last-Event-ID)
    return;
  }
  if (req.method === 'POST' && url.pathname === '/messages') {
    let raw = ''; for await (const chunk of req) raw += chunk;
    const { room, text } = JSON.parse(raw);
    // INSERT and NOTIFY in one statement: the notification is sent only if the row commits
    const { rows } = await pool.query(
      `WITH ins AS (INSERT INTO events (room, body) VALUES ($1, $2) RETURNING id, room)
       SELECT id, pg_notify('events', json_build_object('id', id, 'room', room)::text) FROM ins`,
      [room, { text }],
    );
    res.writeHead(201, { 'content-type': 'application/json' }).end(JSON.stringify({ id: rows[0].id }));
    return;
  }
  res.writeHead(404).end();
}).listen(process.env.PORT ?? 3400, () => listen().catch(console.error));

The table is CREATE TABLE events (id bigserial primary key, room int not null, body jsonb not null).

I tested it with a script that opens three SSE clients (two in room 1, one in room 2), posts 10 messages, then kills the server's LISTEN connection with pg_terminate_backend and posts 3 more while it's down. Results on PostgreSQL 18.6:

Each room-1 client got its 5 messages, and the room-2 client got only room-2 messages.
After the listener was killed, the server reconnected and the backfill delivered all 3 "gap" messages, with 0 duplicates.
A browser reconnecting with Last-Event-ID got exactly the 3 messages it had missed.

The bug the test caught. My first version compared row.id <= client.lastId directly. pg returns bigint and bigserial columns as strings, because they can be larger than JavaScript numbers can hold exactly. Once ids reached two digits, "10" <= "8" was true as a string comparison. The room-2 client silently dropped its 5th message, and the backfill after the reconnect sent nothing. Converting with Number() fixed both. If your ids may go past 2^53, compare BigInts instead.

Production notes

Use a direct connection for LISTEN. PgBouncer in transaction pooling mode doesn't support LISTEN, because your session isn't kept between transactions. Keep one dedicated connection per app instance for listening and use the pool for everything else.
Never sit in an open transaction on the listening connection. Notifications are delivered between transactions. A listener that stays inside a transaction holds the shared queue for everyone, and the queue is 8 GB by default. Watch SELECT pg_notification_queue_usage().
Send ids, not data. The payload limit is just under 8,000 bytes, and a small payload keeps the queue small.
Plan for missed messages. Both Postgres and Redis drop messages for anyone who isn't connected. Backfill from a table, or use a queue when every event must be processed.
Watch notify-heavy write paths. If one table does thousands of commits a second, test the throughput cost above on your own hardware before adding a trigger that notifies on every row.

Which one should you use?

Use Postgres LISTEN/NOTIFY when the events come from your own database writes: new chat messages, order status changes, "this job finished", cache invalidation. You get transactional delivery and no extra service to run. That's how I'd add realtime updates to a NestJS app with Server-Sent Events that already uses Postgres.

Use Redis Pub/Sub when you need steadier latency at high message rates, payloads above 8 KB, or events that don't come from a database write, like presence, typing indicators or live cursors. If you already run Redis for BullMQ job queues, adding Pub/Sub costs nothing extra.

Use neither when every message must be processed. That's a job queue or a stream.

FAQ

Is Postgres LISTEN/NOTIFY fast enough for realtime apps?

For most apps, yes. In my test on PostgreSQL 18.6 the median delivery time was 0.18 to 0.52 ms from 1 to 100 listeners at up to 25,000 messages a second, with no lost messages. Its p99 latency was higher and less steady than Redis Pub/Sub under load, up to about 10 ms at 10,000 messages a second with 10 listeners.

Does NOTIFY slow down writes?

It can. With 16 to 64 clients doing single-row inserts, sending pg_notify in the same transaction ran at about 55 to 80% of plain insert throughput in my runs. Commits that send notifications append to one shared queue in commit order, so they take turns.

Is a NOTIFY sent if the transaction rolls back?

No. Notifications are delivered only when the transaction commits, and a rolled-back transaction sends nothing. Redis Pub/Sub has no link to your database transaction, so a publish before the rollback still reaches subscribers.

What is the maximum NOTIFY payload size?

The payload must be shorter than 8,000 bytes in a default PostgreSQL build. In my test a 7,999-byte payload worked and 8,000 bytes failed with 'payload string too long'. Send an id and read the row instead.

Does LISTEN/NOTIFY work with PgBouncer?

Not in transaction pooling mode, because LISTEN needs the same session to stay connected. Use one direct database connection per app instance for LISTEN and the pool for everything else.

Originally published on fabwaseem.com.

How to Test an MCP Server: Vitest, In-Memory Transport, Streamable HTTP and the Inspector CLI

Waseem Anjum — Sat, 31 Oct 2026 06:05:29 +0000

Cross-posted from my blog. The original, with any updates, lives on fabwaseem.com.

Testing an MCP server means checking three layers: the pure functions behind your tools, the MCP contract (tool list, schemas, results and errors), and the transport your clients actually use. You can cover all three with Vitest and the official TypeScript SDK, without starting an AI client, and the whole suite below runs in about 300 ms.

I wrote this while building Benchline, my set of browser tools that are also a stateless MCP server. Every tool there is a pure function first and an MCP tool second, and that split is what makes testing easy. Below is a small, complete example server you can copy, the tests I run against it, and the MCP Inspector CLI commands for manual checks. Everything was run with @modelcontextprotocol/sdk 1.32.2, Vitest 5.0.5 and Node 22.20, and I re-ran the full suite on October 31, 2026 (1.32.2 is still the latest SDK release) with the same result.

TL;DR

Unit-test the logic as plain functions. Most bugs live there, and these tests need no MCP at all.
Contract-test the server in memory with InMemoryTransport.createLinkedPair() and a real SDK Client: list tools, check schemas, call each tool, and assert on errors.
Test the transport once over Streamable HTTP: the SDK client connects, initialize returns 200, wrong Accept headers get 406, GET gets 405 on a stateless server.
Check by hand with npx @modelcontextprotocol/inspector --cli <url> --transport http --method tools/list.
In SDK 1.32.2, a schema failure and an unknown tool both came back as a tool result with isError: true, not as a thrown error. Write your assertions so they hold either way.

The server under test

Two read-only tools: slugify, with a typed output schema, and json_format, which must report bad input as an error result instead of crashing.

```ts title="src/server.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function slugify(input: string) {
return input.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase()
.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
}

export function createServer() {
const server = new McpServer({ name: "demo-tools", version: "1.0.0" });

server.registerTool("slugify", {
title: "Slugify",
description: "Turn a title into a URL slug (lowercase ASCII, words joined by hyphens).",
inputSchema: { text: z.string().min(1).max(500) },
outputSchema: { slug: z.string() },
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
}, async ({ text }) => {
const slug = slugify(text);
return { content: [{ type: "text", text: slug }], structuredContent: { slug } };
});

server.registerTool("json_format", {
title: "Format JSON",
description: "Pretty-print a JSON string with the given indent. Returns an error result for invalid JSON.",
inputSchema: { json: z.string(), indent: z.number().int().min(0).max(8).default(2) },
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
}, async ({ json, indent }) => {
try {
return { content: [{ type: "text", text: JSON.stringify(JSON.parse(json), null, indent) }] };
} catch (e) {
return { isError: true, content: [{ type: "text", text: Invalid JSON: ${(e as Error).message} }] };
}
});

return server;
}




The key design choice is that `slugify` is exported on its own. The MCP handler is a thin wrapper, so the logic is tested like any other function.

## Layer 1: unit tests for the tool logic



```ts title="test/unit.test.ts"
import { describe, it, expect } from "vitest";
import { slugify } from "../src/server.ts";

describe("slugify (pure function)", () => {
  it("lowercases and joins words", () => expect(slugify("Hello, MCP World!")).toBe("hello-mcp-world"));
  it("strips accents", () => expect(slugify("Crème Brûlée")).toBe("creme-brulee"));
  it("trims separators", () => expect(slugify("  --a--  ")).toBe("a"));
});

Nothing MCP-specific here, and that is the point. In Benchline, each tool folder has a pure lib/ covered by Vitest. The MCP layer only maps inputs and outputs.

Layer 2: contract tests with the in-memory transport

The SDK ships InMemoryTransport, which links a client and a server inside one process. You test the real protocol (JSON-RPC messages, schema validation, result shapes) with no ports and no network.

```ts title="test/mcp.test.ts"
import { describe, it, expect, beforeAll, afterAll } from "vitest";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { createServer } from "../src/server.ts";

let client: Client;
beforeAll(async () => {
const [clientT, serverT] = InMemoryTransport.createLinkedPair();
await createServer().connect(serverT);
client = new Client({ name: "test", version: "1.0.0" });
await client.connect(clientT);
});
afterAll(() => client.close());

describe("MCP contract (in-memory)", () => {
it("lists tools with object schemas and descriptions", async () => {
const { tools } = await client.listTools();
expect(tools.length).toBeGreaterThan(0);
for (const t of tools) {
expect(t.name).toMatch(/^[a-z][a-z0-9_]{0,63}$/);
expect(t.description?.length).toBeGreaterThan(20);
expect(t.inputSchema.type).toBe("object");
expect(t.annotations?.readOnlyHint).toBe(true);
}
expect(new Set(tools.map((t) => t.name)).size).toBe(tools.length);
});

it("returns structured content that matches the output schema", async () => {
const r = await client.callTool({ name: "slugify", arguments: { text: "Hello MCP" } });
expect(r.isError).toBeFalsy();
expect(r.structuredContent).toEqual({ slug: "hello-mcp" });
});

it("applies schema defaults", async () => {
const r = await client.callTool({ name: "json_format", arguments: { json: '{"a":1}' } });
expect((r.content as any)[0].text).toBe('{\n "a": 1\n}');
});

it("reports bad input as a tool error, not a crash", async () => {
const r = await client.callTool({ name: "json_format", arguments: { json: "{oops" } });
expect(r.isError).toBe(true);
expect((r.content as any)[0].text).toMatch(/^Invalid JSON/);
});

it("rejects arguments that fail the input schema", async () => {
const r = await client.callTool({ name: "slugify", arguments: { text: "" } }).catch((e) => e);
if (r instanceof Error) expect((r as any).code).toBe(-32602);
else expect((r as any).isError).toBe(true);
});

it("errors on unknown tools", async () => {
const r = await client.callTool({ name: "nope", arguments: {} }).catch((e) => e);
expect(r instanceof Error ? true : (r as any).isError).toBe(true);
});
});




What these tests catch:

- **Schema regressions.** Every tool must have an object `inputSchema` and a useful description. A model picks tools by name and description, so an empty description is a real bug.
- **Annotation drift.** If a tool is meant to be read-only, assert `readOnlyHint`. Clients can use annotations to decide when to ask the user for confirmation.
- **Duplicate names** after a refactor.
- **Error shape.** A handler that throws on bad input is worse than one that returns `isError: true` with a clear message, because the model can read the message and retry.

Two results surprised me, so I logged them before writing the assertions. With SDK 1.32.2, calling `slugify` with an empty string (which fails `min(1)`) and calling a tool that doesn't exist both resolved to a result with `isError: true`. The unknown-tool text was `MCP error -32602: Tool nope not found`. Older SDK versions and other server frameworks may throw a JSON-RPC error instead, so the tests accept both shapes.

## Layer 3: the Streamable HTTP transport

Clients like Cursor, Claude Code and VS Code connect over HTTP, so test that path once. This server is stateless: a new `McpServer` and transport per request and no session ID. Benchline's public endpoint is stateless in the same way: no API key and no session.



```ts title="src/http.ts"
import { createServer as createHttpServer } from "node:http";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { createServer } from "./server.ts";

// Stateless Streamable HTTP: a new server + transport per request, no session id.
export function startHttp(port = 0) {
  const http = createHttpServer(async (req, res) => {
    if (req.url !== "/mcp") { res.writeHead(404).end(); return; }
    if (req.method !== "POST") { res.writeHead(405, { Allow: "POST" }).end(); return; }
    const chunks: Buffer[] = []; for await (const c of req) chunks.push(c as Buffer);
    const body = JSON.parse(Buffer.concat(chunks).toString() || "null");
    const server = createServer();
    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
    res.on("close", () => { transport.close(); server.close(); });
    await server.connect(transport);
    await transport.handleRequest(req, res, body);
  });
  return new Promise<{ url: URL; close: () => void }>((resolve) =>
    http.listen(port, "127.0.0.1", () => {
      const { port } = http.address() as { port: number };
      resolve({ url: new URL(`http://127.0.0.1:${port}/mcp`), close: () => http.close() });
    }));
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const { url } = await startHttp(Number(process.env.PORT ?? 3321));
  console.log(`MCP server on ${url}`);
}

```ts title="test/http.test.ts"
import { describe, it, expect, beforeAll, afterAll } from "vitest";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { startHttp } from "../src/http.ts";

let srv: Awaited>;
const url = () => process.env.MCP_URL ? new URL(process.env.MCP_URL) : srv.url;
beforeAll(async () => { if (!process.env.MCP_URL) srv = await startHttp(); });
afterAll(() => srv?.close());

const init = { jsonrpc: "2.0", id: 1, method: "initialize",
params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "curl", version: "1" } } };

describe("Streamable HTTP transport", () => {
it("works with the official SDK client", async () => {
const c = new Client({ name: "http-test", version: "1.0.0" });
await c.connect(new StreamableHTTPClientTransport(url()));
const { tools } = await c.listTools();
expect(tools.length).toBeGreaterThan(0);
await c.close();
});

it("answers initialize without a session id (stateless)", async () => {
const r = await fetch(url(), { method: "POST", body: JSON.stringify(init),
headers: { "content-type": "application/json", accept: "application/json, text/event-stream" } });
expect(r.status).toBe(200);
expect(r.headers.get("mcp-session-id")).toBeNull();
});

it("rejects a client that does not accept both content types", async () => {
const r = await fetch(url(), { method: "POST", body: JSON.stringify(init),
headers: { "content-type": "application/json", accept: "application/json" } });
expect(r.status).toBe(406);
});

it("returns 405 for GET when there is no SSE stream", async () => {
const r = await fetch(url(), { headers: { accept: "text/event-stream" } });
expect(r.status).toBe(405);
});
});




All four passed. Facts worth pinning in tests, because a framework upgrade can silently change them:

- `initialize` returned **200** with no `mcp-session-id` header, so clients don't need to track a session.
- A request with `Accept: application/json` only returned **406**. The Streamable HTTP spec requires clients to accept both `application/json` and `text/event-stream`, and some hand-written clients and proxies don't.
- `GET /mcp` returned **405**, which tells clients there is no server-to-client SSE stream on a stateless server.
- In stateless mode, `tools/list` worked without an `initialize` call first. A raw curl got back a 1,120-byte JSON response for the two tools.

Set `MCP_URL` to run the same file against a deployed server: `MCP_URL=https://your-host/mcp npx vitest run test/http.test.ts`. I ran it against the local server started with `node src/http.ts`, and all 4 tests passed.

Response size is worth a test too. Everything in `tools/list` is sent to the model, so it costs context on every conversation. I measured why that matters in [MCP vs API](https://fabwaseem.com/blog/mcp-vs-api).

## Manual checks with the MCP Inspector CLI

The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) has a web UI and a CLI mode. The CLI is handy in a terminal or a CI smoke step (I first ran it with version 2.12.0, and the same commands gave the same output with 2.13.0, the latest release on October 31, 2026):



```bash title="Inspector CLI"
# list tools
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:3321/mcp \
  --transport http --method tools/list

# call one tool
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:3321/mcp \
  --transport http --method tools/call --tool-name slugify --tool-arg 'text=Hello MCP World'

The call printed:

{
  "content": [{ "type": "text", "text": "hello-mcp-world" }],
  "structuredContent": { "slug": "hello-mcp-world" }
}

And raw curl, for when you suspect the client:

```bash title="curl"
curl -s http://127.0.0.1:3321/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'




## Running it in CI



```json title="package.json (scripts)"
{
  "scripts": {
    "test": "vitest run",
    "test:remote": "vitest run test/http.test.ts"
  }
}

npm test runs all three layers. In 3 test files and 13 tests, Vitest reported a duration of 295 ms. Run test:remote with MCP_URL set after each deploy as a smoke test. It catches a broken proxy, a missing route or a CDN that strips headers, which is exactly what unit tests can't see.

What to test, as a checklist

Every tool: unit tests for its logic, including edge cases and bad input.
tools/list: unique names, object input schemas, descriptions long enough to be useful, expected annotations.
Each tool through callTool: one happy path, one error path that returns isError: true with a readable message.
Output schemas: structuredContent matches what you declared.
Transport: SDK client connects; initialize status and session header; Accept handling (406); GET behavior (405 when stateless).
Auth, if you have it: no token gets 401 with a WWW-Authenticate header, and a wrong-audience token is rejected. The MCP security guide covers the cases worth testing.
Size: keep an eye on the tools/list byte count as you add tools.

If you are building your first server, start with how to build an MCP server in Next.js and stateless MCP servers. Then connect it to your editor with how to add a remote MCP server.

FAQ

How do I test an MCP server without an AI client?

Use the official SDK's Client class in your test runner. Connect it to your server with InMemoryTransport.createLinkedPair() for fast in-process tests, or with StreamableHTTPClientTransport for the HTTP path, then call listTools and callTool and assert on the results. No model or editor is needed.

What is InMemoryTransport in the MCP SDK?

InMemoryTransport, exported from @modelcontextprotocol/sdk/inMemory.js, creates a linked pair of transports inside one process. Connect your server to one end and a Client to the other, and they exchange real JSON-RPC MCP messages without any network, which makes contract tests fast and deterministic.

How do I use the MCP Inspector CLI?

Run npx @modelcontextprotocol/inspector --cli followed by the server URL, --transport http and a method. For example --method tools/list lists tools, and --method tools/call --tool-name slugify --tool-arg 'text=Hello' calls one. It prints the JSON result, which makes it useful for scripts and CI smoke checks.

Should an MCP tool throw or return isError?

Return a result with isError: true and a clear text message for expected failures such as invalid input. The model can read the message and try again. In my tests with SDK 1.32.2, even schema validation failures and unknown tool names came back as isError results.

Why does my MCP server return 406 Not Acceptable?

The Streamable HTTP transport requires the client to send an Accept header listing both application/json and text/event-stream. A request with only Accept: application/json got 406 from the SDK's server transport in my test. Fix the client or the proxy that rewrites the header.

Originally published on fabwaseem.com.

Free OG Image Generator: Open Graph Image Sizes and Dynamic OG Images in Next.js

Waseem Anjum — Fri, 30 Oct 2026 07:03:55 +0000

Cross-posted from my blog. The original, with any updates, lives on fabwaseem.com.

A free OG image generator turns a title, a subtitle and a few colors into a 1200×630 PNG that link previews can display. I built one you can use right now, with no account and no watermark: open the free OG image generator. It exports a ready PNG, gives you a live image URL, and writes the matching Next.js opengraph-image.tsx file for the template you picked.

This guide covers what an OG image is, the correct Open Graph image size for every major platform, how to use the tool, how to generate dynamic OG images in Next.js with next/og, the exact meta tags you need, and how to debug a preview that refuses to update.

What is an OG image?

An OG (Open Graph) image is the picture a social network or messaging app shows when someone shares a link. The page declares it with an og:image meta tag, defined by the Open Graph protocol, and the platform downloads that URL. Without one, the platform shows no image or guesses one from the page, which rarely looks good.

The Open Graph protocol was created by Facebook and is now read by LinkedIn, Slack, Discord, WhatsApp, iMessage and most chat apps. X (Twitter) reads its own twitter:* tags first and falls back to Open Graph tags when they are missing.

Definition: an OG image is the image referenced by a page's og:image meta tag. A dynamic OG image is one rendered on request (or at build time) from code, usually with the page title baked in, instead of a static file designed by hand.

What is the correct Open Graph image size?

Use 1200×630 pixels, a 1.91:1 aspect ratio, as a PNG or JPG under 5 MB. Facebook recommends at least 1200×630 for high-resolution displays, LinkedIn asks for at least 1200×627 at 1.91:1, and X's large card crops toward 2:1 but displays a 1200×630 image fine. One 1200×630 file covers almost every platform.

Keep the important text inside a safe zone: leave roughly 60 to 80 px of padding on every side, because some apps crop the edges or round the corners. Large, high-contrast titles survive small mobile previews far better than paragraphs of small text.

What OG and Twitter card sizes does each platform use?

Each platform publishes slightly different rules, but they converge on 1.91:1. The table below lists the recommended size and the hard limits from each platform's own documentation, so you can design one image and know where it might be cropped.

Platform	Recommended size	Ratio	Limits from official docs	Tag read
Facebook	1200 × 630	1.91:1	Minimum 200 × 200; 600 × 315 for large previews; max 8 MB	`og:image`
LinkedIn	1200 × 627	1.91:1	Minimum 1200 × 627; max 5 MB	`og:image`
X (summary_large_image)	1200 × 600 to 1200 × 675	2:1	Minimum 300 × 157; max 4096 × 4096; under 5 MB; JPG, PNG, WEBP or GIF	`twitter:image`, falls back to `og:image`
X (summary)	144 × 144 or larger	1:1	Max 4096 × 4096; under 5 MB	`twitter:image`
Slack	1200 × 630	1.91:1	Unfurls use Open Graph tags	`og:image`
Discord	1200 × 630	1.91:1	Embeds use Open Graph tags	`og:image`
WhatsApp	1200 × 630	1.91:1	Small files load more reliably	`og:image`
Next.js file convention	1200 × 630	1.91:1	`opengraph-image` max 8 MB, `twitter-image` max 5 MB (build fails above)	generates both

Sources: Facebook image guidelines, LinkedIn sharing image requirements, X summary card with large image and the Next.js opengraph-image docs.

How do I use the free OG image generator?

Open the tool, pick a template, type your title, subtitle and author, choose a font and three colors, then click Download PNG. The preview updates as you type and always renders at 1200×630. You can also copy the image URL to use directly in og:image, or copy the Next.js code.

Step by step:

Go to tools.fabwaseem.com/t/og-image-generator.
Choose one of six templates: Blog post (title, dek and byline), Product / SaaS (launch card with a mark), Minimal (type and empty space), Gradient (full-bleed color), Code snippet (editor window) or Personal / profile (name, role and portrait).
Fill in the title, subtitle and author. For the product and profile templates you can add a logo or avatar URL (HTTPS only; PNG, JPEG, WebP or GIF up to 1.5 MB).
Pick a font: Inter, Syne, Space Grotesk, Playfair Display, JetBrains Mono or Urbanist.
Set the background, text and accent colors.
Click Download PNG, Copy URL, or Copy code for an opengraph-image.tsx file.

The PNG is rendered when its URL is requested and is not stored as a file. Browsers and the CDN may cache the exact URL for a day, so the same card loads fast the next time.

Can I use the generated image URL directly in my meta tags?

Yes. The Copy URL button gives you an absolute HTTPS link to /api/og-tool with your settings in the query string, and that URL always returns a 1200×630 PNG. Paste it into og:image and twitter:image. For production sites, downloading the PNG or using the generated Next.js file keeps you independent of a third-party URL.

Here is the shape of a generated URL (shortened):

https://www.fabwaseem.com/api/og-tool?template=blog&title=Ship+the+post+people+actually+share&subtitle=A+readable+1200%C3%97630+card&author=Waseem+Anjum&font=syne

How do I generate dynamic OG images in Next.js?

Add an opengraph-image.tsx file to any App Router segment and default-export a function that returns an ImageResponse from next/og. Next.js turns that route into an image and injects the og:image, og:image:width, og:image:height, og:image:type and og:image:alt tags into the page head automatically. No meta tags are written by hand.

This is the pattern from the official Next.js docs, adapted for a blog post route with a dynamic slug:

// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
import { getPost } from '@/lib/posts'

export const alt = 'Blog post cover'
export const size = { width: 1200, height: 630 }
export const contentType = 'image/png'

export default async function Image({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)
  const interSemiBold = await readFile(
    join(process.cwd(), 'assets/Inter-SemiBold.ttf')
  )

  return new ImageResponse(
    (
      <div
        style={{
          width: '100%',
          height: '100%',
          display: 'flex',
          flexDirection: 'column',
          justifyContent: 'flex-end',
          padding: 72,
          background: '#0C0C0C',
          color: '#F5F5F5',
        }}
      >
        <div style={{ display: 'flex', fontSize: 28, color: '#8FB4C9' }}>
          yoursite.com/blog
        </div>
        <div style={{ display: 'flex', fontSize: 72, lineHeight: 1.05, marginTop: 16 }}>
          {post.title}
        </div>
      </div>
    ),
    {
      ...size,
      fonts: [
        { name: 'Inter', data: interSemiBold, style: 'normal', weight: 600 },
      ],
    }
  )
}

A few facts from the docs worth knowing before you ship it:

The default export receives params as a Promise, so await it (Next.js 15 and later).
Generated images are statically optimized at build time and cached, unless they use request-time APIs or uncached data.
ImageResponse uses Satori and Resvg to turn JSX and CSS into a PNG. Only flexbox and a subset of CSS work; display: grid does not. Every div with more than one child needs display: 'flex'.
The ImageResponse reference lists a 500 KB maximum bundle size, which includes your JSX, CSS, fonts and images. Fonts must be TTF, OTF or WOFF.
Add a twitter-image.tsx with the same code if you want a separate X image; otherwise X falls back to og:image.

The free generator writes this file for you. Its output loads the chosen Google Font at render time with a small loadFont helper, so you can paste it into a segment and run it without adding font files.

Which meta tags does an OG image need?

At minimum you need og:title, og:description, og:url, og:type and og:image with an absolute HTTPS URL, plus twitter:card set to summary_large_image for a large X card. Adding og:image:width, og:image:height and og:image:alt helps platforms render the first share without waiting to download the image.

If you are not on Next.js, paste this into your <head>:

<meta property="og:type" content="article" />
<meta property="og:title" content="Your page title" />
<meta property="og:description" content="One sentence that earns the click." />
<meta property="og:url" content="https://example.com/blog/your-post" />
<meta property="og:image" content="https://example.com/og/your-post.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:alt" content="Short description of the image" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="Your page title" />
<meta name="twitter:description" content="One sentence that earns the click." />
<meta name="twitter:image" content="https://example.com/og/your-post.png" />

In the Next.js App Router you can set the same values with the Metadata API. Set metadataBase in your root layout so relative image paths resolve to absolute URLs:

// app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  metadataBase: new URL('https://example.com'),
  openGraph: {
    images: [{ url: '/og.png', width: 1200, height: 630, alt: 'Example' }],
  },
  twitter: { card: 'summary_large_image' },
}

How do I test and debug an OG image?

Paste the page URL into the Facebook Sharing Debugger and the LinkedIn Post Inspector, then click scrape again to clear their cache. Open the og:image URL in a browser to confirm it returns a 200 image. Finally, drop the link into Slack or Discord and check the unfurl. Most broken previews are a relative URL, a blocked crawler or a stale cache.

Testing tools:

Facebook Sharing Debugger: shows exactly which tags Facebook read and lets you force a re-scrape.
LinkedIn Post Inspector: refreshes LinkedIn's cached preview.
curl -I https://example.com/og.png: should return 200 and content-type: image/png.
curl -s https://example.com/page | grep og:image: confirms the tag is in the server HTML, not added later by client JavaScript.

Common causes and fixes:

Symptom	Likely cause	Fix
No image at all	`og:image` is a relative path	Use an absolute https URL; in Next.js set `metadataBase`
Old image keeps showing	Platform cache	Re-scrape in the debugger; add a version query like `?v=2`
Works in production, not on localhost	Crawlers cannot reach localhost	Test on a preview deployment or a tunnel
Image cropped badly on X	Ratio far from 2:1 or text near the edges	Use 1200×630 with 60 to 80 px padding
Next.js build fails on the image	File over 8 MB (OG) or 5 MB (Twitter)	Compress, or generate with code
`ImageResponse` layout is broken	Unsupported CSS such as grid	Use flexbox and `display: 'flex'` on parents
Tag missing in page source	Set in a client component	Set metadata on the server (Metadata API or file convention)

Static OG image or dynamic OG image: which should I use?

Use a static 1200×630 file for pages that rarely change, such as the home page, and dynamic OG images for content that grows, such as blog posts, docs and product pages. Dynamic images keep every share on-brand automatically, while a static file is the simplest and fastest option for a handful of pages.

	Static file	Dynamic (`next/og`)	Free generator URL
Setup	Design once, drop in `app/`	Write `opengraph-image.tsx`	Copy one URL
Per-page titles	Manual	Automatic	One URL per page
Best for	Home, landing pages	Blogs, docs, catalogs	Quick launches, side projects
Build impact	None	Rendered at build or on request	None

The generator sits in the middle: design visually, then either download a static PNG or copy the code to make it dynamic.

Frequently asked questions

Is this OG image generator really free?

Yes. It runs in the browser with no account, no sign-up and no watermark on the PNG. You can download images, copy the image URL or copy the Next.js code as often as you like.

What size is an OG image in Next.js?

The Next.js docs use size = { width: 1200, height: 630 } in opengraph-image.tsx, and ImageResponse defaults to 1200×630. Image files must stay under 8 MB for opengraph-image and 5 MB for twitter-image, or the build fails.

Do I need separate Twitter card images?

Usually not. X reads twitter:image first and falls back to og:image. Add twitter:card with the value summary_large_image so X shows the large card. Create a separate twitter-image only if you want a different design for X.

Why is my OG image not showing?

The most common reasons are a relative image URL, a page that blocks crawlers, a tag added by client-side JavaScript, or a cached old preview. Use an absolute https URL, check the server HTML and re-scrape in the Facebook Sharing Debugger.

Can I use WebP or SVG for OG images?

Use PNG or JPG for the widest support. X accepts WEBP, but SVG is not supported by the major platforms, and the Next.js file convention accepts JPG, PNG and GIF for static image files. The free generator always outputs PNG.

Does an OG image help SEO?

It does not directly change Google rankings, but it improves click-through when links are shared on social networks and in chat apps. For AI search visibility, pair it with good metadata and structured data, as covered in my Next.js SEO for AI search guide.

Key takeaways

Design every OG image at 1200×630 (1.91:1), under 5 MB, with 60 to 80 px of padding.
og:image must be an absolute HTTPS URL; in Next.js, set metadataBase.
In Next.js, an opengraph-image.tsx with ImageResponse from next/og generates the image and the meta tags for you. Use flexbox only.
Add twitter:card = summary_large_image; X falls back to og:image for the picture.
Always re-scrape in the Facebook Sharing Debugger and LinkedIn Post Inspector after changing an image.

Ready to make one? Create your free OG image now: pick a template, download the PNG or copy the Next.js code. For more of what I build, see my projects or head back to the home page.

Originally published on fabwaseem.com.

DEV Community: Waseem Anjum

Zod vs Valibot vs ArkType for MCP Tool Schemas

What I ran

One tool, three schemas

What the model sees in tools/list

Validation errors the model gets back

The datetime trap

Parse speed, and the ArkType clone setting

Cold start and bundle size

What I'm doing in my own MCP servers

FAQ

Can I use Valibot or ArkType instead of Zod for MCP tool schemas?

Why does my Valibot MCP tool fail at tools/list?

Why is ArkType slower than Zod in my benchmark?

Does Zod accept ISO datetimes with a timezone offset?

Which validation library has the smallest bundle?

NestJS Rate Limiting: In-Memory vs Redis vs Postgres

What I tested

Wiring @nestjs/throttler

Redis storage

Postgres storage (custom)

Latency (allowed requests)

Reject correctness

Multi-instance correctness

What I'd pick

FAQ

Does NestJS @nestjs/throttler work across multiple instances?

What Redis storage should I use with @nestjs/throttler?

Can I store NestJS rate limits in Postgres?

How much latency does NestJS rate limiting add?

Is in-memory rate limiting OK for production NestJS?

Run TypeScript in Node.js Without a Build Step: Type Stripping Tested on Node 22, 24 and 26

How Node.js type stripping works

What works out of the box

What fails (tested on Node 22, 24 and 26)

--experimental-transform-types is gone in Node 26

The tsconfig.json that catches every failure

Replacing enums

Startup time: node vs tsx vs precompiled JS

When to use built-in type stripping

FAQ

Can Node.js run TypeScript directly?

Does Node.js type stripping check types?

Why does my enum fail in Node.js?

Is --experimental-transform-types available in Node 26?

Do I still need tsx or ts-node?

Why do I need .ts in import paths?

NestJS vs Hono vs Fastify (2026): Benchmarked on Node.js 26

The test setup

The code

Results: requests per second (one core, higher is better)

Results: startup time and memory

What the numbers say

Caveats (read these before quoting the numbers)

Which one should you choose?

How to reproduce

FAQ

Is Hono faster than Fastify?

Is NestJS slower than Express?

Should I use the Fastify adapter in NestJS?

Is Express 5 faster than Express 4?

Which is best for a SaaS backend in 2026?

How to Build an MCP Server in NestJS: Streamable HTTP, Guards and DI (Tested)

Is there an official NestJS MCP module?

What I tested

Step 1: Install the packages

Step 2: A normal Nest provider for your data

Step 3: The MCP service (handler, tools and DI)

Step 4: A guard for the bearer token and Origin

Step 5: The controller

Step 6: Test it (curl, Inspector, e2e)

Five things that broke (and the fixes)

How fast is a per-request MCP server in NestJS?

Should you use @rekog/mcp-nest instead?

FAQ

Is there an official NestJS MCP package?

Can I use NestJS dependency injection inside MCP tools?

How do I add authentication to a NestJS MCP server?

Why does my NestJS MCP endpoint return Parse error -32700?

Does a NestJS MCP server work with older MCP clients?

Wiring `@nestjs/throttler`

`--experimental-transform-types` is gone in Node 26