DEV Community: Waseem Anjum

React View Transitions in Next.js 16.4: ViewTransition, addTransitionType and Tested Examples

Waseem Anjum — Sat, 24 Oct 2026 22:05:26 +0000

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

React View Transitions animate UI changes with the browser's View Transition API, declaratively. You wrap elements in <ViewTransition>, and React animates them when they enter, exit, update or move between pages. They became stable in React 19.3 on September 9, 2026, and Next.js 16.4 ships React 19.3, so they work in the App Router with no configuration.

I built a small Next.js 16.4.2 app with the four main patterns: a shared-element morph, a Suspense reveal, directional slides and a tab animation with addTransitionType. Then I recorded every transition in headless Chrome 155 to see what actually fires. Most of it behaves as documented. Browser back and forward do not, so that gets its own section below.

What are React View Transitions?

React View Transitions are the <ViewTransition> component and the addTransitionType function, stable since React 19.3. They hand animations to the browser's document.startViewTransition() from the View Transition API: the browser snapshots the old and new UI and animates between them, while React decides which elements take part and which CSS class each animation uses.

React picks the animation from how the tree changed. From the React 19.3 announcement:

Trigger	When it runs	Prop
enter	The `<ViewTransition>` is added	`enter`
exit	The `<ViewTransition>` is removed	`exit`
update	Its children change style or content	`update`
share	A named `<ViewTransition>` is removed in one place and added in another	`share`
(fallback)	Any trigger without its own prop	`default`

Each prop takes "auto" (the browser's crossfade), "none", a CSS class name you style, or an object that maps transition types to classes.

What triggers a view transition in React?

Only Transitions do. React animates updates inside startTransition, a <Suspense> boundary revealing its content, and updates from useDeferredValue. A plain setState does not animate, because React treats it as urgent. In Next.js App Router, every <Link> and router.push() navigation is a Transition, so <ViewTransition> animates route changes automatically.

This is the mistake behind most "my view transition doesn't run" reports. If you call setIndex(2) directly in a click handler, nothing animates. Wrap it in startTransition(() => setIndex(2)) and it does.

Do View Transitions need a flag in Next.js 16.4?

No. The Next.js view transitions guide says they "work in the App Router with no configuration." The experimental.viewTransition option that older versions needed is gone: I searched Next.js 16.4.2's config schema and it has no viewTransition key. You need React 19.3, which next@16.4 installs.

Requirements and support on October 17, 2026:

Requirement	Value
React	19.3.0 or newer (19.3.1 is `latest`)
Next.js	16.4 (ships React 19.3); App Router
Import	`import { ViewTransition, addTransitionType } from "react"`
Browsers	Chromium 125+, recent Safari and Firefox (per Next.js docs)
Unsupported browsers	The app works; changes happen without animation
Platforms	DOM only; React Native support is in progress

Next.js notes that "some animations may behave differently in Safari." Test there before you ship anything elaborate.

How do I add view transitions to a Next.js app?

Import ViewTransition from react, wrap the element you want to animate, and add CSS for the class names you pass. For route animations, give matching elements the same name on both pages, tag links with transitionTypes, and wrap each page.tsx (not the layout) in a <ViewTransition> that maps those types to animations.

My demo is a grid of four cards. Each card opens a detail page with a large hero, details that stream in from the server, and a tabs page. It runs Next.js 16.4.2, React 19.3.1 and cacheComponents: true (the default for new 16.4 apps), so each detail page is a partial prerender: a static shell plus a dynamic hole. The patterns follow the official Next.js view transitions demo, trimmed down so each one is easy to see.

Step 1: Morph a shared element between pages

Give the thumbnail and the hero the same name. React pairs them across the navigation and the browser animates size and position:

// app/page.tsx
import { ViewTransition } from "react";
import Link from "next/link";

{items.map((item) => (
  <Link key={item.id} href={`/item/${item.id}`} transitionTypes={["nav-forward"]}>
    <ViewTransition name={`card-${item.id}`} share="morph" default="none">
      <div className="card" style={{ background: item.color }}>{item.title}</div>
    </ViewTransition>
  </Link>
))}

// app/item/[id]/page.tsx
<ViewTransition name={`card-${item.id}`} share="morph" default="none">
  <div className="hero" style={{ background: item.color }}>{item.title}</div>
</ViewTransition>

default="none" stops the named element from crossfading during unrelated transitions. Next.js warns that with default="none" you must keep the explicit share, or "the pair silently stops morphing." Names must be unique on a page, so build them from an ID.

The morph needs both elements in the same commit. Next.js says this happens with prefetched pages; if the destination suspends first, "no pair forms." In my app the hero sits in the static shell, which <Link> prefetches, so it morphed on every click.

Step 2: Animate a Suspense reveal

Wrap the fallback in an exit animation and the content in an enter animation:

// app/item/[id]/page.tsx
<Suspense
  fallback={
    <ViewTransition exit="slide-down" default="none">
      <div className="skeleton">Loading details…</div>
    </ViewTransition>
  }
>
  <ViewTransition enter="slide-up" default="none">
    <Details id={item.id} />
  </ViewTransition>
</Suspense>

Details calls await connection(), so it renders at request time. When it streamed in, React started a second, separate view transition about 800 ms after the navigation one, which matches the delay I put in the data function.

Step 3: Slide forward and back

Tag links with transitionTypes, then map the types to classes in a wrapper you put in every page:

// components/directional.tsx
import { ViewTransition } from "react";

export function Directional({ children }: { children: React.ReactNode }) {
  return (
    <ViewTransition
      enter={{ "nav-forward": "nav-forward", "nav-back": "nav-back", default: "none" }}
      exit={{ "nav-forward": "nav-forward", "nav-back": "nav-back", default: "none" }}
      default="none"
    >
      {children}
    </ViewTransition>
  );
}

<Link href="https://www.fabwaseem.com/" transitionTypes={["nav-back"]}>← All cards</Link>

Use it in each page.tsx. Layouts persist across navigations, so enter and exit never fire on a wrapper placed there. useRouter().push() and replace() also accept transitionTypes.

Step 4: Pick the animation with addTransitionType

Outside navigation, call addTransitionType inside startTransition to tell React why the update happened. The same setIndex slides left or right depending on direction:

"use client";
import { ViewTransition, addTransitionType, startTransition, useState } from "react";

export function Tabs() {
  const [index, setIndex] = useState(0);

  function go(next: number) {
    startTransition(() => {
      addTransitionType(next > index ? "tab-next" : "tab-prev");
      setIndex(next);
    });
  }

  return (
    <>
      {tabs.map((t, i) => <button key={t} onClick={() => go(i)}>{t}</button>)}
      <ViewTransition
        key={index}
        enter={{ "tab-next": "from-right", "tab-prev": "from-left", default: "none" }}
        exit={{ "tab-next": "to-left", "tab-prev": "to-right", default: "none" }}
        default="none"
      >
        <div className="panel">{tabs[index]} panel</div>
      </ViewTransition>
    </>
  );
}

key={index} makes React treat each panel as a new element, so it runs exit on the old one and enter on the new one. React also adds each type to the browser's view transition, so CSS can match it with :active-view-transition-type(tab-next).

The CSS

The class names become selectors on the browser's view transition pseudo-elements:

::view-transition-group(.morph) { animation-duration: 400ms; }

::view-transition-old(.nav-forward) { --slide-offset: -60px; animation: 150ms ease-in both fade reverse, 400ms ease-in-out both slide reverse; }
::view-transition-new(.nav-forward) { --slide-offset: 60px; animation: 210ms ease-out 150ms both fade, 400ms ease-in-out both slide; }
::view-transition-old(.nav-back) { --slide-offset: 60px; animation: 150ms ease-in both fade reverse, 400ms ease-in-out both slide reverse; }
::view-transition-new(.nav-back) { --slide-offset: -60px; animation: 210ms ease-out 150ms both fade, 400ms ease-in-out both slide; }

/* Keep the header still and clicks working */
.site-header { view-transition-name: site-header; }
::view-transition-group(site-header) { animation: none; z-index: 100; }
::view-transition-old(site-header) { display: none; }
::view-transition-new(site-header) { animation: none; }
::view-transition { pointer-events: none; }

@keyframes fade { from { opacity: 0; } to { opacity: 1; } }
@keyframes slide { from { translate: var(--slide-offset); } to { translate: 0; } }

@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(*), ::view-transition-new(*), ::view-transition-group(*) {
    animation-duration: 0s !important;
    animation-delay: 0s !important;
  }
}

The pointer-events: none rule matters: while a transition runs, the ::view-transition overlay otherwise swallows clicks.

What did my test show?

Every in-app pattern worked as documented. A forward click produced one transition typed nav-forward with the card-2 pair morphing, then a second untyped transition when the streamed details arrived. Tabs got tab-next and tab-prev. Reduced motion kept the transitions but finished them in under 50 ms. Browser back and forward produced no view transition.

I wrapped document.startViewTransition in a Puppeteer script and logged each call's types, the pseudo-elements it animated, and how long it took to finish:

Action	View transitions started	Types	Finished in
Click card (grid to detail)	2: navigation, then Suspense reveal	`nav-forward`, then none	431 ms, 427 ms
Click "← All cards"	1	`nav-back`	433 ms
Tab 0 to 2	1	`tab-next`	350 ms
Tab 2 to 1	1	`tab-prev`	334 ms
Browser back button	0	n/a	n/a
Browser forward button	0	n/a	n/a
Card click with `prefers-reduced-motion: reduce`	2	`nav-forward`, then none	49 ms, 29 ms

Both navigation transitions included ::view-transition-old(card-2) and ::view-transition-new(card-2), which is the shared pair.

Do view transitions run on the browser back button?

Not in my test. Using the browser's back or forward button in Next.js 16.4.2 started no view transition at all, even for the named morph. It was a client-side navigation (same document, URL and grid restored), and zero calls reached startViewTransition. Use in-app back links with transitionTypes={["nav-back"]} for animated returns.

The Next.js guide says browser back navigations "do not carry a transition type, so the directional slide does not play," and that "the shared element morph from Step 1 still applies." In headless Chrome 155 against a production build (next start), I could not reproduce the morph on back or forward. Treat back-button animation as unreliable until you have tested it in your own app and browsers.

Common React View Transition mistakes

The usual problems are updates that are not Transitions, wrappers placed in layouts, duplicate names on one page, a destination that suspends before the morph can pair, and expecting the back button to animate. Each fails silently: the UI changes instantly with no error.

Mistake	Symptom	Fix
Plain `setState`	No animation	Wrap the update in `startTransition`
Wrapper in `layout.tsx`	Directional enter/exit never run	Put it in each `page.tsx`
Same `name` twice on a page	Broken or missing morph	Build names from IDs
Destination suspends before the hero renders	Content fades in instead of morphing	Keep the shared element in the static or prefetched shell
`default="none"` without `share`	Pair stops morphing (per Next.js docs)	Add `share="morph"` or `share="auto"`
No `pointer-events: none`	Clicks lost during animations	`::view-transition { pointer-events: none; }`
Relying on browser back	Nothing animates	In-app back links with `transitionTypes`
Ignoring reduced motion	Slides for motion-sensitive users	`prefers-reduced-motion` media query
Animating cached Suspense content	Content that's already loaded still fades in	`update="auto" default="none"` on the boundary

View Transitions vs Framer Motion (Motion)

Use View Transitions for route changes, shared elements across pages and loading reveals. The browser animates snapshots, so you add no animation library to your bundle. Keep Motion (formerly Framer Motion) for gestures, springs, drag, scroll-linked effects and animations that must respond while the user interacts.

Need	View Transitions	Motion
Morph between routes	Built in (`name`)	Needs layout animations plus shared state
Suspense loading reveal	Built in	Manual
Extra JavaScript	None (browser API)	A runtime library
Interruptible, gesture-driven	No (snapshot animations; hit-testing skips named elements while they run)	Yes
Springs and physics	CSS easing only	Yes
Browsers without support	Instant update	Animates

For the agent route, Next.js links a vercel-react-view-transitions skill you can install with npx skills add vercel-labs/agent-skills --skill vercel-react-view-transitions. My Agent Skills guide explains what that command installs. For the partial prerendering setup used in this demo, see my Next.js use cache guide.

Related: Next.js 16.4 also ships the experimental Rust React Compiler. I measured it against the Babel compiler and no compiler in React Compiler in Next.js 16.4: 20 counter clicks caused 0 row re-renders instead of 20,000.

Key takeaways

React View Transitions (ViewTransition and addTransitionType) are stable in React 19.3, released September 9, 2026, and work in Next.js 16.4 with no config flag.
Only Transitions animate: startTransition, Suspense reveals, useDeferredValue and Next.js navigations; a plain setState does not.
Give two elements the same name to morph them across routes, and keep the destination in a prefetched or static shell so they pair.
Tag links with transitionTypes and put the enter/exit wrapper in each page.tsx, not the layout.
In my test, browser back and forward buttons started no view transition at all, so use in-app back links for animated returns.
Add pointer-events: none on ::view-transition and a prefers-reduced-motion rule to every app.
Use View Transitions for page-level motion and keep Motion for gestures, springs and interactive animation.

FAQ

What are React View Transitions?

React View Transitions are the ViewTransition component and the addTransitionType function, stable since React 19.3 (September 9, 2026). They use the browser View Transition API to animate elements when they enter, exit, update or move between pages, while React chooses which elements take part and which CSS class each animation uses.

Do React View Transitions work in Next.js?

Yes. Next.js 16.4 ships React 19.3, and the Next.js docs say view transitions work in the App Router with no configuration. The old experimental.viewTransition flag is gone. Import ViewTransition from react, and every Link or router.push navigation animates because it is a Transition.

Why is my ViewTransition not animating?

Most often the update is not a Transition. A plain setState never animates; wrap it in startTransition. Other causes: the wrapper sits in a layout instead of page.tsx, two elements share a name on one page, the browser lacks support, or the navigation came from the browser back button.

How do I make a shared element transition in Next.js?

Wrap the element on both pages in a ViewTransition with the same unique name, such as card-2, and add share="morph" with default="none". React pairs them across the navigation and the browser animates size and position. The destination element must render in the same commit, so keep it in the prefetched shell.

What does addTransitionType do?

addTransitionType tags the current Transition with a reason, such as next or previous. Call it inside startTransition next to the state update, then map types to CSS classes in the enter, exit or update props. React also passes each type to the browser, so :active-view-transition-type() works in CSS.

Do view transitions work with the browser back button?

Not reliably. In my test with Next.js 16.4.2 and Chrome 155, the browser back and forward buttons started no view transition at all, even for named shared elements. Animated returns worked through in-app back links using transitionTypes={["nav-back"]}.

Which browsers support React View Transitions?

Next.js says the integration needs Chromium 125 or newer and recent Safari and Firefox versions, and some animations may behave differently in Safari. In browsers without support the app works normally and updates happen instantly, without animation.

Should I use View Transitions or Framer Motion?

Use View Transitions for route changes, cross-page shared elements and Suspense reveals; they add no animation library because the browser animates snapshots. Keep Motion (formerly Framer Motion) for gestures, springs, drag, scroll-linked effects and animations that must stay interactive while they run.

Originally published on fabwaseem.com.

Next.js Server Actions vs Route Handlers (API Routes): When to Use Each

Waseem Anjum — Sat, 24 Oct 2026 19:08:57 +0000

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

Server Actions vs Route Handlers comes down to one question: who is calling your server code? Use a Server Action when your own Next.js UI mutates data (forms, buttons, optimistic updates). Use a Route Handler when anything else needs a real HTTP endpoint: webhooks, mobile apps, public APIs, OAuth callbacks, file downloads, or cached GET JSON. For reads, use neither; fetch directly in a Server Component.

This guide is written against Next.js 16.4 and React 19.3, the current stable releases. Every code sample below was built with a fresh create-next-app project (which now enables Cache Components by default), type-checked, linted, and run with next start, and the Route Handler responses shown are the real ones I got back. Where I state a framework behavior, it links to the official Next.js or React docs.

If you are building an API for AI agents, the same rules apply: the MCP endpoint in my MCP server in Next.js guide is a Route Handler, because an external client calls it.

What is the difference between Server Actions and Route Handlers?

A Server Action is an async function marked with 'use server' that your React components call like a normal function; Next.js turns the call into a POST request and can return fresh UI in the same response. A Route Handler is a route.ts file that exports GET, POST and other HTTP methods and returns a standard Web Response to any client.

In other words, a Server Action is an internal RPC call for your own frontend, and a Route Handler is a public URL with a contract. Both run only on the server, both can read cookies and talk to your database, and both are reachable by anyone who sends the right request, so both need authentication.

Quick definitions

Term	What it means
Server Function	Any async function marked with `'use server'` that the client can call over the network (React docs).
Server Action	A Server Function used for a mutation, through `<form action>`, `formAction` or `startTransition` (Next.js docs).
Route Handler	A `route.ts` file in `app/` that handles HTTP requests with the Web `Request` and `Response` APIs (Next.js docs).
API Route	The Pages Router equivalent of a Route Handler, in `pages/api`.
RSC Payload	The serialized Server Component tree the client uses to update the page.

TL;DR: when to use Server Actions vs Route Handlers

You need to...	Use	Why
Submit a form or mutate data from your own UI	Server Action	Progressive enhancement, typed arguments, fresh UI in one roundtrip
Show pending, error and success states for a mutation	Server Action + `useActionState`	The hook gives you `state`, `formAction` and `pending`
Read data for a page	Server Component	Fetch straight from the data source; no extra HTTP hop
Receive a webhook (Stripe, GitHub, a CMS)	Route Handler	Fixed URL, raw body for signature checks, custom status codes
Serve a mobile app, CLI or third-party client	Route Handler	A stable, documented HTTP contract that does not change per build
Return non-HTML content (RSS, CSV, images, files)	Route Handler	Return any `Response` with any content type
Handle an OAuth or payment callback URL	Route Handler	Third parties redirect to a known URL with query params
Poll or fetch client-side (SWR, TanStack Query)	Route Handler	Server Actions run one at a time and are not meant for reads
Expose a cacheable `GET` JSON endpoint	Route Handler	`GET` handlers can opt into caching; actions are always `POST`

What are Server Actions in Next.js?

Server Actions are async server functions that Next.js exposes to your components through the 'use server' directive. At build time the compiler replaces the function in client bundles with an encrypted action ID, so calling it sends a POST to the current page. Next.js can then return both the action's result and a re-rendered page in a single response.

Three details from the official docs matter for the decision:

Only POST can invoke them. The Mutating Data docs state that actions use POST behind the scenes and only that method can call them.
One response carries data and UI. If the action calls revalidatePath, updateTag, refresh, sets a cookie or redirects, Next.js re-renders the current route and streams it back in the same response, so you do not need a follow-up fetch (Server Actions guide).
They are dispatched one at a time per client. If a user triggers three actions quickly, the second waits for the first. The docs say not to rely on Promise.all to parallelize them.

Forms that call Server Actions from Server Components also work before JavaScript loads, which is progressive enhancement you do not get from a fetch call to an API.

What are Route Handlers in Next.js?

Route Handlers are route.ts files inside the app directory that export functions named after HTTP methods. They support GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS, return a 405 for anything else, and work with the standard Web Request and Response APIs, plus Next.js helpers NextRequest and NextResponse.

A few rules from the Route Handlers docs shape how you use them:

A route.ts cannot sit in the same segment as a page.tsx (app/route.ts next to app/page.tsx is a conflict; app/api/route.ts is fine).
Route Handlers are not cached by default. You can opt GET into caching; other methods are never cached.
With Cache Components enabled, GET handlers follow the same model as pages: they are prerendered when they touch no runtime data, and you can cache a helper with 'use cache'.
They do not take part in layouts or client-side navigation. They are the lowest-level routing primitive.

The Next.js Backend for Frontend guide sums up their role: Route Handlers are public HTTP endpoints, and any client can access them.

Server Actions vs Route Handlers: side-by-side comparison

	Server Action	Route Handler
Defined in	`'use server'` file or inline function	`app/**/route.ts`
HTTP methods	`POST` only	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
URL	No stable public URL; called by encrypted action ID	Fixed URL you choose
Typical caller	Your own React components	Any HTTP client
Input	Serialized function arguments or `FormData`	`Request` (JSON, form data, raw text, streams)
Output	Serializable return value plus fresh RSC Payload	Any `Response` and content type
Caching	Never cached	`GET` can opt in; others never cached
Concurrency from one client	Dispatched one at a time	Fully parallel
Form integration	Built in; `<form action>` works before JavaScript loads	None; you wire up `fetch` or a form post yourself
Built-in CSRF check	Yes, `Origin` vs `Host` comparison	No; add your own for cookie-auth mutations
Default body size limit	1 MB (configurable)	No Server Action limit applies
Immediate cache update	`updateTag` (Server Actions only)	`revalidateTag(tag, 'max')`, `revalidatePath`
Survives a new deploy	IDs can change between builds	URL stays the same

The last row is easy to miss. Next.js docs note that new deployments typically generate new action IDs, rotated at most every 14 days even with unchanged code, so a tab still running an old build can hit a "Failed to find Server Action" error. That is fine for your own UI, which reloads, but it rules Server Actions out as an API for clients you do not ship with each build.

When should you use Server Actions?

Use a Server Action when your own Next.js UI changes data and the user should see the result right away: creating, editing or deleting records, toggling settings, submitting forms, liking a post, or updating a cart. You get typed calls, progressive enhancement, built-in pending state and one-roundtrip revalidation without writing an API contract.

Here is a complete, working example. The action authenticates, validates with Zod, mutates, and revalidates:

// app/todos/actions.ts
'use server'

import { revalidatePath } from 'next/cache'
import { getUserId } from '@/lib/auth'
import { createTodo, TodoInput } from '@/lib/todos'

export type FormState = { ok: boolean; message: string }

export async function addTodo(_prev: FormState, formData: FormData): Promise<FormState> {
  // 1. Authenticate inside the action. It is a public POST endpoint.
  const userId = await getUserId()
  if (!userId) return { ok: false, message: 'Please sign in first.' }

  // 2. Validate untrusted input.
  const parsed = TodoInput.safeParse({ title: formData.get('title') })
  if (!parsed.success) {
    return { ok: false, message: parsed.error.issues[0]?.message ?? 'Invalid input' }
  }

  // 3. Mutate, then revalidate so the same response carries fresh UI.
  await createTodo(userId, parsed.data)
  revalidatePath('/todos')
  return { ok: true, message: 'Todo added.' }
}

The client form uses React's useActionState, which returns the last result, a wrapped action and a pending flag:

// app/todos/todo-form.tsx
'use client'

import { useActionState } from 'react'
import { addTodo, type FormState } from './actions'

const initialState: FormState = { ok: false, message: '' }

export function TodoForm() {
  const [state, formAction, pending] = useActionState(addTodo, initialState)

  return (
    <form action={formAction}>
      <input name="title" placeholder="New todo" required maxLength={120} />
      <button type="submit" disabled={pending}>
        {pending ? 'Adding...' : 'Add todo'}
      </button>
      {state.message && <p role="status">{state.message}</p>}
    </form>
  )
}

And the page reads data in a Server Component. Because new projects ship with Cache Components on, the cookie-dependent list sits inside <Suspense>; without it, next build fails with a "blocking prerender" error, which I hit on the first build:

// app/todos/page.tsx
import { Suspense } from 'react'
import { getUserId } from '@/lib/auth'
import { listTodos } from '@/lib/todos'
import { TodoForm } from './todo-form'

export default function TodosPage() {
  return (
    <main>
      <h1>Todos</h1>
      <TodoForm />
      <Suspense fallback={<p>Loading todos...</p>}>
        <TodoList />
      </Suspense>
    </main>
  )
}

// Reads come straight from the data layer in a Server Component.
async function TodoList() {
  const userId = await getUserId()
  const todos = userId ? await listTodos(userId) : []

  return (
    <ul>
      {todos.map((todo) => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}

Should you use revalidatePath, updateTag or revalidateTag in a Server Action?

Use updateTag when the user must see their own write immediately; it expires the tag and the action's re-render waits for fresh data, and it only works inside Server Actions. Use revalidatePath when one route is affected. Use revalidateTag(tag, 'max') for background, stale-while-revalidate refreshes that should not slow the response.

The updateTag docs are explicit: calling it from a Route Handler throws, and you should use revalidateTag there instead.

When should you use Route Handlers?

Use a Route Handler whenever the caller is not your own React tree, or the response is not a UI update: webhooks, mobile and partner APIs, OAuth and payment callbacks, RSS feeds, file and CSV downloads, streaming responses, health checks, and cacheable public GET JSON. If someone outside your codebase needs a URL, it should be a Route Handler.

A JSON API for a mobile app, with bearer auth and proper status codes:

// app/api/todos/route.ts
import { NextResponse, type NextRequest } from 'next/server'
import { ZodError } from 'zod'
import { getUserIdFromBearer } from '@/lib/auth'
import { createTodo, listTodos } from '@/lib/todos'

export async function GET(request: NextRequest) {
  const userId = await getUserIdFromBearer(request.headers.get('authorization'))
  if (!userId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })

  return NextResponse.json({ todos: await listTodos(userId) })
}

export async function POST(request: NextRequest) {
  const userId = await getUserIdFromBearer(request.headers.get('authorization'))
  if (!userId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })

  try {
    const todo = await createTodo(userId, await request.json())
    return NextResponse.json({ todo }, { status: 201 })
  } catch (error) {
    if (error instanceof ZodError) {
      return NextResponse.json({ error: error.issues }, { status: 400 })
    }
    if (error instanceof SyntaxError) {
      return NextResponse.json({ error: 'Body must be valid JSON' }, { status: 400 })
    }
    throw error
  }
}

Against next start, this returned 401 with no token, 201 with the created todo, 400 with Zod's issue list for an empty title, 400 for malformed JSON, and 405 for an unsupported PUT, all without extra code for the 405.

A webhook needs the raw body to verify its signature, which is exactly what a Route Handler gives you and a Server Action does not:

// app/api/webhooks/payments/route.ts
import { createHmac, timingSafeEqual } from 'node:crypto'
import { revalidateTag } from 'next/cache'

export async function POST(request: Request) {
  const secret = process.env.WEBHOOK_SECRET
  if (!secret) return new Response('Webhook not configured', { status: 500 })

  // Read the raw body first: signatures are computed over the exact bytes sent.
  const body = await request.text()
  const signature = request.headers.get('x-signature') ?? ''
  const expected = createHmac('sha256', secret).update(body).digest('hex')

  const received = Buffer.from(signature, 'hex')
  const wanted = Buffer.from(expected, 'hex')
  if (received.length !== wanted.length || !timingSafeEqual(received, wanted)) {
    return new Response('Invalid signature', { status: 401 })
  }

  const event = JSON.parse(body) as { type: string }
  if (event.type === 'order.paid') {
    revalidateTag('orders', 'max') // stale-while-revalidate refresh
  }

  return Response.json({ received: true })
}

With a correctly signed body it returned 200 {"received":true}; with a forged signature, 401. Payment providers such as Stripe use their own signature headers and SDK helpers, but the shape is the same: read text, verify, then parse.

Can you use Server Actions and Route Handlers together?

Yes, and most production apps should. Put your business logic in a server-only data layer, then make Server Actions and Route Handlers thin adapters over it: the action handles your web UI, the Route Handler serves mobile apps and webhooks. Validation, authorization rules and database access live in one place, so the two entry points cannot drift apart.

// lib/todos.ts
import 'server-only'
import { z } from 'zod'

export const TodoInput = z.object({
  title: z.string().trim().min(1, 'Title is required').max(120),
})

export type Todo = { id: string; title: string; ownerId: string; done: boolean }

// In-memory store so the example runs as-is. Swap in Prisma or Drizzle.
const todos: Todo[] = []

export async function listTodos(ownerId: string): Promise<Todo[]> {
  return todos.filter((t) => t.ownerId === ownerId)
}

export async function createTodo(ownerId: string, input: unknown): Promise<Todo> {
  const { title } = TodoInput.parse(input) // throws ZodError on bad input
  const todo: Todo = { id: crypto.randomUUID(), title, ownerId, done: false }
  todos.push(todo)
  return todo
}

The server-only import makes the build fail if a Client Component ever imports this file, which keeps database code and secrets out of the browser bundle. This is the same Data Access Layer idea the Next.js Data Security guide recommends. In a real app, swap the array for Prisma or Drizzle, as in my open-source Foliora (Prisma and PostgreSQL) and Forgekit (Drizzle and pgvector) projects.

Should you use Server Actions to fetch data?

No. The React docs say Server Functions "are designed for mutations that update server-side state; they are not recommended for data fetching," and that frameworks typically process one action at a time and cannot cache the return value. Fetch in a Server Component instead, or use a GET Route Handler when the client must fetch.

The Next.js docs make the same point from the other side: Server Actions are queued, so using them for reads makes requests sequential. That is the opposite of what you want for a dashboard that loads several widgets. For client-side polling or data that depends on browser APIs, the Backend for Frontend guide suggests a Route Handler with SWR or TanStack Query.

Should a Server Component fetch from your own Route Handler?

No. Call the data layer directly. The Next.js docs warn that fetching your own Route Handler from a Server Component adds an extra HTTP round trip, and for pages prerendered at build time it fails the build, because no server is listening yet. Route Handlers are for clients outside the React server render.

Are Server Actions secure?

Server Actions are as secure as the checks you write inside them. Next.js adds a CSRF check (comparing Origin with Host), a 1 MB default body limit, encrypted action IDs, removal of unused actions from client bundles, and encryption of closed-over variables. It does not authenticate users or validate input for you, and every action is reachable by a direct POST.

The official guidance boils down to three rules inside every action, which apply equally to Route Handlers:

Authenticate and authorize. Hiding a form on a page is not a security boundary; requests can skip your UI.
Validate inputs. Treat FormData, arguments, query params and headers as untrusted. Schema validation checks shape, not ownership, so look records up by both ID and owner.
Constrain return values. Whatever an action returns is serialized to the client, so return only what the UI renders, never raw database rows.

Two configuration details matter when you self-host:

Behind a proxy or CDN, add the external domains to serverActions.allowedOrigins in next.config, or the CSRF check can reject legitimate requests (serverActions config).
With more than one instance, set NEXT_SERVER_ACTIONS_ENCRYPTION_KEY to the same value everywhere so action references decrypt on every replica. I cover replicas in the production Next.js Dockerfile guide and the Coolify self-hosting guide.

Route Handlers get none of the automatic protections, so for cookie-authenticated mutations you add CSRF protection, rate limiting and payload verification yourself. The Backend for Frontend guide's security section covers headers, rate limiting, payload verification and access to protected resources.

Server Actions vs API routes: what changed from the Pages Router?

API Routes live in pages/api and use Node-style req and res objects. In the App Router, Route Handlers replace them and use the Web Request and Response APIs instead. The Next.js docs say you do not need to use both. Server Actions are new with the App Router; they became stable in Next.js 14.

So when people search "Server Actions vs API routes," they usually mean the same decision as this post. If you are migrating, map each API route to a Route Handler first, then move mutations that only your UI calls into Server Actions, and leave anything an external client depends on as a Route Handler.

Do Server Actions replace tRPC or TanStack Query?

Partly. For mutations called only by your own Next.js UI, Server Actions give you typed calls without a separate API layer. They do not give you client-side caching, parallel reads, or a contract other clients can consume. Keep TanStack Query or SWR for client-side fetching against Route Handlers, and keep an API layer like tRPC or oRPC when you need versioned, reusable endpoints.

Common Server Action and Route Handler mistakes

Mistake	What happens	Fix
No auth check inside the action	Anyone who can send the `POST` can run it	Authenticate and authorize inside every action
`Promise.all` over several actions	They still run one after another	Do parallel work inside one action or a Route Handler
Using an action to load page data	Sequential, uncached reads	Fetch in a Server Component
Server Component fetches `/api/...`	Extra round trip; build fails when prerendered	Call the data layer directly
Uploading a large file through an action	Rejected above the 1 MB default	Raise `bodySizeLimit` or upload straight to storage
`updateTag` in a Route Handler	Throws at runtime	Use `revalidateTag(tag, 'max')` or `revalidatePath`
Mobile app calls a Server Action	Breaks when action IDs change on deploy	Expose a Route Handler with a stable URL
Several replicas, no shared key	Action references fail on other instances	Set one `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY`

Related: Next.js 16.4.1 fixed a high-severity DoS that affects any App Router app with a Server Action, so check your version with the Next.js security update October 2026 guide. To refresh cached data after a Server Action, see updateTag in Next.js use cache explained.

Related: auth libraries hit this split directly. Better Auth signs users in from a server action only with its nextCookies() plugin, and serves everything else from a route handler. See Better Auth with Next.js 16.

Key takeaways

Use Server Actions for mutations from your own UI, Route Handlers for any caller with a URL, and Server Components for reads.
Server Actions are POST-only, dispatched one at a time per client, and can return fresh UI in the same response.
Route Handlers are public, uncached by default, support every common HTTP method and can return any content type.
Both are public entry points: authenticate, validate and shape return values in every one.
Share one server-only data layer so actions and Route Handlers stay thin and consistent.

FAQ

Should I use Server Actions or Route Handlers in Next.js?

Use Server Actions for data mutations triggered by your own Next.js UI, such as form submissions, toggles and deletes. Use Route Handlers when an external client needs a stable URL: webhooks, mobile apps, third-party integrations, OAuth callbacks, file downloads or cacheable GET endpoints. For reading page data, fetch directly in a Server Component.

Can I use Server Actions to fetch data?

You can, but you should not. The React docs say Server Functions are designed for mutations and are not recommended for data fetching, and Next.js dispatches actions one at a time per client, so reads become sequential and uncached. Fetch in Server Components, or use a GET Route Handler with SWR or TanStack Query on the client.

Are Next.js Server Actions secure?

They are as secure as the code inside them. Next.js adds a CSRF check comparing Origin and Host, a 1 MB default body limit, encrypted action IDs and removal of unused actions, but every action is still reachable by a direct POST. Authenticate, authorize and validate input inside each action, and return only the fields the UI needs.

Are Route Handlers the same as API routes?

Route Handlers are the App Router equivalent of Pages Router API routes. They live in route.ts files inside the app directory and use the Web Request and Response APIs instead of Node-style req and res objects. The Next.js docs note you do not need to use API routes and Route Handlers together.

Can a mobile app call a Next.js Server Action?

It should not. Server Actions have no stable public URL; they are called by an encrypted action ID that can change between deployments, which causes a Failed to find Server Action error for out-of-date clients. Expose a Route Handler with a fixed URL, bearer authentication and documented JSON for mobile and third-party clients.

What is the Server Actions body size limit?

By default, Next.js caps the request body sent to a Server Action at 1 MB to prevent excessive parsing and potential DDoS attacks. You can raise it with serverActions.bodySizeLimit in next.config, for example '2mb', but for large files it is usually better to upload directly to object storage.

Originally published on fabwaseem.com.

SSRF Protection in Node.js: Validating User URLs, Redirects and DNS (Tested)

Waseem Anjum — Sat, 24 Oct 2026 19:08:45 +0000

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

If your server fetches a URL that a user typed in, you have an SSRF problem until you prove otherwise. Link previews, webhook senders, "import from URL" buttons, image proxies and video downloaders all do it. Point one of them at http://169.254.169.254/latest/meta-data/ on a cloud VM, or at an admin panel on 127.0.0.1, and your server becomes the attacker's browser inside your network.

This post is about the approach I use in Snagbox, my video download API, where users paste links from social media all day. I ran three different checks against the same list of bypass payloads on Node.js 20.19 to show where each one breaks. The short version: a regex on the hostname is not SSRF protection. You need to check the parsed host, every redirect hop, and the IP address the DNS lookup actually returns.

What SSRF is and who is exposed

Server-Side Request Forgery happens when an attacker controls where your server sends a request. The request comes from inside your network, so it can reach things the attacker cannot reach directly:

Cloud metadata endpoints such as 169.254.169.254 (AWS, GCP, Azure) and metadata.google.internal, which can hand out temporary credentials
Services bound to 127.0.0.1: Redis, admin dashboards, debug ports
Private ranges such as 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16, plus IPv6 unique-local addresses (fc00::/7)

Any feature that takes a URL from a user and fetches it on the server is exposed. That includes webhooks, where the "user" is whoever configures the integration.

The test: three checks, one payload list

I compared three approaches:

(a) Regex on the raw string. Something like /^(https?:\/\/)?(localhost|127\.|10\.|192\.168\.|169\.254\.)/. This is the check I see most often in code review.
(b) new URL() plus a string blocklist. Parse the URL first, then compare url.hostname to a list such as localhost, 127.0.0.1, 0.0.0.0, 169.254.169.254, [::1] and a few prefixes.
(c) The Snagbox safe-fetch.ts approach. Parse the URL, allow only http: and https:, reject credentials, reject internal names, and check IP literals with Node's net.BlockList. DNS answers and redirects are checked separately (covered below).

Results, run on the box with tsx on Node.js 20.19.2. "allowed" means the check let the URL through:

Payload	new URL().hostname	(a) regex	(b) URL+list	(c) safe-fetch static
`http://127.0.0.1/`	`127.0.0.1`	blocked	blocked	blocked
`http://2130706433/`	`127.0.0.1`	allowed	blocked	blocked
`http://0x7f000001/`	`127.0.0.1`	allowed	blocked	blocked
`http://0177.0.0.1/`	`127.0.0.1`	allowed	blocked	blocked
`http://127.1/`	`127.0.0.1`	blocked	blocked	blocked
`http://[::1]/`	`[::1]`	allowed	blocked	blocked
`http://[::ffff:127.0.0.1]/`	`[::ffff:7f00:1]`	allowed	allowed	blocked
`http://[::ffff:7f00:1]/`	`[::ffff:7f00:1]`	allowed	allowed	blocked
`http://169.254.169.254/latest/meta-data/`	`169.254.169.254`	blocked	blocked	blocked
`http://[fd00::1]/`	`[fd00::1]`	allowed	allowed	blocked
`http://0.0.0.0/`	`0.0.0.0`	allowed	blocked	blocked
`http://LOCALHOST./`	`localhost.`	blocked	allowed	blocked
`http://metadata.google.internal/`	`metadata.google.internal`	allowed	allowed	blocked
`http://user:pw@example.com/`	`example.com`	allowed	allowed	blocked
`file:///etc/passwd`	``	allowed	allowed	blocked
`http://localtest.me/`	`localtest.me`	allowed	allowed	allowed

Three things stand out.

1. The WHATWG URL parser already normalizes most IPv4 tricks. new URL("http://2130706433/").hostname is 127.0.0.1. So are 0x7f000001, 0177.0.0.1 and 127.1. That is why approach (b) catches them and the raw-string regex in (a) does not. If you only take one thing from this post: always parse first, then check url.hostname, never the raw input.

2. IPv6 is where string lists fall apart. The parser turns [::ffff:127.0.0.1] into [::ffff:7f00:1], an IPv4-mapped IPv6 address that still points at loopback. No sane string list contains that form. fd00::1 (unique-local) also slips through. net.BlockList handles both: in my tests it blocked ::ffff:a9fe:a9fe (the hex-mapped form of 169.254.169.254) against the IPv4 169.254.0.0/16 rule.

3. A hostname check alone cannot see DNS. localtest.me is a public name that resolves to 127.0.0.1 on the public internet. Every static check, including (c), lets it through, because nothing about the string says "loopback". That is expected. The DNS answer has to be checked at connect time, which is the next section.

Checking IP addresses with net.BlockList

Node.js has had net.BlockList since v15. It does subnet matching for IPv4 and IPv6, so you don't have to write CIDR math yourself:

`ts
import { BlockList, isIP } from "net";

const blocked = new BlockList();
blocked.addSubnet("0.0.0.0", 8, "ipv4");
blocked.addSubnet("10.0.0.0", 8, "ipv4");
blocked.addSubnet("127.0.0.0", 8, "ipv4");
blocked.addSubnet("169.254.0.0", 16, "ipv4");
blocked.addSubnet("172.16.0.0", 12, "ipv4");
blocked.addSubnet("192.168.0.0", 16, "ipv4");
blocked.addRange("224.0.0.0", "255.255.255.255", "ipv4");
blocked.addAddress("::", "ipv6");
blocked.addAddress("::1", "ipv6");
blocked.addSubnet("fc00::", 7, "ipv6");
blocked.addSubnet("fe80::", 10, "ipv6");
blocked.addSubnet("ff00::", 8, "ipv6");

export function isBlockedIp(address: string): boolean {
let ip = address.trim().toLowerCase().replace(/^[|]$/g, "");
const mapped = /^::ffff:(\d{1,3}(?:.\d{1,3}){3})$/.exec(ip);
if (mapped) ip = mapped[1];
const family = isIP(ip);
if (family === 0) return true; // not an IP at all: fail closed
return blocked.check(ip, family === 6 ? "ipv6" : "ipv4");
}
`

Note the last two lines: anything that isn't a valid IP is treated as blocked. Fail closed.

The URL-level check wraps this:

`ts export function assertPublicHttpUrl(raw: string): URL { let url: URL; try { url = new URL(raw); } catch { throw new SsrfError("The URL is not a valid http(s) address."); } if (url.protocol !== "http:" && url.protocol !== "https:") { throw new SsrfError("Only http and https URLs can be fetched."); } if (url.username || url.password) { throw new SsrfError("URLs with embedded credentials are not allowed."); } if (isBlockedHostname(url.hostname)) { throw new SsrfError("Refusing to connect to a non-public address."); } return url; } `

isBlockedHostname strips a trailing dot (so LOCALHOST. doesn't sneak past, which it did in approach (b)), rejects localhost, *.localhost, *.local and *.internal, and runs IP literals through isBlockedIp.

Check every redirect hop

This is the bug that bites people who did everything else right. You validate the URL, then call fetch(), and fetch() follows redirects on its own.

I tested it with two local servers: a "front" one that answers 302 Location: http://127.0.0.1:<port>/, and an "internal" one that returns internal-secret. Plain fetch(frontUrl) came back with the body internal-secret. The redirect was followed with no check at all.

With fetch(frontUrl, { redirect: "manual" }) you get the 302 and its Location header back instead, and you decide what to do. In Snagbox this is a loop that re-validates each hop:

`ts
for (let hop = 0; ; hop++) {
const response = await transport(current, { ...options, headers: hopHeaders });
const isRedirect =
response.status >= 300 && response.status < 400 && response.headers.location;
if (!isRedirect) return wrap(response, current);

response.body.resume(); // drain the redirect body
if (hop >= maxRedirects) throw new SsrfError("Too many redirects.");
const next = assertPublicHttpUrl(
new URL(String(response.headers.location), current).toString(),
);
hopHeaders = headersForHop(current, next, hopHeaders); // drop auth/cookies cross-host
current = next;
}
`

In the test, a fake public host short.example answering 302 to http://169.254.169.254/latest/meta-data/ was refused with SsrfError: Refusing to connect to a non-public address. The metadata request was never made.

This matters a lot for a downloader, because users paste short links (t.co, fb.watch, vm.tiktok.com) all the time. A public short link that bounces to an internal address is the textbook bypass.

Two extra details in that loop are worth copying:

Resolve relative Location headers against the current URL with new URL(location, current).
Drop Authorization, Cookie and Proxy-Authorization when a redirect changes host, so you don't leak credentials to whoever the redirect points at.

DNS rebinding: check the address you actually connect to

The static check passed localtest.me. To close that, you check the DNS answer, and you do it at connect time, inside the same request that opens the socket.

Why at connect time? If you resolve the name, check it, then call fetch(url), the HTTP client resolves the name again. An attacker who controls the DNS server can answer with a public IP the first time and 127.0.0.1 the second time, with a TTL of zero. That's DNS rebinding.

Node's http.request and https.request take a lookup option. Whatever that function returns is the address the socket connects to, so checking inside it closes the gap:

`ts
import { lookup as dnsLookup, type LookupAddress } from "dns";

https.request(url, { lookup: safeLookup, timeout: 30_000 }, onResponse);
`

Two choices here are deliberate:

all: true and reject if any address is private. A name that returns one public and one private address is refused. In my test, ["93.184.216.34", "127.0.0.1"] was blocked, and ["::ffff:169.254.169.254"] was blocked too.
The check runs on the exact address used for the connection, so there is no second lookup to race.

If you use undici or the global fetch() instead, the same idea applies through a custom Agent with a connect option that does its own lookup. Checking once before fetch() is not enough.

Gaps I found in my own blocklist

Running the payloads also showed what my list misses. These all came back "allowed" from isBlockedIp:

100.64.0.1: carrier-grade NAT (100.64.0.0/10), used inside some cloud and Kubernetes networks
198.18.0.1: the benchmarking range (198.18.0.0/15), which some sandboxes and proxies use for internal addresses. My test box's resolver returned this range for localtest.me.
192.0.0.1: IETF protocol assignments (192.0.0.0/24)
64:ff9b::7f00:1: the NAT64 prefix (64:ff9b::/96) wrapping 127.0.0.1
fec0::1: deprecated IPv6 site-local (fec0::/10)

None of these are the common attack targets, but on some networks they lead somewhere internal. The fix is a few more lines:

`ts blocked.addSubnet("100.64.0.0", 10, "ipv4"); blocked.addSubnet("192.0.0.0", 24, "ipv4"); blocked.addSubnet("198.18.0.0", 15, "ipv4"); blocked.addSubnet("64:ff9b::", 96, "ipv6"); blocked.addSubnet("fec0::", 10, "ipv6"); `

The general lesson: start from "only globally routable unicast is allowed", not from a short list of famous bad ranges.

What it costs

Not much. On my box, isBlockedIp took about 1.8 µs per call, averaged over 100,000 calls (mixed public and mapped-private input). The DNS lookup itself costs whatever your resolver costs, and you were doing that lookup anyway. Moving it into the lookup hook doesn't add a second one.

Tests to keep in CI

Turn the payload list into a test file so a refactor can't quietly undo this. With the built-in runner:

`ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { assertPublicHttpUrl, isBlockedIp } from "./safe-fetch";

const mustBlock = [
"http://127.0.0.1/", "http://2130706433/", "http://0x7f000001/",
"http://0177.0.0.1/", "http://[::1]/", "http://[::ffff:127.0.0.1]/",
"http://169.254.169.254/", "http://[fd00::1]/", "http://LOCALHOST./",
"http://metadata.google.internal/", "http://user:pw@example.com/",
"file:///etc/passwd",
];

for (const url of mustBlock) {
test(blocks ${url}, () => assert.throws(() => assertPublicHttpUrl(url)));
}

test("blocks mapped metadata IP", () => assert.ok(isBlockedIp("::ffff:169.254.169.254")));
test("allows a public IP", () => assert.ok(!isBlockedIp("93.184.216.34")));
`

Add one test for the redirect loop with a fake transport (a host that answers 302 to 169.254.169.254), and one for the lookup hook with a fake DNS answer. Those two are the ones that catch real regressions.

Common mistakes

Running a regex on the raw input instead of on new URL(input).hostname
Calling fetch() with the default redirect: "follow" after validating only the first URL
Resolving DNS, checking it, then letting the HTTP client resolve again
Forgetting IPv6, especially IPv4-mapped forms like ::ffff:7f00:1
Allowing file:, gopher: or other schemes because "we only expect https"
Treating "not an IP" as safe instead of failing closed
Forwarding Authorization or cookies to a redirect target on another host

Key takeaways

Parse with new URL() first. It normalizes decimal, hex and octal IPv4 for you.
Use net.BlockList for IP checks. It handles CIDR and IPv4-mapped IPv6.
Follow redirects yourself and re-validate every hop.
Check the DNS answer inside the lookup hook, so the checked address is the connected address.
Keep a payload test in CI, and allow only globally routable addresses rather than blocking a few famous ranges.

If you're building this into a NestJS API, the same safe-fetch module drops into a service. My secure NestJS + Prisma API starter covers the rest of the hardening, the MCP security post covers the auth side of tool servers, and the NestJS Server-Sent Events guide shows how Snagbox streams job progress after the URL passes these checks.

FAQ

Is checking the hostname enough to prevent SSRF in Node.js?

No. A public hostname can resolve to a private IP, and a public URL can redirect to one. You need to check the parsed hostname, every redirect hop, and the IP address returned by DNS at connect time.

Does new URL() block decimal or hex IP addresses?

It doesn't block them, but it normalizes them. new URL('http://2130706433/').hostname is '127.0.0.1', so a check on url.hostname catches it. A regex on the raw string does not.

How do I stop fetch() from following redirects to internal IPs?

Pass redirect: 'manual', read the Location header, resolve it against the current URL, validate the new URL, and only then request it. Repeat for each hop up to a small limit.

What is DNS rebinding and how do I prevent it?

An attacker's DNS server returns a public IP when you check and a private IP when you connect. Prevent it by validating addresses inside the lookup option of http.request or https.request, so the checked address is the connected address.

Originally published on fabwaseem.com.

Next.js use cache Explained: Cache Components, cacheLife and cacheTag in Next.js 16.4

Waseem Anjum — Fri, 23 Oct 2026 22:05:10 +0000

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

Next.js use cache is a directive that marks an async function, component or whole file as cacheable, so its output is stored and reused for matching inputs. It is the core of Cache Components, the caching model that Next.js 16.4 now turns on by default in create-next-app. Add 'use cache', set a lifetime with cacheLife, label it with cacheTag, and invalidate it with updateTag or revalidateTag.

This guide is written against Next.js 16.4.2 and React 19.3, the current releases. I scaffolded a fresh app with create-next-app@16.4.2 (its generated next.config.ts already contains cacheComponents: true and partialPrefetching: true), wrote every example below, then type-checked, linted, built and ran it with next start. The build output, headers and timestamps shown are the real ones I got back. Framework behavior links to the official Next.js docs.

Security note: the October 14, 2026 Next.js security update fixed a critical remote code execution bug in use cache functions that return multiple typed arrays. If you use Cache Components, run Next.js 16.4.1 or later before you ship anything from this post.

What does "use cache" do in Next.js?

'use cache' tells Next.js that a function's return value depends only on its inputs, so it can be stored and reused. The first call runs the function and saves the output; later calls with the same arguments get the saved output until the entry revalidates. Cached output can also be baked into the page's prerendered static shell.

The official use cache reference lists what goes into a cache key:

Build ID: every deploy gets new keys, so caches do not survive a deploy.
Function ID: a secure hash of where the function lives and its signature.
Serializable arguments: function arguments or component props.
Closed-over variables: values captured from an outer scope become part of the key.

That makes it different from the old App Router model, where fetch calls and route segments were cached implicitly. With Cache Components, nothing is cached unless you say so, and anything you do cache is explicit at the call site.

Quick definitions

Term	What it means
Cache Components	The Next.js 16 programming model behind `cacheComponents: true`: explicit `use cache`, Partial Prerendering and Suspense streaming (docs)
`'use cache'`	Directive that caches a function, component or file's exports, shared across users
`cacheLife`	Sets how long an entry is fresh (`stale`, `revalidate`, `expire`) (docs)
`cacheTag`	Labels an entry so you can invalidate it on demand (docs)
`updateTag`	Expires a tag immediately from a Server Action; the next read waits for fresh data
`revalidateTag`	Marks a tag stale from a Server Function or Route Handler; serves stale while it refreshes
Static shell	The prerendered HTML of a route, including cached output and Suspense fallbacks

TL;DR: Next.js use cache in five lines

You want to...	Do this
Cache a database query or API call for everyone	`'use cache'` + `cacheLife('hours')` + `cacheTag('x')` in the data function
Show a user's change right after they submit a form	`updateTag('x')` inside the Server Action
Refresh after a CMS or Stripe webhook	`revalidateTag('x', 'max')` in a Route Handler
Read cookies or headers	Read them outside the cached scope and pass values as arguments
Cache something that must read cookies inside	`'use cache: private'` (per browser only)
Share a cache across many server instances	`'use cache: remote'` with a cache handler

Is Cache Components enabled by default in Next.js 16.4?

Yes, for new apps. Since Next.js 16.4, released on October 6, 2026, every app created with create-next-app has Cache Components enabled, and the Next.js team says it will become the default for all apps in Next.js 17. Existing apps keep the old model until you add cacheComponents: true.

This is what create-next-app@16.4.2 generated for me, unedited apart from the Tailwind loader lines:

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

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
}

export default nextConfig

next build confirms it at the top of the log:

✓ Running next.config.ts took 21ms
- Cache Components enabled
- Partial Prefetching enabled

How do you use "use cache" in Next.js? (step by step)

Here is the full working pattern from my test app: a product list that every visitor shares, a greeting that reads a cookie, and a form that adds a product.

Step 1: cache the data function

Put the directive at the top of the async function body, then set an explicit lifetime and a tag:

// lib/products.ts
import { cacheLife, cacheTag } from 'next/cache'
import { queryProducts } from './db'

// Shared, cached data function: one entry for every visitor.
export async function getProducts() {
  'use cache'
  cacheLife('hours')
  cacheTag('products')

  const products = await queryProducts()
  return { products, cachedAt: new Date().toISOString() }
}

cachedAt is there only to prove caching in the tests below. Because new Date() runs inside the cached scope, its value is stored with the entry, and the route still prerenders.

Step 2: render cached and request-time parts on one page

// app/page.tsx
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { getProducts } from '@/lib/products'
import { addProduct } from './actions'

export default function Home() {
  return (
    <main>
      <h1>Store</h1>
      {/* Request-time hole: reads a cookie, so it streams in */}
      <Suspense fallback={<p>Loading greeting...</p>}>
        <Greeting />
      </Suspense>
      {/* Cached: part of the static shell */}
      <ProductList />
      <form action={addProduct}>
        <input name="name" placeholder="Name" />
        <input name="price" type="number" placeholder="Price" />
        <button>Add</button>
      </form>
    </main>
  )
}

async function Greeting() {
  const name = (await cookies()).get('name')?.value ?? 'guest'
  return <p>Hi, {name}</p>
}

async function ProductList() {
  const { products, cachedAt } = await getProducts()
  return (
    <section>
      <ul>
        {products.map((p) => (
          <li key={p.id}>{p.name}: ${p.price}</li>
        ))}
      </ul>
      <p>cached at {cachedAt}</p>
    </section>
  )
}

Step 3: invalidate from a Server Action with updateTag

// app/actions.ts
'use server'

import { updateTag } from 'next/cache'
import { insertProduct } from '@/lib/db'

export async function addProduct(formData: FormData) {
  const name = String(formData.get('name') ?? '').trim()
  const price = Number(formData.get('price'))
  if (!name || !Number.isFinite(price)) return

  await insertProduct({ name, price })
  // Expire the tag now: the next read waits for fresh data
  // (read-your-own-writes for the user who submitted the form).
  updateTag('products')
}

In a real app, authenticate and authorize inside the action first. My Server Actions vs Route Handlers guide covers why every action is a public endpoint.

Step 4: invalidate from a webhook with revalidateTag

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache'

// Called by a CMS or admin webhook after products change.
export async function POST(request: Request) {
  if (request.headers.get('authorization') !== `Bearer ${process.env.REVALIDATE_SECRET}`) {
    return Response.json({ error: 'unauthorized' }, { status: 401 })
  }
  // Stale-while-revalidate: visitors keep getting the old list
  // while the next request refreshes it in the background.
  revalidateTag('products', 'max')
  return Response.json({ revalidated: true })
}

Step 5: build and read the route table

Route (app)          Revalidate  Expire
┌ ◐ /                        1h      1d
├ ○ /_not-found
├ ◐ /account
├ ○ /api/products            1h      1d
└ ƒ /api/revalidate

○  (Static)             prerendered as static content
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content
ƒ  (Dynamic)            server-rendered on demand

The home page is ◐ Partial Prerender: the product list is in the static shell, and the cookie greeting streams in. The 1h / 1d columns come straight from the hours profile. The webhook route is dynamic, as it should be.

Does it actually cache? What I measured with next start

These are the real responses from next start on the test app.

Two requests, one entry. A GET Route Handler that calls getProducts() returned the same timestamp twice. It was filled during next build and reused:

$ curl -s localhost:3141/api/products
{"count":2,"cachedAt":"2026-10-17T13:01:48.233Z"}
$ curl -s localhost:3141/api/products
{"count":2,"cachedAt":"2026-10-17T13:01:48.233Z"}

Shared cache, personal hole. Sending cookie: name=Waseem changed the greeting to Hi, Waseem while the product list kept the same cached at value. The response headers show how Next.js treats the page:

x-nextjs-stale-time: 300
x-nextjs-prerender: 1
x-nextjs-postponed: 1

x-nextjs-stale-time: 300 is the 5-minute client stale value from the hours profile, and x-nextjs-postponed: 1 means part of the page was deferred to request time.

revalidateTag is stale-while-revalidate. Without the bearer token the webhook returned 401. With it, the first request after revalidation still got the old entry, and the next one got a fresh one:

$ curl -s -X POST -H 'authorization: Bearer s3cret' localhost:3141/api/revalidate
{"revalidated":true}
$ curl -s localhost:3141/api/products
{"count":2,"cachedAt":"2026-10-17T13:01:48.233Z"}   # stale, refresh starts
$ curl -s localhost:3141/api/products
{"count":2,"cachedAt":"2026-10-17T13:02:01.283Z"}   # fresh

updateTag is read-your-own-writes. In a headless Chrome test, submitting the form with "Webcam, 59" re-rendered the list with three items and a new cached at time in the same navigation. A second browser that opened the page afterwards saw the same three items and the same new timestamp, so the shared entry was replaced, not forked per user.

What are the cacheLife profiles?

cacheLife sets three values: stale (how long the browser may reuse it without asking), revalidate (after which the server refreshes it in the background) and expire (after which a request must wait for fresh data). These are the built-in presets from the cacheLife reference:

Profile	Use case	`stale`	`revalidate`	`expire`
`default`	Standard content	5 minutes	15 minutes	never
`seconds`	Real-time data	30 seconds	1 second	1 minute
`minutes`	Frequently updated content	5 minutes	1 minute	1 hour
`hours`	Updated several times a day	5 minutes	1 hour	1 day
`days`	Updated daily	5 minutes	1 day	1 week
`weeks`	Updated weekly	5 minutes	1 week	30 days
`max`	Rarely changes	5 minutes	30 days	1 year

Three rules worth remembering:

Always set cacheLife explicitly. Without it the default profile applies, and nesting a short-lived cache inside a scope with no explicit cacheLife fails the build during prerendering.
The browser keeps cached output for at least 30 seconds. The client router enforces a minimum 30-second stale time regardless of your profile.
You can define custom profiles in next.config.ts under cacheLife, or pass an inline object such as cacheLife({ stale: 60, revalidate: 600, expire: 3600 }).

updateTag vs revalidateTag: which should you use?

Use updateTag inside a Server Action when the user who made a change must see it on the very next render. Use revalidateTag(tag, 'max') from a Route Handler or webhook when a short window of stale data is fine. updateTag blocks the next read until fresh data loads; revalidateTag serves stale content while it refreshes.

	`updateTag(tag)`	`revalidateTag(tag, 'max')`
Where it runs	Server Actions only	Server Functions and Route Handlers
Next read	Waits for fresh data	Gets stale data, triggers a refresh
Best for	Forms, settings, carts: read-your-own-writes	CMS publish, Stripe and GitHub webhooks, admin jobs
In a Route Handler	Throws	Works

The revalidateTag reference recommends the 'max' profile and marks the single-argument form as deprecated; it behaves like { expire: 0 }, a blocking cache miss. Tags are case-sensitive and capped at 256 characters, and a longer tag is silently never assigned. Revalidation is triggered by the next request, not by the call itself, so pages refresh as they are visited.

use cache vs use cache: private vs use cache: remote

Next.js has three caching directives. Plain 'use cache' covers most apps. The other two solve specific problems, and the use cache: remote reference compares them:

Feature	`'use cache'`	`'use cache: remote'`	`'use cache: private'`
Server-side storage	In memory or a cache handler	Remote cache handler	None
Shared between users	Yes	Yes	No, per browser
Can call `cookies()` / `headers()` inside	No, pass values as arguments	No, pass values as arguments	Yes
Extra cost	None	Storage and network	None
Survives a deploy	No	No	N/A

When should you use "use cache: private"?

Use it only when a function must read cookies or headers itself and you cannot refactor it to take those values as arguments, or when compliance rules forbid storing request data in a server cache. It runs at request time, is excluded from the static shell and is cached only in the browser. This is the version from my test app:

// app/account/page.tsx (excerpt)
import { cookies } from 'next/headers'
import { cacheLife } from 'next/cache'

// Reads cookies directly. Cached per browser only, never in a shared server cache.
async function getPreferences() {
  'use cache: private'
  cacheLife({ stale: 60 })
  const currency = (await cookies()).get('currency')?.value ?? 'USD'
  return { currency }
}

With a currency=PKR cookie the page rendered Currency: PKR, and the route still built as ◐ because the component sits inside <Suspense>.

When does "use cache: remote" make sense?

When request-time content gets low hit rates from per-instance memory: serverless functions, many replicas, or an expensive upstream such as a slow CMS. It stores entries in a shared handler like Redis. Skip it when operations already take under about 50 ms, when keys are mostly unique per request, or when data changes every few seconds; the docs list those as cases where remote caching does not pay off.

Does "use cache" work when self-hosting with Docker or Coolify?

Yes. The official platform table lists both the Node.js server and Docker as supported, and static export as not supported. When self-hosted, the default in-memory cache persists across requests in the same process, which is exactly what the next start tests above show. Size it with cacheMaxMemorySize.

Two things change once you run more than one container:

Each replica has its own memory cache. Two instances can serve different cachedAt values until both refresh. Configure a shared cacheHandlers entry (for example Redis) if that matters.
Every deploy starts cold. The cache key includes the build ID, so use cache entries do not carry over. For data that must survive deploys, the docs still point to unstable_cache or the fetch cache.

If you are deploying this way, my self-hosting Next.js with Coolify guide and production Next.js Dockerfile cover the container side.

How do you migrate an existing app to Cache Components?

Enable cacheComponents: true, then replace each route segment config the build complains about. The migration guide says routes that still export dynamic, revalidate or fetchCache will error once the flag is on. Most of the work is mechanical:

Before (old App Router)	After (Cache Components)
`export const revalidate = 3600`	`'use cache'` + `cacheLife('hours')` around the data or UI
`export const revalidate = 0` / `force-dynamic`	Remove it; uncached data already runs at request time
`export const fetchCache = 'force-cache'`	Wrap the data in `'use cache'`
`unstable_cache(fn, keys, { tags, revalidate })`	Optional: `'use cache'` + `cacheTag` + `cacheLife`; the old API keeps working
`fetch(url, { next: { tags } })`	`cacheTag` inside a `'use cache'` function
`revalidateTag('x')`	`updateTag('x')` in actions, `revalidateTag('x', 'max')` elsewhere

For a large app, adopt it incrementally:

Turn on the flag and migrate the segment configs above.
Opt out routes that are not ready with export const instant = false, or run the codemod across the app: npx @next/codemod@canary cache-components-instant-false ./app.
Fix synchronous IO such as new Date(), Math.random() and crypto.randomUUID() in the prerendered shell; instant = false does not clear those errors. Move the call into a cached scope, a Client Component, or behind connection() inside <Suspense>.
Remove instant = false one route at a time and resolve the dev overlay insights.

If you use a coding agent, Next.js ships a skill for this: npx skills add vercel/next.js --skill next-cache-components-adoption, then ask the agent to adopt Cache Components with it.

What can't you do inside "use cache"?

Cached functions run in an isolated environment, and four limits catch most people:

No request APIs. cookies(), headers() and searchParams are not allowed, even in a helper the cached function calls. On dynamic routes this can pass next build and fail under next start with the next-request-in-use-cache error.
Serializable inputs and outputs only. Arguments follow Server Component serialization, return values follow Client Component serialization. Class instances, symbols, URL objects and functions (except as pass-through) are rejected.
React.cache does not cross the boundary. Values stored with React.cache outside a cached scope are not visible inside it. Pass data as arguments.
Promises of runtime data hang the build. Passing a cookies() promise or uncached data into a cached function makes prerendering wait, and the build times out after 50 seconds.

For debugging, run NEXT_PRIVATE_DEBUG_CACHE=1 npm run start for verbose cache logs. In development, logs from cached functions are replayed with a Cache prefix.

Common "use cache" mistakes

Mistake	What happens	Fix
Calling `cookies()` inside `'use cache'`	`next-request-in-use-cache` error	Read it outside and pass the value in
Caching per-user data with plain `'use cache'`	Users can see each other's data if the key misses the user ID	Add the user ID as an argument, or use `'use cache: private'`
No `cacheLife`	`default` profile applies; nested short caches can fail the build	Set a profile in every cached scope
`updateTag` in a Route Handler	Throws at runtime	Use `revalidateTag(tag, 'max')`
`revalidateTag('x')` with one argument	Deprecated, blocking miss	Pass `'max'` or migrate to `updateTag`
Expecting caches to survive deploys	Cold cache after each deploy	Accept it, or use `unstable_cache` / `fetch` cache for that data
Several replicas, default handler	Replicas disagree for a while	Shared `cacheHandlers` or `'use cache: remote'`
Running Next.js below 16.4.1	Exposed to the October 2026 critical advisories	Upgrade now

Related: Next.js 16.4.1 patched a critical RCE in use cache functions that return typed arrays; see the Next.js security update October 2026. To let an AI agent do the migration for you, install the official next-cache-components-adoption skill as shown in Agent Skills: how to write a SKILL.md.

Related: I reused this demo app to benchmark the TypeScript 7 upgrade: the next build type-check step dropped from 1,368 ms to 231 ms.

Related: my React View Transitions guide uses Cache Components with connection() so a Suspense fallback streams in and animates its reveal.

Related: for a side-by-side with a non-Next.js framework, see TanStack Start vs Next.js, where I benchmarked the same app on both for server throughput, client JS, hydration and build time.

Key takeaways

'use cache' caches an async function, component or file by its inputs; with Cache Components nothing else is cached implicitly.
New Next.js 16.4 apps have Cache Components and Partial Prefetching on by default, and it becomes the default for all apps in Next.js 17.
Pair every cached scope with cacheLife and cacheTag, then invalidate with updateTag in Server Actions or revalidateTag(tag, 'max') elsewhere.
Request APIs stay outside cached scopes; pass their values in as arguments, or reach for 'use cache: private' when you truly cannot.
Self-hosted next start keeps entries in memory across requests, but not across deploys or between replicas.

FAQ

What does 'use cache' do in Next.js?

'use cache' marks an async function, component or file's exports as cacheable. Next.js runs it once for a given set of serializable inputs, stores the output, and reuses it until the entry revalidates through cacheLife or a cacheTag invalidation. Cached output can also be included in the route's prerendered static shell.

Is Cache Components enabled by default in Next.js 16.4?

Yes for new apps. Since Next.js 16.4, create-next-app generates a next.config.ts with cacheComponents: true and partialPrefetching: true. Existing apps keep the previous model until you enable the flag, and the Next.js team plans to make Cache Components the default for all apps in Next.js 17.

What is the difference between updateTag and revalidateTag?

updateTag runs only in Server Actions and expires a tag immediately, so the next read waits for fresh data and the user sees their own change. revalidateTag runs in Server Functions and Route Handlers; with the recommended 'max' profile it marks the tag stale and serves stale content while the next request refreshes it.

Can I use cookies() inside 'use cache'?

No. cookies(), headers() and searchParams are not allowed inside a 'use cache' scope or any helper it calls, and doing so throws the next-request-in-use-cache error. Read the value outside the cached function and pass it in as an argument. If you cannot refactor, 'use cache: private' allows request APIs but caches only in the browser.

Does 'use cache' replace unstable_cache?

For most code, yes, but you do not have to migrate. unstable_cache keeps working with Cache Components. One difference matters: unstable_cache and the fetch cache persist across deployments, while 'use cache' entries are keyed by build ID and start cold after every deploy.

Does 'use cache' work when self-hosting Next.js with Docker?

Yes. Node.js servers and Docker containers are supported; static export is not. Self-hosted, the default in-memory cache persists across requests in the same process, sized by cacheMaxMemorySize. With several replicas each has its own cache, so configure a shared cacheHandlers entry such as Redis if they must agree.

Originally published on fabwaseem.com.

Next.js Security Update October 2026: Patch the use cache RCE, SVG sharp RCE and Server Actions DoS

Waseem Anjum — Fri, 23 Oct 2026 19:04:06 +0000

The Next.js security update of October 14, 2026 fixes three vulnerabilities: two critical unauthenticated remote code execution (RCE) bugs, one in use cache and one in SVG image optimization through sharp, and a high severity denial of service in Server Actions. Upgrade to Next.js 16.4.1 or later on 16.x, or 15.5.28 on 15.x, make sure sharp is 0.35.5 or later, then rebuild and redeploy.

The patch is easy to apply and easy to get wrong when you self-host. I reproduced the upgrade on real installs and found that upgrading Next.js 15 to 15.5.28 left the vulnerable sharp 0.34.5 in place, while npm audit on an unpatched next@16.4.0 reported 0 vulnerabilities. This guide shows how to check whether you are affected, a script that checks for you, and the exact steps to patch a Docker or Coolify deployment. Everything is cited to the official advisories.

What did the October 2026 Next.js security update fix?

It fixed three advisories published on October 14, 2026, all patched in Next.js 16.4.1 (Active LTS) and 15.5.28 (Maintenance LTS), according to the official Next.js security update. Two allow unauthenticated remote code execution with a CVSS 4.0 score of 9.5; the third lets crafted requests pin a server's CPU.

Advisory	Severity	What it is	Affected `next` versions	Fixed in	Workaround
GHSA-673q-mjm6-r5xr	Critical, 9.5	RCE in `use cache` functions that return multiple typed arrays	16.0.0 to 16.4.0	16.4.1	None
CVE-2026-96889 / GHSA-2464-fhr4-w9xw	Critical, 9.5	RCE in the Image Optimization API with SVG, via `sharp`'s librsvg, on glibc Linux	10.0.0 to 15.5.27, 16.0.0 to 16.4.0	15.5.28, 16.4.1	`sharp` 0.35.5 or later
GHSA-p3m5-59mp-jv5r	High, 8.2	DoS: crafted requests cause excessive CPU in App Router apps with Server Actions	13.0.0 to 15.5.27, 16.0.0 to 16.4.0	15.5.28, 16.4.1	None

The two React Server Components bugs also have upstream React advisories: GHSA-xqc2-xf4c-x3h3 for the typed-array RCE and GHSA-h3gv-c5rc-p453 for the DoS. Next.js ships its own compiled copy of react-server-dom-webpack and react-server-dom-turbopack inside the next package (I checked node_modules/next/dist/compiled), so upgrading next is what fixes a Next.js app, not bumping react alone.

Quick definitions

Term	What it means
RCE	Remote code execution: an attacker can run code on your server
DoS	Denial of service: the server stops answering legitimate requests
GHSA	A GitHub Security Advisory ID
`sharp`	The image library Next.js uses for Image Optimization; it bundles libvips and librsvg
glibc	The C library used by Debian, Ubuntu and `node:*-slim` images (Alpine uses musl instead)
Active / Maintenance LTS	Next.js 16.4.x and 15.5.x, the two release lines that receive security fixes

TL;DR: how to patch Next.js now

Upgrade: npm install next@16.4.2 on 16.x (16.4.1 is the security release; 16.4.2 adds bug fixes) or npm install next@15.5.28 on 15.x.
Check sharp: run npm ls next sharp and confirm sharp@0.35.5 or later. On 15.x, run npm update sharp if it still shows 0.34.x.
Commit the lockfile, rebuild the image from scratch and redeploy.
Verify the running container, not just your laptop.

Is my Next.js app affected?

You are affected if your installed next is 16.0.0 through 16.4.0, or 15.5.27 and earlier, or if the sharp copy Next.js loads is older than 0.35.5. Which bugs reach you depends on features: use cache needs Cache Components, the DoS needs at least one Server Action, and the SVG bug needs glibc Linux.

Check the versions first:

npm ls next sharp

Then match your app against each advisory:

use cache RCE (GHSA-673q-mjm6-r5xr). Only Next.js 16 apps using the App Router with Cache Components can be exposed, and the trigger is a use cache function that returns multiple typed arrays. The advisory still says to upgrade immediately even if your application does not have similar functions. New apps from create-next-app 16.4 have Cache Components on by default, as I covered in Next.js use cache explained.
SVG Image Optimization RCE (CVE-2026-96889). A memory bug in librsvg, which sharp uses to decode SVG, can lead to RCE when Next.js runs on glibc-based Linux. That covers most Debian and Ubuntu based Docker images and VPS installs. By default Next.js does not optimize SVG images; apps that set images.dangerouslyAllowSVG: true are the clearest exposure, but the advisory is not limited to that setting, so patch either way.
Server Actions DoS (GHSA-p3m5-59mp-jv5r). Any App Router app with at least one Server Action, on Next.js 13 through 15.5.27 or 16.0.0 through 16.4.0. Pages Router apps and apps without Server Actions are not vulnerable.

Why does `npm audit` say my app is safe?

Because the advisory feed it reads may not list these issues yet. On October 17, 2026, I installed next@16.4.0, react and react-dom in an empty project and ran npm audit:

$ npm audit --json | jq .metadata.vulnerabilities
{ "info": 0, "low": 0, "moderate": 0, "high": 0, "critical": 0, "total": 0 }

Zero findings on a version with two open critical advisories. Treat npm audit, Dependabot and similar scanners as a backstop here and check the versions yourself, or use the script below.

A script that checks your app against all three advisories

I wrote this to check every app I run. It reads the installed next version, resolves sharp from Next.js's own folder (the copy the image optimizer actually loads), scans your source for use cache, use server and dangerouslyAllowSVG, and exits with code 1 if anything is unpatched, so you can drop it into CI. It has no dependencies.

// check-next-security.mjs: checks a Next.js app against the October 14, 2026 advisories.
// Usage: node check-next-security.mjs [projectDir]
import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
import { createRequire } from 'node:module'
import path from 'node:path'

const dir = path.resolve(process.argv[2] ?? '.')
const req = createRequire(path.join(dir, 'package.json'))
// Find node_modules/<pkg>/package.json the way Node would, without relying on "exports".
const version = (pkg, from = req) => {
  for (const base of from.resolve.paths(pkg) ?? []) {
    const file = path.join(base, pkg, 'package.json')
    if (existsSync(file)) return JSON.parse(readFileSync(file, 'utf8')).version
  }
  return null
}
const cmp = (a, b) => {
  const [x, y] = [a, b].map((v) => v.split('-')[0].split('.').map(Number))
  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i]
  return 0
}
const inRange = (v, lo, hi) => cmp(v, lo) >= 0 && cmp(v, hi) <= 0

// Scan source files for features the advisories depend on.
const src = []
const walk = (d) => {
  for (const name of readdirSync(d)) {
    if (['node_modules', '.next', '.git', 'out', 'dist'].includes(name)) continue
    const p = path.join(d, name)
    if (statSync(p).isDirectory()) walk(p)
    else if (/\.(m?[jt]sx?)$/.test(name)) src.push(readFileSync(p, 'utf8'))
  }
}
walk(dir)
const code = src.join('\n')
const uses = {
  useCache: /['"]use cache(: \w+)?['"]/.test(code),
  serverActions: /['"]use server['"]/.test(code),
  svgOptimizer: /dangerouslyAllowSVG\s*:\s*true/.test(code),
  nextOg: /from ['"]next\/og['"]/.test(code),
}

const next = version('next')
if (!next) { console.error('next is not installed in', dir); process.exit(2) }
// Resolve sharp from next's own folder, since that is the copy the image optimizer loads.
const nextPkg = (req.resolve.paths('next') ?? []).map((b) => path.join(b, 'next', 'package.json')).find(existsSync)
const sharp = version('sharp', createRequire(nextPkg))
const major = Number(next.split('.')[0])

const checks = [
  {
    id: 'GHSA-673q-mjm6-r5xr (critical): RCE in use cache returning typed arrays',
    vulnerable: inRange(next, '16.0.0', '16.4.0'),
    fix: 'upgrade next to 16.4.1+ (no workaround)',
    note: uses.useCache ? 'app uses "use cache"' : 'no "use cache" found, upgrade anyway',
  },
  {
    id: 'CVE-2026-96889 / GHSA-2464-fhr4-w9xw (critical): RCE via SVG in image optimization',
    vulnerable: sharp ? cmp(sharp, '0.35.5') < 0 : false,
    fix: 'sharp must be 0.35.5+ (npm update sharp), next 16.4.1+ or 15.5.28+',
    note: `sharp ${sharp ?? 'not installed'}` + (uses.svgOptimizer ? ', dangerouslyAllowSVG on' : '') + (uses.nextOg ? ', uses next/og' : ''),
  },
  {
    id: 'GHSA-p3m5-59mp-jv5r (high): DoS via Server Actions',
    vulnerable: inRange(next, '13.0.0', '15.5.27') || inRange(next, '16.0.0', '16.4.0'),
    fix: major >= 16 ? 'upgrade next to 16.4.1+' : 'upgrade next to 15.5.28+',
    note: uses.serverActions ? 'app defines Server Actions' : 'no "use server" found',
  },
]

console.log(`next ${next}, sharp ${sharp ?? 'not installed'} in ${dir}\n`)
let bad = 0
for (const c of checks) {
  if (c.vulnerable) bad++
  console.log(`${c.vulnerable ? 'VULNERABLE' : 'ok        '}  ${c.id}`)
  console.log(`            ${c.note}${c.vulnerable ? `\n            fix: ${c.fix}` : ''}`)
}
console.log(bad ? `\n${bad} issue(s) found. Patch, rebuild and redeploy.` : '\nAll three October 14, 2026 advisories are patched.')
process.exit(bad ? 1 : 0)

Run it from your project root with node check-next-security.mjs. This is the real output on a Next.js 16.4.0 app with one use cache function and one Server Action, before and after npm install next@16.4.2:

$ node check-next-security.mjs
next 16.4.0, sharp 0.35.4 in /app

VULNERABLE  GHSA-673q-mjm6-r5xr (critical): RCE in use cache returning typed arrays
            app uses "use cache"
            fix: upgrade next to 16.4.1+ (no workaround)
VULNERABLE  CVE-2026-96889 / GHSA-2464-fhr4-w9xw (critical): RCE via SVG in image optimization
            sharp 0.35.4
            fix: sharp must be 0.35.5+ (npm update sharp), next 16.4.1+ or 15.5.28+
VULNERABLE  GHSA-p3m5-59mp-jv5r (high): DoS via Server Actions
            app defines Server Actions
            fix: upgrade next to 16.4.1+

3 issue(s) found. Patch, rebuild and redeploy.

$ npm install next@16.4.2 && node check-next-security.mjs
next 16.4.2, sharp 0.35.5 in /app

ok          GHSA-673q-mjm6-r5xr (critical): RCE in use cache returning typed arrays
            app uses "use cache"
ok          CVE-2026-96889 / GHSA-2464-fhr4-w9xw (critical): RCE via SVG in image optimization
            sharp 0.35.5
ok          GHSA-p3m5-59mp-jv5r (high): DoS via Server Actions
            app defines Server Actions

All three October 14, 2026 advisories are patched.

The script checks versions and source patterns; it is not an exploit test. A clean result means you are on patched versions, which is what the advisories ask for.

How do you upgrade Next.js 16 to the patched version?

Install the latest 16.4 patch, then confirm sharp moved with it. Next.js 16.4.1 raised its sharp requirement to ^0.35.5 (16.4.0 accepted ^0.35.4; I read both from the npm registry), so npm has to upgrade sharp when you upgrade next.

npm install next@16.4.2
npm ls next sharp

In my test, a project whose lockfile held next@16.4.0 and sharp@0.35.4 came out of npm install next@16.4.1 with sharp@0.35.5, as expected. Run the same check with pnpm why sharp or yarn why sharp if you use those package managers.

eslint-config-next should match your next version, so bump it in the same commit. If you have not moved to 16 yet, the version 16 upgrade guide covers the breaking changes; that is a bigger job than this patch, so patch 15.x first.

How do you patch Next.js 15 safely?

Upgrade to 15.5.28, then check sharp separately, because upgrading next alone may not fix the SVG bug. Next.js 15.5.28 declares sharp as ^0.34.3 || ^0.35.5, so an existing lockfile that already resolved sharp 0.34.x still satisfies it, and npm keeps it.

This is what happened on a real project with next@15.5.27 and sharp@0.34.5 in the lockfile:

$ npm install next@15.5.28
$ npm ls sharp
└─┬ next@15.5.28
  └── sharp@0.34.5        # still vulnerable

$ npm update sharp
$ npm ls sharp
└─┬ next@15.5.28
  └── sharp@0.35.5        # fixed

If sharp is a direct dependency in your package.json, run npm install sharp@0.35.5 instead. To force one version across a monorepo, add an override:

{
  "overrides": {
    "sharp": "0.35.5"
  }
}

pnpm uses pnpm.overrides and Yarn uses resolutions for the same job.

How do you patch a self-hosted Next.js app in Docker or Coolify?

Update the lockfile, rebuild the image without reusing old layers, redeploy, then check the versions inside the running container. A dependency fix only protects you once the container that serves traffic contains it, and a Docker build that copies package-lock.json and runs npm ci installs exactly what the lockfile says.

Update and verify locally. npm install next@16.4.2, npm ls next sharp, run the checker.
Commit package-lock.json. Without it, your build server resolves whatever it resolved last time.
Rebuild the image. With the standalone output used in my production Next.js Dockerfile, next build copies sharp and its native libvips package into .next/standalone/node_modules. In my build that was @img/sharp-libvips-linux-x64, the glibc variant. An image built before the patch keeps the old sharp until you rebuild it.
Redeploy. In Coolify, push the commit or click Redeploy. To skip cached layers for this one build, trigger a forced deploy, for example through the Coolify API with GET /api/v1/deploy?uuid=<app-uuid>&force=true. My self-host Next.js with Coolify guide covers the deploy setup. With plain Docker, run docker compose build --no-cache && docker compose up -d.
Verify the running container. In a standalone image the app lives in /app, so:

docker exec <container> node -e "console.log(require('/app/node_modules/next/package.json').version, require('/app/node_modules/sharp/package.json').version)"

Requiring the package.json files by absolute path works even though sharp 0.35.5 does not export ./package.json. I checked the same command against a standalone build of Next.js 16.4.2; it printed 0.35.5 16.4.2 for sharp and next. Adjust the path if your Dockerfile copies the app somewhere other than /app.

What if you cannot upgrade Next.js today?

Only the SVG bug has an interim mitigation; the use cache RCE and the Server Actions DoS have no workaround, so plan the upgrade within hours, not weeks. In the meantime:

Bug	Interim step	Source
SVG / `sharp` RCE	Make sure `sharp` is 0.35.5 or later, even without upgrading `next`	Next.js advisory
SVG / `sharp` RCE	In your own code that calls `sharp`, block SVG decoding with `sharp.block({ operation: ['VipsForeignLoadSvg'] })`	sharp advisory
SVG / `sharp` RCE	Turn off `images.dangerouslyAllowSVG` if you do not need optimized SVGs	Image docs
`use cache` RCE	None. Upgrade.	Next.js advisory
Server Actions DoS	None. Upgrade. Rate limits only reduce the blast radius.	Next.js advisory

I tested the sharp.block call with sharp 0.35.5: before it, a small SVG converted to a 100-byte PNG; after it, the same call failed with Input buffer contains unsupported image format.

import sharp from 'sharp'

// Refuse to decode SVG input anywhere this sharp instance is used.
sharp.block({ operation: ['VipsForeignLoadSvg'] })

The sharp advisory adds one hardening note: whether the librsvg bug can reach code execution depends partly on the Node.js binary. It recommends a node built as a Position Independent Executable (PIE), notes that most Linux distribution packages already are, and warns that the official Node.js binaries are not.

How do you know whether you were attacked?

The advisories publish no indicators of compromise and do not mention exploitation in the wild, so look for the side effects each bug would leave, and re-check the advisories for updates.

DoS: sustained 100% CPU on a Next.js process together with slow or failed requests, especially POST requests carrying a Next-Action header.
SVG RCE: unexpected requests to /_next/image with .svg sources, crashes of the Node.js process during image optimization, and new child processes or outbound connections from the container.
Any RCE: unknown files in the container filesystem, changed environment variables or secrets used from new IPs. If you find any of these, rotate secrets (database URLs, API keys, NEXT_SERVER_ACTIONS_ENCRYPTION_KEY) after patching.

Security habits that make the next patch faster

This was an out-of-band release that landed eight days after 16.4.0 shipped on October 6. A few habits keep the next one to a ten-minute job:

Stay on an LTS line. Security fixes land on 16.4.x (Active LTS) and 15.5.x (Maintenance LTS).
Turn on upgrade nudges. Next.js 16.4 added experimental.agentUpgrade, whose default 'security' policy reminds you during next dev and next build when an upgrade fixes a known vulnerability in your installed version (Next.js 16.4 notes).
Run the checker in CI. Exit code 1 fails the build when a vulnerable version is installed.
Pin and commit lockfiles, then rebuild images from them so the running version is the one you reviewed.
Keep Server Actions small and authenticated. The DoS needs only one action to exist, but auth and input validation limit what any future bug can reach; see Server Actions vs Route Handlers.

Common mistakes when patching

Mistake	What happens	Fix
Upgrading `react` instead of `next`	Next.js keeps its bundled RSC runtime	Upgrade `next`
Upgrading 15.x to 15.5.28 and stopping	`sharp` 0.34.x can stay in the lockfile	`npm update sharp`, confirm 0.35.5+
Trusting `npm audit`	It reported 0 issues on unpatched 16.4.0	Check versions or run the script
Not committing the lockfile	CI or Coolify rebuilds the old versions	Commit `package-lock.json`
Rebuilding from a cached layer	Old `node_modules` layer is reused	Build once with no cache
Checking only the laptop	Production still runs the old image	`docker exec` into the running container

Related: I packaged the checker script above as a reusable agent skill, so Claude Code, Cursor, Codex or Copilot can run the check and patch for you. See Agent Skills: how to write a SKILL.md.

Related: running an MCP server next to your Next.js app? MCP security in 2026 covers this month's MCP SDK OAuth advisories and how to fix them.

Key takeaways

The October 14, 2026 update fixes two critical RCEs (use cache typed arrays and SVG via sharp) and a high-severity Server Actions DoS.
Patched versions are Next.js 16.4.1+ and 15.5.28+, with sharp 0.35.5 or later.
On 15.x, upgrading next can leave sharp 0.34.x installed; run npm update sharp and verify.
npm audit reported nothing for unpatched next@16.4.0 on October 17, 2026, so check versions directly.
A self-hosted fix only counts after you rebuild the image, redeploy and verify the versions inside the running container.

Originally published on fabwaseem.com.

Agent Skills Explained: How to Write a SKILL.md for Claude Code, Cursor, Codex and Copilot

Waseem Anjum — Fri, 23 Oct 2026 19:03:05 +0000

Agent Skills are now the standard way to teach an AI coding agent a repeatable job. Write one SKILL.md file and Claude Code, Cursor, OpenAI Codex, GitHub Copilot and VS Code can all load it. Next.js 16.4 even ships its own skills that you install with npx skills add.

In this guide I build a real skill, next-security-check, that checks a Next.js app against the October 2026 security advisories. I validate it with the official skills-ref validator and install it with the skills CLI. Along the way it covers the SKILL.md format, the folder each agent actually reads, and the mistakes that stop a skill from triggering. Every rule below is cited to the Agent Skills specification or to each agent's own docs.

What are Agent Skills?

Agent Skills are folders of instructions, scripts and reference files that an AI agent loads on demand to do a specific task. Each skill is a directory with a required SKILL.md file: YAML frontmatter with a name and description, then Markdown instructions. The agent reads only the name and description at startup and loads the rest when a task matches.

According to the Agent Skills overview, the format "was originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products." The client showcase lists the tools that support it, including Claude Code, Cursor, OpenAI Codex, GitHub Copilot, VS Code, Gemini CLI, OpenCode, Goose and JetBrains Junie.

Term	Meaning
Skill	A directory containing `SKILL.md` plus optional `scripts/`, `references/`, `assets/`
`SKILL.md`	Frontmatter (`name`, `description`, optional fields) followed by Markdown instructions
Activation	The agent decides a skill is relevant, or you invoke it with `/skill-name` or `$skill-name`
Progressive disclosure	Loading metadata first, the body on activation, and resources only when needed
`skills-ref`	The reference validator from the Agent Skills project
`skills` CLI	Vercel Labs' installer (`npx skills add`) that copies or links skills into each agent's folder

Why do Agent Skills matter right now?

Skills matter because they are the first agent customization format that works across vendors. The same folder runs in Claude Code, Cursor, Codex and Copilot. Framework teams now ship them: the Next.js 16.4 release tells you to run npx skills add vercel/next.js --skill next-bundle-optimizer, then /next-bundle-optimizer "in your AI agent of choice."

Running npx skills add vercel/next.js --list on October 17, 2026 showed the official Next.js skills, including:

next-bundle-optimizer: audits and cuts browser initial-load work
next-cache-components-adoption: turns on Cache Components and fixes the blocking routes it surfaces
next-cache-components-optimizer: grows the static shell, guarded by instant() tests
next-partial-prefetching-adoption and next-partial-prefetching-optimizer
next-dev-loop: verifies runtime behavior against a running next dev

If you already followed my Next.js use cache guide, next-cache-components-adoption is the skill that automates that migration.

How is a skill different from AGENTS.md, rules and MCP?

A skill is an on-demand procedure. AGENTS.md and rules files are always-on context. An MCP server is a live tool connection. Use AGENTS.md for facts every task needs, a skill for a multi-step job that only some tasks need, and MCP when the agent must call an external system such as a database or an API.

	AGENTS.md / CLAUDE.md / rules	Agent Skill (`SKILL.md`)	MCP server
Loaded	Every session	Name and description at startup; body on activation	Tool list at startup; calls at runtime
Best for	Conventions, commands, project facts	Repeatable procedures, checklists, scripts	Live data and actions in other systems
Contains	Markdown	Markdown + scripts + references + assets	Running code (stdio or HTTP)
Context cost	Always paid	About 100 tokens until used	Tool schemas, paid per server
Portable	Mostly, file names differ	Yes, one open spec	Yes, one open protocol

Claude Code's docs put it well: create a skill "when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure" (Claude Code skills). For the always-on side, see AGENTS.md vs CLAUDE.md vs Cursor rules. For live tools, see how to build an MCP server in Next.js.

What does the SKILL.md format look like?

A SKILL.md file starts with YAML frontmatter between --- lines, then free-form Markdown. The specification requires only two fields, name and description. license, compatibility, metadata and the experimental allowed-tools are optional. The body has no required structure; write the steps the agent should follow.

The folder layout for the skill in this guide:

.agents/skills/next-security-check/
├── SKILL.md                  # required: frontmatter + instructions
├── scripts/
│   └── check-next-security.mjs   # code the agent runs
└── references/
    └── advisories.md         # loaded only when SKILL.md points to it

Which frontmatter fields does the spec define?

Field	Required	Rule from the spec
`name`	Yes	1-64 chars; lowercase letters, numbers and hyphens; no leading, trailing or consecutive hyphens; must match the folder name
`description`	Yes	1-1024 chars; what the skill does and when to use it
`license`	No	License name or bundled license file
`compatibility`	No	Up to 500 chars; required tools, network access, target product
`metadata`	No	String-to-string map, e.g. `author`, `version`
`allowed-tools`	No	Space-separated pre-approved tools, e.g. `Bash(git:*) Read`; experimental, support varies

Agents add their own optional fields on top. Claude Code, Cursor and VS Code all support disable-model-invocation: true to make a skill run only when you type /skill-name. Claude Code and VS Code also support user-invocable: false to hide a background skill from the / menu (VS Code agent skills, Cursor skills). Other agents ignore fields they don't know. Claude Code says it "ignores a field it doesn't recognize without reporting an error."

How do I create an Agent Skill step by step?

To create an Agent Skill, make a folder named after the skill inside .agents/skills/, add a SKILL.md with a name that matches the folder and a description that says when to use it, then write numbered steps in the body. Put long material in references/, code in scripts/, and validate with skills-ref validate.

Step 1: Create the folder

mkdir -p .agents/skills/next-security-check/{scripts,references}

Step 2: Write SKILL.md

This is the exact file I validated and installed:

---
name: next-security-check
description: Checks a Next.js app against known Next.js security advisories and patches it. Use when the user asks whether their Next.js app is vulnerable, mentions a Next.js CVE or GHSA, asks to upgrade Next.js for security, or before deploying a Next.js app.
license: MIT
compatibility: Requires Node.js 18+ and npm, pnpm or yarn in a Next.js project
metadata:
  author: fabwaseem
  version: "1.0"
---

# Next.js security check

## Steps

1. Run the checker from the project root:
   `node .agents/skills/next-security-check/scripts/check-next-security.mjs .`
   Exit code 0 means patched, 1 means at least one advisory is open.
2. If it reports VULNERABLE, read [references/advisories.md](references/advisories.md)
   for the fixed versions, then upgrade:
   - Next.js 16.x: `npm install next@latest eslint-config-next@latest`
   - Next.js 15.x: `npm install next@15.5.28`, then `npm update sharp`
3. Run the checker again. Do not report success until it exits 0.
4. Run the project's own checks (`npm run lint`, `npm run build`) and report
   any failures instead of hiding them.
5. Tell the user to commit the lockfile, rebuild the Docker image without cache
   and redeploy. A patched laptop does not patch production.

## Gotchas

- `npm audit` can miss these advisories. Trust the checker's version comparison.
- On Next.js 15.5.28 the lockfile can keep `sharp` 0.34.x. Always re-check `sharp`.
- Upgrading `react` does not fix Next.js: Next.js bundles its own React Server
  Components runtime. Upgrade `next`.
- Never run `npm audit fix --force`; it can jump major versions.

## Output format

Report a short table: advisory, status before, status after, action taken.

The Gotchas section holds what I found the hard way while writing the Next.js security update guide. The best-practices guide says "the highest-value content in many skills is a list of gotchas," because they are facts the agent can't guess (Agent Skills best practices).

Step 3: Bundle the script and the reference

Copy the dependency-free checker from the security post into scripts/check-next-security.mjs, and keep the advisory table in references/advisories.md:

# Next.js advisories checked by this skill

| Advisory | Severity | Affected next | Fixed in | Workaround |
| --- | --- | --- | --- | --- |
| GHSA-673q-mjm6-r5xr: RCE in `use cache` returning typed arrays | Critical 9.5 | 16.0.0 to 16.4.0 | 16.4.1 | None |
| CVE-2026-96889 / GHSA-2464-fhr4-w9xw: RCE via SVG in image optimization (sharp, glibc) | Critical 9.5 | 10.0.0 to 15.5.27, 16.0.0 to 16.4.0 | 15.5.28, 16.4.1 (sharp 0.35.5+) | sharp 0.35.5+ |
| GHSA-p3m5-59mp-jv5r: DoS via Server Actions | High 8.2 | 13.0.0 to 15.5.27, 16.0.0 to 16.4.0 | 15.5.28, 16.4.1 | None |

Source: https://nextjs.org/blog/nextjs-security-update-october-14-2026

The agent only reads this file when step 2 sends it there. That is progressive disclosure working as designed.

Step 4: Test the script on its own

A skill is only as good as its script, so run it outside the agent first. On a project with next@16.4.0 it exits 1:

VULNERABLE  GHSA-p3m5-59mp-jv5r (high): DoS via Server Actions
            fix: upgrade next to 16.4.1+

2 issue(s) found. Patch, rebuild and redeploy.

On the same project after upgrading to next@16.4.2 it exits 0 with All three October 14, 2026 advisories are patched.

How do I validate a SKILL.md file?

Validate a skill with skills-ref validate <folder>, the reference validator from the Agent Skills project. It checks the frontmatter against the spec: required fields, name format, name matching the directory, and field lengths. It exits 0 when the skill is valid and 1 with a list of errors otherwise, so it works in CI.

Install it from the official repository (the project calls it a reference library "for demonstration purposes only", so treat it as a linter, not a runtime):

python3 -m venv .venv && . .venv/bin/activate
pip install "git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref"
skills-ref validate .agents/skills/next-security-check

Real output from my run:

Valid skill: .agents/skills/next-security-check

And the three mistakes I tested on purpose:

$ skills-ref validate bad/Next_Security
Validation failed for bad/Next_Security:
  - Skill name 'Next_Security' must be lowercase
  - Skill name 'Next_Security' contains invalid characters. Only letters, digits, and hyphens are allowed.

$ skills-ref validate bad/next-check
Validation failed for bad/next-check:
  - Directory name 'next-check' must match skill name 'next-security-check'

$ skills-ref validate bad/nodesc
Validation failed for bad/nodesc:
  - Missing required field in frontmatter: description

skills-ref to-prompt <folder> prints the <available_skills> XML block an agent would inject: name, description and location. Read it to see your skill the way the model sees it before activation.

Where does each agent look for skills?

Each agent scans its own folders, but they overlap. .agents/skills/ is read by Codex, Cursor, VS Code and GitHub Copilot. .claude/skills/ is read by Claude Code, Cursor, VS Code and Copilot. Claude Code does not list .agents/skills/, so keep the real folder in .agents/skills/ and symlink it into .claude/skills/.

Agent	Project folders	Personal folders	Manual invoke	Source
Claude Code	`.claude/skills/` (also nested `<subdir>/.claude/skills/`)	`~/.claude/skills/`	`/skill-name`	docs
Cursor	`.agents/skills/`, `.cursor/skills/`, plus `.claude/skills/` and `.codex/skills/` for compatibility	`~/.agents/skills/`, `~/.cursor/skills/`, `~/.claude/skills/`, `~/.codex/skills/`	`/` then the skill name	docs
OpenAI Codex	`.agents/skills/` in every directory from the working directory up to the repo root	`$HOME/.agents/skills`	`/skills` or `$skill-name`	docs
VS Code (Copilot Chat)	`.github/skills/`, `.claude/skills/`, `.agents/skills/`	`~/.copilot/skills/`, `~/.claude/skills/`, `~/.agents/skills/`	`/skill-name`	docs
GitHub Copilot	`.github/skills`, `.claude/skills`, `.agents/skills`	`~/.copilot/skills`, `~/.agents/skills`	per client	docs

You don't have to set up the symlink yourself. When I installed the skill with the skills CLI for Claude Code, Codex and Cursor, it did exactly that, as the next section shows.

How do I install skills with npx skills add?

npx skills add <source> installs skills from a GitHub repo, a URL or a local folder. It writes one canonical copy to .agents/skills/<name>/ and symlinks it into agent folders that need a different path, such as .claude/skills/. It also records the source and a content hash in skills-lock.json so installs are reproducible.

The CLI is vercel-labs/skills (version 1.7.2 on npm when I tested it). One thing tripped me up: it needs Node.js 22.20 or later. On Node 20 it crashes with SyntaxError: The requested module 'fs/promises' does not provide an export named 'glob'. On Node 24 it worked:

# see what a repo offers
npx skills add vercel/next.js --list

# install one official Next.js skill
npx skills add vercel/next.js --skill next-cache-components-adoption

# install your own local skill for three agents, no prompts
npx skills add ./.agents/skills/next-security-check -a claude-code -a codex -a cursor -y

The result in a fresh project:

◇  Installed 1 skill
│  ✓ ./.agents/skills/next-security-check
│    universal: Codex, Cursor
│    symlinked: Claude Code

.agents/skills/next-security-check/SKILL.md
.claude/skills/next-security-check -> ../../.agents/skills/next-security-check
skills-lock.json

On GitHub, the gh skill command in GitHub CLI can also discover and install skills from repositories (GitHub Docs). Other useful skills CLI commands: npx skills ls lists installed skills, npx skills update updates them, npx skills remove removes them, and npx skills init my-skill scaffolds a new SKILL.md. Commit .agents/, .claude/skills and skills-lock.json so the whole team gets the same skills.

The CLI ends every install with a warning worth repeating: "Review skills before use; they run with full agent permissions." Read a third-party skill's SKILL.md and scripts before you install it, exactly as you would read a postinstall script.

How does progressive disclosure keep context small?

Progressive disclosure means the agent loads a skill in three stages. The name and description (about 100 tokens) load at startup for every skill. The full SKILL.md body (under 5,000 tokens recommended) loads when the skill activates. Files in scripts/, references/ and assets/ load only when the instructions point to them.

The specification gives two size rules that follow from this:

Keep the main SKILL.md under 500 lines and move detailed material to separate files.
Keep file references one level deep from SKILL.md, and avoid chains like SKILL.md → a.md → b.md.

Because only metadata is always loaded, you can install dozens of skills for little context. Claude Code caps the listing too. It truncates the combined description and when_to_use text at 1,536 characters per skill, so it tells you to put the key use case first.

How do I write a description that actually triggers?

Write the description as two sentences: what the skill does, then "Use when..." followed by the words a user would actually type. Agents choose skills by matching the task against the description, so vague text like "Helps with Next.js" never fires. Name concrete triggers: error messages, file names, tool names and intents.

Compare:

Weak description	Strong description
`Helps with Next.js security.`	`Checks a Next.js app against known Next.js security advisories and patches it. Use when the user asks whether their Next.js app is vulnerable, mentions a Next.js CVE or GHSA, asks to upgrade Next.js for security, or before deploying a Next.js app.`
`Database stuff.`	`Writes and reviews Prisma migrations for PostgreSQL. Use when the user edits schema.prisma, asks for a migration, or sees a P3005 or drift error.`

OpenAI's Codex docs say the same: "write concise descriptions with clear scope and boundaries. Front-load the key use case and trigger words" (Codex skills). If a skill should never fire on its own, such as a deploy or a release, set disable-model-invocation: true in clients that support it and invoke it by name.

What makes a skill good? Best practices checklist

A good skill encodes knowledge the agent doesn't already have, gives an order of steps, and checks its own work. The best-practices guide recommends starting from a real task you have done, adding gotchas, providing templates and checklists, and building validation loops where the agent runs a check, fixes the problem and runs it again.

Use this checklist before you commit a skill:

One job per skill. "Check and patch Next.js security" is one job; "all things Next.js" is not.
Name matches the folder, lowercase with hyphens, 64 characters or fewer.
Description says what and when, with the trigger words a user would type.
Numbered steps with exact commands, not advice.
A Gotchas section with the non-obvious facts you learned the hard way.
A validation loop: run a check, fix, run it again, and only then report success (step 3 in the example).
Scripts for anything deterministic. A script that exits 0 or 1 beats a paragraph the model has to interpret.
References for long material, linked from SKILL.md, one level deep.
An output format so results look the same every run.
skills-ref validate passes in CI.
No secrets in the folder. Skills are committed and shared; read tokens from the environment.
Tested by hand in at least one agent with a prompt that should trigger the skill and one that shouldn't.

Common Agent Skill mistakes

The most common reasons a skill doesn't trigger or doesn't work are a folder name that doesn't match name, a vague description, a file in a folder the agent doesn't scan, and frontmatter that doesn't start on line 1. Claude Code says that if the opening --- isn't the first line it treats the whole file, markers included, as skill content.

Symptom	Likely cause	Fix
Skill never appears	Wrong folder for that agent	Use `.agents/skills/` plus a `.claude/skills/` symlink
Validator fails on name	Uppercase, underscores, or folder mismatch	Rename both to the same lowercase-hyphen name
Skill appears but never auto-triggers	Description lacks trigger words	Rewrite as "Does X. Use when ..."
Fields ignored	YAML doesn't parse or `---` not on line 1	Fix the YAML; Claude Code still loads the skill with no fields set when it doesn't parse
Agent says "done" too early	No validation loop	Add "run the check again; do not report success until it passes"
`npx skills` crashes	Node.js older than 22.20	Upgrade Node (24 LTS works)
Skill fires for deploys you didn't ask for	Auto-invocation on	`disable-model-invocation: true`

Related: Next.js links a vercel-react-view-transitions skill for adding page animations. My React View Transitions guide covers the same patterns with tested code.

Related: skills, MCP servers and plain APIs overlap. See MCP vs API for a benchmarked comparison and a decision guide for when an agent needs MCP at all.

Related: the AI SDK ships a migration skill for coding agents; my AI SDK 7 migration guide covers when to use it versus the official codemod, tested on a real v6 app.

Key takeaways

Agent Skills are folders with a SKILL.md (YAML name + description, then Markdown steps) plus optional scripts/, references/ and assets/.
One skill works across Claude Code, Cursor, Codex, GitHub Copilot, VS Code and the other clients listed on agentskills.io.
Put skills in .agents/skills/ and symlink them into .claude/skills/ for Claude Code; npx skills add does this for you.
Only about 100 tokens of metadata load per skill until it activates, so keep SKILL.md under 500 lines and move detail into references.
The description decides whether a skill triggers: say what it does and "Use when..." with real trigger words.
Validate with skills-ref validate, put gotchas and a validation loop in every skill, and review third-party skills before installing.
Next.js 16.4 ships official skills such as next-bundle-optimizer and next-cache-components-adoption.

Originally published on fabwaseem.com.

Better Auth with Next.js 16: proxy.ts, Prisma 7 and Server Actions (Tested Setup)

Waseem Anjum — Fri, 23 Oct 2026 07:05:25 +0000

Better Auth is an open-source (MIT) TypeScript authentication library that runs inside your own app and stores users and sessions in your own database. With Next.js 16 you mount one route handler, call auth.api.getSession() in server components and proxy.ts, and add the nextCookies() plugin so server actions can set cookies.

I built a complete Next.js 16.4.2 app with Better Auth 1.7.10, Prisma 7.10.1 and PostgreSQL 17: email and password sign-up and sign-in through server actions, a protected dashboard, a session check in proxy.ts and sign-out. Then I tested it with curl and headless Chrome, and counted every database query per page load. The setup works as documented, with two exceptions: one setting that does nothing on Prisma 7 unless you turn on a preview feature, and a React 19 form reset that wipes the email field.

TL;DR

Install better-auth, create lib/auth.ts with prismaAdapter(prisma) and nextCookies(), mount toNextJsHandler(auth) at app/api/auth/[...all]/route.ts, generate the schema with npx auth@latest generate and migrate with Prisma. Check the session in every protected page, not only in proxy.ts. A full proxy check plus a page check cost 4 database queries per load in my test, and the cookie cache cut that to 0.

Piece	File	What it does
Server config	`src/lib/auth.ts`	`betterAuth({ database, emailAndPassword, plugins })`
API route	`src/app/api/auth/[...all]/route.ts`	`toNextJsHandler(auth)` serves `/api/auth/*`
Client	`src/lib/auth-client.ts`	`createAuthClient()` from `better-auth/react`
Route guard	`src/proxy.ts`	Redirects signed-out users (optimistic)
Real check	each protected `page.tsx`	`auth.api.getSession({ headers: await headers() })`
Schema	`prisma/schema.prisma`	`user`, `session`, `account`, `verification`

Versions tested on October 17, 2026: better-auth 1.7.10 (released October 15; 1.8.0-beta.1 is on the beta tag), Next.js 16.4.2, React 19.3.1, Prisma 7.10.1, Node.js 24.22.0.

What is Better Auth?

Better Auth is a framework-agnostic authentication library for TypeScript. It handles email and password, social sign-in, sessions, and plugins for 2FA, organizations and passkeys, all inside your own server. Users, sessions and accounts live in your database through an adapter for Prisma, Drizzle, Kysely or a direct connection. There is no hosted service to call.

It is MIT licensed, had about 30,000 GitHub stars on its repository when I checked, and has shipped stable 1.x releases since 1.0.0 in November 2024. Its own security docs say passwords are hashed with scrypt by default.

How do I set up Better Auth in Next.js 16?

Install better-auth, add BETTER_AUTH_SECRET and BETTER_AUTH_URL to .env, create a betterAuth() instance with a database adapter, mount the handler at app/api/auth/[...all]/route.ts, then generate and migrate the schema. With Prisma 7 that takes six files and two CLI commands. Each step below is the exact code I ran.

Step 1: Install packages and set the secret

```bash title="Terminal"
npm i better-auth @prisma/client @prisma/adapter-pg
npm i -D prisma dotenv
npx prisma init --datasource-provider postgresql --output ../src/generated/prisma






```bash title=".env"
DATABASE_URL="postgresql://demo:demo@127.0.0.1:5432/badb"
BETTER_AUTH_SECRET="at-least-32-random-characters"   # openssl rand -base64 32
BETTER_AUTH_URL="http://localhost:3000"

better-auth 1.7.10 already depends on @better-auth/prisma-adapter, so import { prismaAdapter } from "better-auth/adapters/prisma" works without installing the adapter separately.

Two things surprised me with Prisma 7.10.1. prisma init wrote prisma7.config.ts, not prisma.config.ts. It also installed Prisma agent skills into .agents/, .claude/ and .windsurf/, so review that before you commit. Also, if your shell already exports DATABASE_URL, dotenv will not override it. My first migrate dev targeted the wrong database and asked to reset it. Read the target in the prompt before you answer yes.

Step 2: Create the Prisma client and the auth instance

```ts title="src/lib/prisma.ts"
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "@/generated/prisma/client";

const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };

export const prisma =
globalForPrisma.prisma ??
new PrismaClient({ adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL! }) });

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;






```ts title="src/lib/auth.ts"
import { betterAuth } from "better-auth";
import { prismaAdapter } from "better-auth/adapters/prisma";
import { nextCookies } from "better-auth/next-js";
import { prisma } from "./prisma";

export const auth = betterAuth({
  database: prismaAdapter(prisma, { provider: "postgresql" }),
  emailAndPassword: { enabled: true },
  plugins: [nextCookies()], // keep this last
});

export type Session = typeof auth.$Infer.Session;

Step 3: Mount the API route and create the client

```ts title="src/app/api/auth/[...all]/route.ts"
import { toNextJsHandler } from "better-auth/next-js";
import { auth } from "@/lib/auth";

export const { GET, POST } = toNextJsHandler(auth);






```ts title="src/lib/auth-client.ts"
import { createAuthClient } from "better-auth/react";

export const authClient = createAuthClient();

All Better Auth endpoints now live under /api/auth, for example POST /api/auth/sign-up/email and GET /api/auth/get-session.

Step 4: Generate the schema and migrate

```bash title="Terminal"
npx prisma generate
npx auth@latest generate --config src/lib/auth.ts --yes
npx prisma migrate dev --name add-better-auth




Run `prisma generate` first. With no generated client, `auth generate` could not load `src/lib/auth.ts` and hung for three minutes until I killed it. Once the client existed, it finished in seconds and wrote four models, `User`, `Session`, `Account` and `Verification`, mapped to the tables `user`, `session`, `account` and `verification`. The CLI only writes the schema. As the [Better Auth Prisma adapter docs](https://www.better-auth.com/docs/adapters/prisma) say, migrations are left to Prisma.

Better Auth 1.7 also checks the schema at startup. Before the migration ran, it logged `Prisma schema mismatch` and listed the missing tables. That is a useful early warning in CI.

## How do I sign in with a server action?

Call `auth.api.signInEmail()` or `auth.api.signUpEmail()` inside a `"use server"` function, and keep the `nextCookies()` plugin in your config. Without it the server action succeeds but sets no cookie. In my test the user stayed signed out and was redirected back to the sign-in page. With it, the session cookie was set and the redirect to `/dashboard` worked.



```ts title="src/app/actions.ts"
"use server";

import { headers } from "next/headers";
import { redirect } from "next/navigation";
import { APIError } from "better-auth/api";
import { auth } from "@/lib/auth";

export type SignInState = { error: string; email: string } | null;

export async function signIn(_: SignInState, form: FormData): Promise<SignInState> {
  const email = String(form.get("email"));
  try {
    await auth.api.signInEmail({ body: { email, password: String(form.get("password")) } });
  } catch (e) {
    // Return the email: React 19 resets the form after an action.
    if (e instanceof APIError) return { error: e.message, email };
    throw e;
  }
  redirect("/dashboard");
}

export async function signOut() {
  await auth.api.signOut({ headers: await headers() });
  redirect("/sign-in");
}

```tsx title="src/app/sign-in/page.tsx (sign-in form)"
"use client";

import { useActionState } from "react";
import { signIn } from "../actions";

export default function SignInPage() {
const [state, action, pending] = useActionState(signIn, null);
return (

{state.error}

}

);
}




Why return the email? React 19 resets a form after its action finishes. In my Chrome test, a wrong password showed "Invalid email or password" and the email field was empty. After returning the email from the action and using it as `defaultValue`, the field kept its value. See [useActionState](https://react.dev/reference/react/useActionState) for the pattern. Keep `redirect()` outside the `try` block, because it works by throwing.

## How do I protect routes with proxy.ts?

Next.js 16 renamed `middleware.ts` to `proxy.ts`, and it runs on Node.js, so `auth.api.getSession()` works there. Use the proxy only to redirect signed-out users early. Then check the session again in every protected page or server action, because the proxy can be skipped by a matcher mistake and it is not a security boundary.



```ts title="src/proxy.ts"
import { NextRequest, NextResponse } from "next/server";
import { headers } from "next/headers";
import { auth } from "@/lib/auth";

export async function proxy(request: NextRequest) {
  const session = await auth.api.getSession({ headers: await headers() });
  if (!session) {
    return NextResponse.redirect(new URL("/sign-in", request.url));
  }
  return NextResponse.next();
}

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

```tsx title="src/app/dashboard/page.tsx"
import { headers } from "next/headers";
import { redirect } from "next/navigation";
import { auth } from "@/lib/auth";
import { signOut } from "../actions";

export default async function DashboardPage() {
// The proxy only redirects. This check is the one that protects the page.
const session = await auth.api.getSession({ headers: await headers() });
if (!session) redirect("/sign-in");

return (

Welcome, {session.user.name}

Sign out

);
}




For a proxy with no database call, the [Better Auth Next.js docs](https://www.better-auth.com/docs/integrations/next) offer `getSessionCookie(request)` from `better-auth/cookies`, and label it "THIS IS NOT SECURE!" I tested why. A request with a made-up cookie, `better-auth.session_token=forged.value`, passed the cookie-only proxy. The page's own `getSession()` call then redirected it to `/sign-in`. With the full check in `proxy.ts`, the forged cookie was redirected at the proxy.

Next.js documents the rename and the codemod (`npx @next/codemod@canary middleware-to-proxy .`) in its [proxy.ts reference](https://nextjs.org/docs/app/api-reference/file-conventions/proxy).

## What did my tests show?

Everything in the core flow worked on the first production build (`next build` then `next start`). I tested with curl against the HTTP API and with headless Chrome 155 through the real forms and server actions:

| Test | Result |
| --- | --- |
| Visit `/dashboard` signed out | 307 to `/sign-in` |
| Sign up through the form (server action) | Redirect to `/dashboard`, "Welcome, UI Tester" |
| Same, without `nextCookies()` | No cookie set, user stays signed out |
| Session cookie | `better-auth.session_token`, `HttpOnly`, `SameSite=Lax`, `Max-Age=604800` (7 days) |
| Wrong password | 401 `INVALID_EMAIL_OR_PASSWORD` |
| Sign-in with `Origin: https://evil.example` | 403 `INVALID_ORIGIN` |
| Forged cookie, full proxy check | 307 to `/sign-in` |
| Forged cookie, cookie-only proxy | Passes proxy, page redirects to `/sign-in` |
| Sign out, then visit `/dashboard` | 307 to `/sign-in` |

Two notes. A curl request with no `Origin` header at all was accepted. That matches the [Better Auth security docs](https://www.better-auth.com/docs/reference/security), which allow requests that carry neither an Origin nor Fetch Metadata headers so that server-to-server and native clients keep working. Also, my cookie had no `Secure` flag over `http://localhost`. The [cookies docs](https://www.better-auth.com/docs/concepts/cookies) say cookies are secure in production mode, and `advanced.useSecureCookies: true` forces it.

## How many database queries does Better Auth make per request?

Each `getSession()` call made 2 queries on Prisma 7: one for the session by token and one for the user. A full check in `proxy.ts` plus a check in the page therefore cost 4 queries per page load. The cookie cache brought that to 0, and a cookie-only proxy to 2. I counted with PostgreSQL statement logging, over two warm dashboard loads per setup.

![Database queries per protected page load with Better Auth and Prisma 7: full proxy and page check 4, joins true without relationJoins 4, with relationJoins 2, cookie-only proxy 2, cookie cache 0](https://res.cloudinary.com/wasicloudinary/image/upload/v1792250133/fabwaseem/blog/better-auth-nextjs/diagram-queries.jpg)

| Setup (proxy + page check) | Queries per load | Median load time (local DB) |
| --- | --- | --- |
| Full `getSession()` in proxy and page | 4 | 7.3 ms |
| + `advanced.database.joins: true` | **4** (no change) | not measured |
| + `joins: true` and Prisma `relationJoins` preview | 2 | 6.8 ms |
| + `session.cookieCache` (5 min) | 0 | 5.9 ms |
| Cookie-only proxy, full check in page | 2 | 6.0 ms |

Times are the median of 300 requests from 2 runs against PostgreSQL on the same machine, so each query cost well under a millisecond. With a database in another region, every query is a network round trip, so the query count matters more than these timings suggest.

### Why doesn't `joins: true` reduce queries on Prisma 7?

Because Prisma 7 still runs `include` as separate queries unless you enable its `relationJoins` preview. With `joins: true` alone, the PostgreSQL log still showed `SELECT ... FROM "session"` followed by `SELECT ... FROM "user" WHERE "id" IN ($1)`. After adding `previewFeatures = ["relationJoins"]` and running `prisma generate`, getSession became one `LEFT JOIN LATERAL` query.



```prisma title="prisma/schema.prisma"
generator client {
  provider        = "prisma-client"
  output          = "../src/generated/prisma"
  previewFeatures = ["relationJoins"]
}

```ts title="src/lib/auth.ts"
export const auth = betterAuth({
// ...
advanced: { database: { joins: true } },
});




The Better Auth docs promise "2x to 3x performance improvements" from joins, depending on database latency, without mentioning the Prisma preview flag. Prisma's [relation queries docs](https://www.prisma.io/docs/orm/prisma-client/queries/relation-queries) list `relationJoins` as Preview. One caution: in my [Drizzle vs Prisma benchmark](https://www.fabwaseem.com/blog/drizzle-vs-prisma), `relationJoins` made paginated `include` queries with a deep `OFFSET` much slower. The flag applies to the whole client, so measure your other queries after enabling it.

### Should I enable the cookie cache?

Enable it if your sessions rarely change and you can accept a short revocation delay. With `cookieCache: { enabled: true, maxAge: 5 * 60 }`, Better Auth stores the session in a signed `better-auth.session_data` cookie and skips the database. The [session management docs](https://www.better-auth.com/docs/concepts/session-management) warn that a revoked session "may remain active on other devices until the cookie cache expires."



```ts title="src/lib/auth.ts"
export const auth = betterAuth({
  // ...
  session: {
    cookieCache: { enabled: true, maxAge: 5 * 60 }, // seconds
  },
});

One catch I hit. With a cookie-only proxy, the cache cookie never got written, because the only getSession() call ran in a server component and React Server Components cannot set cookies. The query count stayed at 2. Once session_data was set by a route handler (/api/auth/get-session) or by the full check in proxy.ts, page loads dropped to 0 queries. The Better Auth Next.js docs warn about this: "As RSCs cannot set cookies, the cookie cache will not be refreshed until the server is interacted with from the client via Server Actions or Route Handlers."

Better Auth vs Clerk: which should I use?

Choose Better Auth when you want auth inside your own app and database, no per-user vendor pricing and full control of the schema and UI. Choose Clerk when you want a hosted service with prebuilt sign-in components, a user dashboard and managed infrastructure. You trade control and data ownership for less code to run.

	Better Auth	Clerk
What it is	Library inside your app	Hosted authentication service
Where users live	Your database (Prisma, Drizzle, Kysely, SQL)	Clerk's infrastructure
License	MIT, open source	Commercial SaaS
UI	You build it (or use community components)	Prebuilt components
Self-hosting	Yes, runs wherever Next.js runs	No
You operate	Database, secrets, email delivery, upgrades	Integration only

Pricing and limits change, so check Clerk's docs for current plans. If you self-host Next.js, Better Auth fits that setup. My Next.js AI starter kit uses Better Auth 1.7.10 with Drizzle for that reason.

Can I use Better Auth with Prisma 8 or Drizzle?

Drizzle yes, Prisma 8 not yet. Better Auth 1.7.10's peer dependencies accept drizzle-orm 0.45.2 or newer, including the 1.0 release candidates, and @prisma/client 5, 6 or 7. Prisma 8 replaces @prisma/client with a new runtime package, so the Prisma adapter does not cover it yet.

If you are starting a new project, my Prisma 8 guide explains why to pin Prisma 7 for now. The Drizzle adapter is drizzleAdapter(db, { provider: "pg" }) from better-auth/adapters/drizzle.

Common Better Auth mistakes in Next.js

Relying on the proxy alone. Check the session in every protected page, route handler and server action.
Forgetting nextCookies(). Sign-in through a server action silently sets no cookie. Keep it last in plugins.
Putting redirect() inside try. redirect throws, so your catch swallows it.
Running auth generate before prisma generate. It cannot import a client that does not exist yet.
Expecting joins: true to work on Prisma 7 by itself. It needs the relationJoins preview.
A cookie-only proxy plus the cookie cache. RSCs cannot write the cache cookie, so it stays empty.
Hard-coding BETTER_AUTH_SECRET. Generate 32+ random bytes and keep it in your deployment's environment, not in git.

For the wider question of when to use server actions and when to use route handlers, see my server actions vs route handlers guide.

Key takeaways

Better Auth 1.7.10 works with Next.js 16.4 and Prisma 7: one route handler, an auth instance with prismaAdapter, and nextCookies() for server actions.
Generate the Prisma client before running npx auth generate, then migrate with Prisma; the Better Auth CLI writes the schema but does not migrate.
proxy.ts can run a full getSession() on Node.js, but always check the session again in each page; a forged cookie passed the cookie-only proxy in my test.
A full proxy check plus a page check cost 4 database queries per load on Prisma 7; the cookie cache cut it to 0.
advanced.database.joins only reduced queries after enabling Prisma's relationJoins preview.
React 19 resets forms after an action, so return the email from a failed sign-in action to keep it in the field.
Better Auth supports Drizzle 0.45 and 1.0 RC and Prisma 5 to 7, but not Prisma 8 yet.

Originally published on fabwaseem.com.

AI SDK 7 Migration: Upgrading from AI SDK 6 (What the Codemod Misses)

Waseem Anjum — Fri, 23 Oct 2026 07:05:03 +0000

An AI SDK 7 migration looks like a rename job: system becomes instructions, onFinish becomes onEnd, and there's a codemod for most of it. I upgraded a real AI SDK 6 app to see what's actually left after the codemod. The codemod ran in 20 seconds and fixed 15 lines, but it fixed only 1 of the 9 tests that broke. The rest were behaviour changes that TypeScript doesn't flag at all, including token usage that silently doubled and OpenTelemetry traces that silently stopped.

Here's the full upgrade path from AI SDK 6 to 7, with every number measured on ai 6.0.309 → 7.0.143.

TL;DR: how do I upgrade to AI SDK 7?

Make sure you're on Node.js 22 or later (24 LTS is better). AI SDK 7 drops Node 18 and 20.
Commit, then upgrade: npm i ai@7 @ai-sdk/react@4 @ai-sdk/openai@4 (and your other providers).
Run npx @ai-sdk/codemod v7 from the project root.
Run tsc --noEmit and fix what's left, mainly tool context.
Review the behaviour changes by hand: usage and toolCalls now cover all steps, step.response.messages is per step, onChunk gets every stream part, and system messages inside messages now throw.
If you use OpenTelemetry, install @ai-sdk/otel and call registerTelemetry(), or your traces stop.

Stage	TypeScript errors	Failing tests (of 13)	Lines changed
v6 baseline (`ai` 6.0.309)	0	0	none
Bump to `ai` 7.0.143, no code changes	6	9	0
After `npx @ai-sdk/codemod v7`	2	8	15
After manual fixes	0	0	+18 more

What's new in AI SDK 7?

AI SDK 7.0 shipped on June 25, 2026, and the current release is ai 7.0.143. The headline changes in the official migration guide are:

Node.js 22+ and ESM-only packages. No more CommonJS builds.
Renames out of experimental_: telemetry, include, onStart, onStepStart, transcribe, generateSpeech, and tool context.
New names for old concepts: system → instructions, onFinish → onEnd, onStepFinish → onStepEnd, fullStream → stream, stepCountIs → isStepCount.
Results cover every step. usage, toolCalls, toolResults, content and friends are accumulated across a multi-step tool loop, and the old final-step values move to result.finalStep.
Typed, per-tool context with contextSchema and toolsContext, separate from a shared runtimeContext.
Telemetry as a plug-in. OpenTelemetry lives in @ai-sdk/otel, and telemetry is on by default once you register an integration.
Safer defaults: system messages in messages are rejected, request bodies aren't kept in results, and MCP HTTP transports no longer follow redirects.

Most renames keep the old name as a deprecated alias, so your code keeps compiling. That's convenient, and it's also why a type check alone won't tell you whether the migration is done.

How I tested the upgrade

I wrote a small but realistic AI SDK 6 app, the kind of code you'd find in a Next.js chat product:

a tool loop with generateText, a system prompt, a weather tool reading experimental_context, stopWhen: stepCountIs(3), onStepFinish and onFinish callbacks logging token usage, and experimental_telemetry
a streaming chat route using streamText, convertToModelMessages and toUIMessageStreamResponse(), plus a fullStream consumer with an onChunk handler
structured output with experimental_output: Output.object(...)
stored chats whose first message is { role: 'system' }
a small CommonJS script that does require('ai')

Then I wrote 13 tests with node:test and the SDK's own MockLanguageModelV3, so every run is offline and deterministic. Each test pins down one behaviour the app relies on: the tool gets its context, usage is the final step's, the last step's messages hold the whole exchange, and so on. All 13 passed on v6 with zero TypeScript errors.

Versions: ai 6.0.309 → 7.0.143, @ai-sdk/openai 3.0.130 → 4.0.96, @ai-sdk/react 3.0.312 → 4.0.147, @ai-sdk/codemod 4.0.3, TypeScript 5.9.3, Node 24.22.

Step 1: bump the packages (6 type errors, 9 failing tests)

Upgrading the packages without touching code gave 6 TypeScript errors:

experimental_context is gone from both the generateText options and the tool's execute options (2 errors)
experimental_output is gone as an option and as a result property (2 errors)
usage.cachedInputTokens no longer exists
the ToolCallOptions type is no longer exported

And 9 of 13 tests failed. The scariest failure was one that didn't look like a failure: with experimental_context gone, the tool threw Cannot destructure property 'units' of 'experimental_context' as it is undefined. The SDK turned that into an error-text tool result, sent it back to the model, and my mock model still produced a normal answer. The "tool loop works" test passed. A real model would probably apologise or guess, and you'd find out from users.

The CommonJS script, on the other hand, kept working. AI SDK 7 ships only ESM, but Node 24 can require() ES modules natively, so require('ai') still returned the functions. On older Node versions without require(esm) support it will fail, but those versions aren't supported by AI SDK 7 anyway.

Step 2: run the codemod (2 type errors, 8 failing tests)

npx @ai-sdk/codemod v7 src test

It took 19.8 seconds and changed 15 lines in 4 files:

system → instructions (2 places) and stepCountIs → isStepCount
onStepFinish → onStepEnd, onFinish → onEnd
experimental_telemetry → telemetry
usage.cachedInputTokens → usage.inputTokenDetails.cacheReadTokens
experimental_output → output (option and result)
fullStream → stream
ToolCallOptions → ToolExecutionOptions
{ experimental_context } → { context: experimental_context } inside the tool's execute

Those are all correct, mechanical renames. What it couldn't do:

Tool context at the call site. It left experimental_context: { units: 'c' } in the generateText call, which is now a type error. The v7 design needs a contextSchema on the tool and a toolsContext object keyed by tool name, which isn't a rename.
The new generic. It swapped in ToolExecutionOptions, which now requires a type argument, so the codemod itself introduced a new type error.
Any behaviour change. It kept telemetry: { isEnabled: true } and kept reading result.usage and result.toolCalls exactly as before, now with different meanings.

The only test it fixed was structured output. Eight still failed.

Step 3: the behaviour changes you have to fix by hand

These are the changes that broke tests even after the codemod, with the fix I used for each.

Tool context. Declare what each tool needs and pass it per tool:

export const weather = tool({
  inputSchema: z.object({ city: z.string() }),
  contextSchema: z.object({ units: z.enum(['c', 'f']) }),
  execute: async ({ city }, { context: { units } }) => getWeather(city, units),
})

await generateText({
  model,
  tools: { weather },
  toolsContext: { weather: { units: 'c' } },
  // ...
})

The bonus is that context is now typed, so the as { units: ... } cast goes away.

Usage now covers all steps. In my two-step tool loop, result.usage.totalTokens went from 15 (final step only) to 30 (both steps), and cached input tokens went from 4 to 8. totalUsage is deprecated. If your billing, rate limits or logs read usage, decide which number you want. For the old meaning, read result.finalStep.usage. The same applies inside onEnd: event.usage is now all steps and event.finalStep.usage is the last step.

toolCalls and friends now cover all steps. result.toolCalls.length went from 0 to 1, because the tool call happened in step 1, not the final step. Same for toolResults, content, files, sources and warnings. Use result.finalStep.toolCalls for the old behaviour.

step.response.messages is per step. In v6 the last step's response.messages held the whole exchange (3 messages: tool call, tool result, answer). In v7 it held 1. If you persist the conversation from it, switch to result.responseMessages.

onChunk receives every stream part. My handler went from seeing 2 chunks (text-delta ×2) to 8, including start, start-step, text-start, text-end, finish-step and finish. Guard on chunk.type before using it.

System messages in messages throw. v6 printed a warning; v7 throws AI_InvalidPromptError: System messages are not allowed in the prompt or messages fields. That breaks old stored chats. I moved them into instructions:

const instructions = stored.filter(m => m.role === 'system').map(m => m.content).join('\n')
const messages = stored.filter(m => m.role !== 'system')
await generateText({ model, instructions: instructions || undefined, messages })

Only use allowSystemInMessages: true if every stored message came from your own server code, because a user-supplied system message is a prompt injection.

Deprecated stream helpers. result.toUIMessageStreamResponse() still works but is deprecated. The stateless replacement is createUIMessageStreamResponse({ stream: toUIMessageStream({ stream: result.stream }) }).

With these 18 extra lines across the same 4 files, I was back to 0 TypeScript errors, 13 of 13 tests passing and no deprecation warnings.

Does OpenTelemetry still work after upgrading to AI SDK 7?

Not by itself. This was the most silent break I found, and none of my tests caught it, so I tested it separately with an in-memory OpenTelemetry exporter.

v6 with experimental_telemetry: { isEnabled: true } recorded 2 spans: ai.generateText and ai.generateText.doGenerate.
v7, same code, recorded 0 spans. No error, no warning.
v7 with @ai-sdk/otel 1.0.143 and registerTelemetry(new OpenTelemetry()) at startup recorded 3 spans, with new names: invoke_agent mock-model-id, chat mock-model-id and step 1.

So you need the new package and you need to update any dashboard, alert or query that filters on the old ai.generateText span names. For Next.js, register it in instrumentation.ts:

import { registerTelemetry } from 'ai'
import { OpenTelemetry } from '@ai-sdk/otel'

registerTelemetry(new OpenTelemetry())

Once an integration is registered, every call is traced by default, so you can delete isEnabled: true and use isEnabled: false to opt out.

Which AI SDK 7 changes does the codemod catch?

The pattern is clear. Renames are covered: either the old name still works as an alias, or TypeScript flags it and the codemod fixes it. Semantic changes are not: all-steps results, per-step messages, onChunk and system messages pass the type check and slip past the codemod. Telemetry gets past all three.

If your app has no tests around its AI calls, write a few before you upgrade. Pin down token usage, what you persist, and what your tools receive.

Should I use the AI SDK migration skill?

Vercel also publishes an agent skill for this upgrade:

npx skills add vercel/ai --skill migrate-ai-sdk-v6-to-v7

Then you ask your coding agent to "use the migrate-ai-sdk-v6-to-v7 skill and migrate my app". The skill is a checklist that points at the migration guide, and it does say the right thing: "When v7 changes semantics, decide whether the app wants the new all-steps behavior or the previous final-step-only behavior." It also covers tool context, finalStep and @ai-sdk/otel, which the codemod can't.

My suggestion: run the codemod first for the mechanical renames, then let an agent with the skill (or yourself, with this list) work through the behaviour changes, and review that diff carefully. If you haven't used skills before, I explained how they work in Agent Skills explained.

Install size and performance: is AI SDK 7 heavier?

Barely. A fresh install of ai, @ai-sdk/openai, @ai-sdk/react and React was 23.8 MB across 18 packages on v6 and 24.3 MB across 26 packages on v7. The ai package itself grew from 7.2 MB to 8.2 MB. It dropped its @opentelemetry/api dependency (now in @ai-sdk/otel), while @ai-sdk/react 4 now pulls in @ai-sdk/mcp and cross-spawn.

Import time didn't change: import 'ai' took 113.5 ms on v6 and 115.4 ms on v7 (30 runs each with hyperfine, against 23.8 ms for an empty Node script), which is within noise.

Other AI SDK 7 changes worth checking

My test app didn't use these, but grep your code for them:

prepareStep overrides carry forward. Returned instructions and messages now stick for later steps instead of applying to one step.
Request and response bodies are excluded by default. If you log result.request.body, opt in with include: { requestBody: true }.
MCP redirects. createMCPClient HTTP and SSE transports now default to redirect: 'error' to block SSRF. If your MCP server redirects, set redirect: 'follow'. See my MCP security guide for why that default matters.
needsApproval is deprecated in favour of a toolApproval setting on the call.
Image parts become { type: 'file', mediaType: 'image', data }.
xAI now uses the Responses API by default, and OpenAI reasoning summaries default to 'detailed' when reasoning is on.
Google provider names drop GenerativeAI, for example createGoogleGenerativeAI → createGoogle.

Common AI SDK 7 migration mistakes

Stopping when tsc passes. Most of the deprecated names still compile. My app had 0 type errors with 8 failing tests in between.
Not reviewing the meaning of usage. It now covers all steps. Code that adds up per-step usage and then also adds the final usage will now count every step twice.
Forgetting @ai-sdk/otel. Traces stop without an error.
Trusting a passing "it answers" test. A tool that throws becomes a tool error the model can talk around.
Turning on allowSystemInMessages for user data. Move system prompts to instructions instead.

Key takeaways

AI SDK 7 needs Node.js 22+ and is ESM-only, but require('ai') still worked on Node 24 thanks to native require(esm).
Bumping ai 6.0.309 → 7.0.143 gave 6 TypeScript errors and 9 of 13 failing tests on a realistic app.
npx @ai-sdk/codemod v7 took 20 seconds and fixed 15 lines, but only 1 of the 9 failing tests.
usage, toolCalls and the other results now cover all steps; in my tool loop, usage went from 15 to 30 tokens. Use finalStep for the old meaning.
Tool context moved to contextSchema plus toolsContext; without it, the tool failed silently while the answer still looked fine.
OpenTelemetry recorded 0 spans after the upgrade until I added @ai-sdk/otel, and the span names changed.
Install size and import time are basically unchanged: 24.3 MB vs 23.8 MB and 115 ms vs 114 ms.

Related: my open-source Next.js AI starter kit, Forgekit, already runs on AI SDK 7 (it uses isStepCount), so you can compare against a working v7 chat app.

Originally published on fabwaseem.com.

How to Add a Remote MCP Server to Cursor, Claude Code, VS Code and Claude Desktop (Tested)

Waseem Anjum — Fri, 23 Oct 2026 06:26:39 +0000

A remote MCP server is a Model Context Protocol server you reach over HTTPS instead of starting it on your own machine. You add it with a URL, not a command. Every major AI coding client supports this now, but each one wants the URL in a slightly different shape. Cursor takes a bare url, Claude Code wants "type": "http", VS Code has two file formats, and Claude Desktop doesn't read a URL from its config file at all.

This guide gives you the working setup for each client, using a real public server: Benchline, my open-source developer tools site, which serves its tools over MCP at https://benchline.fabwaseem.com/mcp with no API key and no session. I checked every config block against the official docs on October 23, 2026, ran the Claude Code commands for real, called a tool through the official TypeScript SDK and through mcp-remote, and measured what the server costs in latency and in tokens. All numbers below come from those runs.

TL;DR: add a remote MCP server

Client	Where it goes	What to write
Cursor	`~/.cursor/mcp.json` or `.cursor/mcp.json`	`"mcpServers": { "name": { "url": "…/mcp" } }`
Claude Code	`claude mcp add` or `.mcp.json`	`claude mcp add --transport http name …/mcp` (JSON needs `"type": "http"`)
VS Code	`.vscode/mcp.json`, or `.mcp.json` / `~/.copilot/mcp-config.json`	`"servers"` with `"type": "http"`, or `"mcpServers"` with `"type": "http"`
Claude Desktop	Customize > Connectors	Add custom connector and paste the URL. Use `mcp-remote` in `claude_desktop_config.json` only for servers Anthropic's cloud can't reach

Before you blame the client, test the server with curl or the MCP Inspector. A remote server that answers tools/list will work in all four.

Measured from my build box, October 23, 2026	Result
`initialize`, new connection per request (n=20)	median 1,487 ms, p95 1,867 ms
`initialize`, one reused connection (n=20)	median 373 ms, p95 596 ms
`tools/list`, one reused connection (n=20)	median 911 ms, p95 973 ms
`tools/list` response size	138,658 bytes raw, 24,174 bytes gzip
Tool definitions the model reads (o200k_base)	17,517 tokens
`tools/call` through the TypeScript SDK, connected (n=20)	median 375 ms, p95 419 ms
Claude Code 2.1.309, `claude mcp add --transport http`	`✔ Connected`

What "remote" means in MCP

MCP has two standard transports. With stdio, the client starts the server as a child process (npx some-server) and talks to it through stdin and stdout. The server runs on your machine, with your files and your environment variables. With Streamable HTTP, the server is a web endpoint. The client POSTs JSON-RPC messages to one URL and reads the answer as JSON or as a Server-Sent Events stream. The transport spec defines both. The older HTTP+SSE transport is deprecated, and Claude Code's docs say to use HTTP where you can.

A remote server is just the second kind, hosted somewhere public. That has real advantages. You install nothing, the publisher ships fixes without asking you to update, and the same URL works in every client. It also means the server never sees your disk, which is a security win for tools that don't need it.

Benchline's endpoint is stateless: each POST stands alone, it returns no Mcp-Session-Id, and it answers with plain JSON. I explain how that server is built in Building Benchline: a stateless MCP server, and what the newer stateless spec changes in Stateless MCP servers and the 2026-07-28 spec. For this guide, all you need is the URL.

Check the server with curl first

A Streamable HTTP server must get both application/json and text/event-stream in the Accept header. This call lists the tools:

curl -sS -X POST https://benchline.fabwaseem.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

And this one calls a tool:

curl -sS -X POST https://benchline.fabwaseem.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"format_json","arguments":{"json":"{\"a\":1}"}}}'

Benchline accepts tools/list and tools/call without an initialize first, because it builds a fresh server for every request. A sessionful server would want initialize first and an Mcp-Session-Id header after that. When I sent initialize with protocol version 2025-06-18, the server answered with serverInfo benchline, the tools capability and no session header.

If you prefer a real client to raw JSON-RPC, the MCP Inspector has a CLI mode. Version 2.12.0 needs Node.js 22.19 or newer:

npx @modelcontextprotocol/inspector --cli \
  --transport http --server-url https://benchline.fabwaseem.com/mcp \
  --method tools/call --tool-name format_json --tool-arg 'json="{\"a\":1}"'

One gotcha I hit: --tool-arg parses the value as JSON. My first try, json={"a":1}, sent an object, and the tool rejected it with -32602 Input validation error: expected string, received object. Wrapping the value in quotes makes it a JSON string.

Cursor

Cursor reads ~/.cursor/mcp.json for servers you want in every project, and .cursor/mcp.json in a project for that project only. A remote server needs only a url:

{
  "mcpServers": {
    "benchline": {
      "url": "https://benchline.fabwaseem.com/mcp"
    }
  }
}

For a server that needs a token, add headers and read the value from your environment with Cursor's ${env:NAME} interpolation, so the secret never lands in the file:

{
  "mcpServers": {
    "my-api": {
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}" }
    }
  }
}

Servers that use OAuth need no header. Cursor runs the sign-in itself, using PKCE and the server's protected resource metadata. If a server doesn't show up, open the Output panel and pick MCP Logs. Source: Cursor MCP docs.

Claude Code

Claude Code has a one-line command for remote servers:

claude mcp add --transport http benchline https://benchline.fabwaseem.com/mcp
claude mcp list

On Claude Code 2.1.309 this printed Added HTTP MCP server benchline with URL: https://benchline.fabwaseem.com/mcp to local config, and claude mcp list showed benchline: https://benchline.fabwaseem.com/mcp (HTTP) - ✔ Connected. The default scope is local: the entry is saved in ~/.claude.json under the current project. Add --scope user to use it in every project, or --scope project to write it to .mcp.json and commit it for your team. For a token, pass --header "Authorization: Bearer …". For OAuth servers, run /mcp inside a session or claude mcp login <name>.

The project file looks like this:

{
  "mcpServers": {
    "benchline": {
      "type": "http",
      "url": "https://benchline.fabwaseem.com/mcp"
    }
  }
}

Don't paste a Cursor block into .mcp.json. Claude Code reads an entry without type as a stdio server. When I tried the Cursor-style block above, claude mcp list printed Skipped — invalid MCP server config for "benchline": command: expected string, received undefined, and the server was not loaded. Adding "type": "http" fixes it, and "streamable-http" works as an alias. Source: Claude Code MCP docs.

VS Code

VS Code now reads two formats, and it matters which file you edit.

The VS Code format lives in .vscode/mcp.json in your workspace, or in your user profile. It uses a top-level servers object, and type is required:

{
  "servers": {
    "benchline": {
      "type": "http",
      "url": "https://benchline.fabwaseem.com/mcp"
    }
  }
}

The portable format lives in .mcp.json at the workspace root, or in ~/.copilot/mcp-config.json for your user. It uses mcpServers, the same shape as Claude Code's file, so one committed .mcp.json can serve both tools:

{
  "mcpServers": {
    "benchline": {
      "type": "http",
      "url": "https://benchline.fabwaseem.com/mcp"
    }
  }
}

The guided MCP: Add Server command now suggests the Copilot Global file first and labels .vscode/mcp.json as deprecated, though VS Code still reads it. The two formats handle secrets differently. .vscode/mcp.json supports ${input:…} prompts and ${env:NAME}, while portable files use ${NAME} and no input prompts. VS Code first tries Streamable HTTP and falls back to SSE. Source: VS Code MCP configuration reference.

Claude Desktop

This is where most copy-paste setups break. claude_desktop_config.json is for local stdio servers. The supported way to add a remote server is a custom connector:

Open Customize > Connectors (on the web, claude.ai/customize/connectors).
Click + Add, then Add custom connector.
Enter a name and the server URL, https://benchline.fabwaseem.com/mcp.
Under Authentication, pick No sign in for a public server like Benchline, or sign in for an OAuth server. There is also a Request headers section for API keys.
In a chat, enable it from + > Connectors.

Custom connectors work on Free (one connector), Pro, Max, Team and Enterprise plans. On Team and Enterprise, an Owner adds the connector first. One detail matters a lot: Claude connects to a custom connector from Anthropic's cloud, not from your computer. The server has to be reachable from the public internet. A server on localhost, behind a VPN or on a company network won't connect, even if curl works on your laptop. Source: Claude Help Center.

For those servers, bridge the URL to stdio with mcp-remote in claude_desktop_config.json (on macOS in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\):

{
  "mcpServers": {
    "benchline": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://benchline.fabwaseem.com/mcp"]
    }
  }
}

Claude Desktop starts mcp-remote as a local process, and mcp-remote speaks Streamable HTTP to the server from your own network. I tested this by starting mcp-remote 0.15.2 from the official TypeScript SDK's stdio client, the way Claude Desktop would. The format_json call came back valid. The first start took 11.2 s, including npx fetching the package, and the call itself took 970 ms. For a token, use --header and keep the value in env, or --header-file so the secret stays out of the process list.

Call a tool with the official TypeScript SDK

To check a server from code, or to use one in your own agent, the official SDK client takes about ten lines:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "remote-mcp-check", version: "1.0.0" });
await client.connect(
  new StreamableHTTPClientTransport(new URL("https://benchline.fabwaseem.com/mcp")),
);

const { tools } = await client.listTools();
const result = await client.callTool({
  name: "format_json",
  arguments: { json: '{"b":2,"a":[1,2]}' },
});
console.log(result.structuredContent); // { output: '{\n  "b": 2, …', valid: true, errors: [] }
await client.close();

With @modelcontextprotocol/sdk 1.32.1, the client negotiated protocol 2025-11-25, got no session id, and the call returned structuredContent with valid: true. Twenty calls on that connected client took a median of 375 ms and a p95 of 419 ms.

The v2 client, @modelcontextprotocol/client 2.3.1, with versionNegotiation: { mode: "auto" } also connected and fell back to 2025-11-25, because Benchline's server doesn't speak 2026-07-28 yet. A direct 2026-07-28 request got Unsupported protocol version, and the list of versions the server does accept. Clients that negotiate handle this for you. Claude Code's v2 runtime, for example, asks each server which revision it supports and uses the newer one only where the server has it.

What a remote MCP server costs your context window

Speed is rarely the problem with MCP. Tokens are. Each tool's name, description and JSON Schema can end up in the model's context, and that's paid on every turn. So I measured Benchline's tools/list:

The full JSON-RPC response is 138,658 bytes. With curl --compressed the server sent 24,174 bytes of gzip.
Counted with the o200k_base tokenizer (via js-tiktoken), the whole response is 34,307 tokens.
Keep only what a model needs to choose and call a tool, meaning name, description and inputSchema, and it comes to 17,517 tokens (72,398 bytes of JSON). A rough characters-divided-by-4 estimate gives 18,100. Benchline's output schemas make up 52,458 bytes of the full response.
The largest single tool definition, build_open_graph, is 584 tokens. The smallest is 75.

These are approximations. o200k_base is OpenAI's tokenizer, Claude and other models count differently, and each client decides which fields it forwards. Still, the order of magnitude holds. For comparison, the MCP server behind this site came to 5,949 tokens in my MCP vs API benchmark. Some clients soften the cost. Claude Code uses tool search by default, so Claude can look up tools when it needs them. VS Code lets you choose which tools a session can use, and Cursor lets you toggle whole servers off. Turn off what you aren't using.

Latency: why the first request is slow

I measured with curl from my build box, which reaches the internet through an egress proxy, so the absolute numbers include that path. Yours will differ. The pattern is the useful part:

Request (n=20 each)	New connection per request	One reused connection
`initialize`	median 1,487 ms, p95 1,867 ms	median 373 ms, p95 596 ms
`tools/list`	median 2,043 ms, p95 2,391 ms	median 911 ms, p95 973 ms

On a fresh connection, the TCP and TLS setup alone took a median of 928 ms before the first byte of the request went out. On a reused connection, tools/list sent its first byte after a median of 395 ms, and most of the remaining time went into downloading the uncompressed 138 KB body. Real clients keep connections open and fetch the tool list once per session, so you pay the slow path roughly once. Two practical points follow. A server with a large tool list should support compression. And MCP_TIMEOUT in Claude Code, or your client's equivalent, should allow a few seconds for the first connect.

Troubleshooting remote MCP servers

Every error below is one I triggered against the live server or found in the client docs:

406 Not Acceptable: Client must accept both application/json and text/event-stream. Your Accept header is missing one of the two types. Real clients send both; hand-written curl and fetch calls often don't.
405 Method not allowed on GET. Normal for a stateless server that offers no server-to-client stream. The spec allows it, and clients carry on.
Skipped — invalid MCP server config … command: expected string in Claude Code. You have a url without "type": "http".
A connector works in curl but not in Claude Desktop. Anthropic's cloud makes the connection, so it can't reach private networks. Use mcp-remote, or put the server somewhere public.
401 Unauthorized. The server wants OAuth or a token. Claude Code flags the server under /mcp, where you can sign in, and Cursor and VS Code both support OAuth for HTTP servers. If you configured a static Authorization header and it's rejected, fix the token: Claude Code won't fall back to OAuth.
429 Too many requests. Public servers rate-limit. Benchline allows 60 requests a minute per address and sends retry-after.
Unsupported protocol version. The client asked for a revision the server doesn't have. Use a client that negotiates, or pin a version both support.
Spaces in mcp-remote header args on Windows. The mcp-remote README warns that Cursor, Codex CLI and Claude Desktop on Windows don't escape spaces inside args. Write Authorization:${AUTH_HEADER} with no space and put Bearer … in env.

Security checklist for remote MCP servers

A remote server can't read your files, but it can still influence your agent. Before adding one:

Trust the publisher. Tool descriptions and tool output reach your model, and both can carry prompt injection. Servers that fetch web content are the main risk.
Keep secrets out of config files. Use ${env:NAME} in Cursor, ${NAME} in Claude Code and portable VS Code files, or ${input:…} in .vscode/mcp.json. Never commit a populated Authorization header.
Prefer OAuth over shared keys for anything multi-user, and read what scopes you grant.
Keep tool approval on for tools that write or delete, and approve one call at a time until you trust a server.
Pin mcp-remote (mcp-remote@0.15.2) in shared configs, so npx doesn't pull a new version silently.

For the server side, including the OAuth SDK flaws I reproduced this month, read MCP security in 2026. If you want to build a remote server of your own, How to build an MCP server in Next.js covers the route handler, bearer auth and Origin checks.

How I tested

All tests ran on October 23, 2026, from my Linux build box against the live https://benchline.fabwaseem.com/mcp:

Latency: curl 8.14.1, 20 sequential initialize and 20 tools/list POSTs with a new connection each and a 1.5 s pause to stay under the rate limit. Then 20 of each on one connection with curl --next. Median and p95 come from time_total, using linear interpolation.
Size and tokens: the saved tools/list body, counted with js-tiktoken and the o200k_base ranks.
SDK: @modelcontextprotocol/sdk 1.32.1 and @modelcontextprotocol/client 2.3.1 on Node.js 20.19. Twenty format_json calls on one connected client, 1.2 s apart.
Clients: Claude Code 2.1.309 in a throwaway HOME. mcp-remote 0.15.2 started over stdio by the SDK. MCP Inspector 2.12.0 CLI. I checked the Cursor, VS Code and Claude Desktop syntax against their official docs on the same day, but didn't run those apps on the box.

FAQ

What is a remote MCP server?

A Model Context Protocol server you reach over HTTPS with the Streamable HTTP transport, instead of a local process your client starts over stdio. You add it with a URL, nothing is installed on your machine, and the same URL works in Cursor, Claude Code, VS Code and Claude Desktop.

How do I add a remote MCP server to Cursor?

Add an entry with only a url under mcpServers in ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for one project, for example "benchline": { "url": "https://benchline.fabwaseem.com/mcp" }. Add headers with ${env:NAME} for token auth. Cursor runs OAuth itself for servers that need it.

What is the claude mcp add command for an HTTP server?

claude mcp add --transport http , for example claude mcp add --transport http benchline https://benchline.fabwaseem.com/mcp. It saves to local scope by default. Add --scope user for every project or --scope project to write .mcp.json, and --header for a bearer token. Check it with claude mcp list.

Why does Claude Code skip my MCP server from .mcp.json?

An entry with a url but no type is read as a stdio server and skipped. In my test Claude Code 2.1.309 reported command: expected string, received undefined. Add "type": "http" (or the alias "streamable-http") next to the url.

Can I put a remote URL in claude_desktop_config.json?

No. That file is for local stdio servers. Add remote servers in Claude Desktop under Customize > Connectors > Add custom connector. For a server that Anthropic's cloud cannot reach, run npx -y mcp-remote as a stdio command in claude_desktop_config.json.

Why does my custom connector fail in Claude when curl works?

Claude connects to custom connectors from Anthropic's cloud, not from your computer. A server on localhost, a VPN or a private network is unreachable from there. Host it publicly, allowlist Anthropic's IP ranges, or bridge it with mcp-remote, which connects from your own network.

How many tokens does an MCP server add to the context?

It depends on its tool schemas. Benchline's tool names, descriptions and input schemas came to 17,517 tokens with the o200k_base tokenizer, and the whole tools/list response to 34,307. The MCP server behind fabwaseem.com is 5,949 tokens. Turn off servers and tools you don't need.

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

POST a tools/list JSON-RPC request with curl, sending content-type: application/json and accept: application/json, text/event-stream, or run npx @modelcontextprotocol/inspector --cli --transport http --server-url --method tools/list. A missing Accept type returns HTTP 406.

Key takeaways

A remote MCP server is a Streamable HTTP endpoint. You add it with a URL, and nothing runs on your machine.
Cursor takes a bare url. Claude Code and VS Code need "type": "http", and Claude Code skips a url entry without it.
Claude Desktop adds remote servers as custom connectors, and the connection comes from Anthropic's cloud. Use mcp-remote in claude_desktop_config.json for servers that cloud can't reach.
Test with curl or the MCP Inspector first. The Accept header must list both application/json and text/event-stream.
Benchline's tool definitions came to 17,517 tokens (o200k_base). Context cost is the real price of adding a server, so turn off tools you don't use.
On one connection, a tools/call through the TypeScript SDK took a median of 375 ms. The first connect is the slow part.
Keep tokens in environment variables, prefer OAuth, and leave tool approval on for anything that writes.

Originally published on fabwaseem.com, where I write about MCP, AI automation, Node.js and Next.js.

Server-Sent Events in NestJS: Live Job Progress with @Sse, and the Gotchas I Hit in Chrome

Waseem Anjum — Mon, 19 Oct 2026 05:29:34 +0000

I added live progress to a long-running job API with NestJS's @Sse() decorator and it worked on the first try. Then I tested it properly, in a real browser, and found three things the ten-line example doesn't warn you about: a finished stream makes EventSource reconnect and replay it, Nest's automatic event ids restart at 1 on every connection, and six open streams over HTTP/1.1 freeze every other request to that host.

This is the write-up. The patterns come from Snagbox, my open-source NestJS media downloader API, which streams download progress over SSE. Every behaviour below was checked on NestJS 12.1.3, Node.js 22.20 and headless Chrome 155, and every number was measured on my machine (method at the end).

TL;DR: NestJS SSE in production

Return an Observable<MessageEvent> from an @Sse() route. Then:

Give each job its own ReplaySubject(1), so a client that connects mid-job gets the latest progress at once. In my test that took 2 to 4 ms, against 451 to 1,002 ms with a plain Subject.
Set id on every message yourself. Nest numbers messages per connection, so after a reconnect the ids start at 1 again and Last-Event-ID is useless.
Close the EventSource on the client when the job finishes. When your Observable completes, the browser treats it as a dropped connection and reconnects, and it replayed my stream three times in 1.6 seconds.
Send a heartbeat as a comment frame ({ comment: "ping" }). The client never sees it, and Nest gives it no id.
Don't open one stream per item in a batch. Over HTTP/1.1, Chrome opened 6 of 8 streams to my server, and an ordinary fetch() to the same host was still waiting 5 seconds later. Poll one batch endpoint instead, or serve over HTTP/2.

Result (measured on the box)	Value
One 10 s job, 40 updates, SSE	1 request, 40 of 40 updates, 4,516 bytes
Same job, polling every 1 s	11 requests, 10 of 40 updates, 4,438 bytes
Same job, polling every 250 ms	41 requests, 40 of 40 updates, 16,506 bytes
SSE delivery lag on localhost	0.8 ms mean, 2 ms max
Late joiner, `ReplaySubject(1)` vs `Subject`	2 to 4 ms vs 451 to 1,002 ms to first frame
Server memory per open stream	about 34 to 64 KB of RSS (5,000 and 1,000 streams)
Chrome 155, HTTP/1.1, 8 `EventSource`s	6 opened, the 7th, 8th and a `fetch()` stalled

What are Server-Sent Events?

SSE is a plain HTTP response with Content-Type: text/event-stream that never ends until one side closes it. The server writes UTF-8 frames separated by a blank line. Each frame can carry data:, an event: name, an id: and a retry: delay, and a line starting with : is a comment. The format and the reconnection rules are in the WHATWG HTML spec.

In the browser, EventSource does all the client work. It parses frames, fires events, remembers the last id, and reconnects after a dropped connection, sending that id back in a Last-Event-ID header.

SSE only goes from the server to the client. For job progress, notifications, build logs and streamed LLM tokens, that is all you need. The client can still send commands through normal POST requests.

SSE vs WebSockets vs polling

	SSE	WebSockets	Polling
Direction	Server to client	Both ways	Client asks
Protocol	Plain HTTP	Upgrade to `ws://`	Plain HTTP
Reconnects	Built into `EventSource`	You write it	Not needed
Works through HTTP proxies and CDNs	Usually, if buffering is off	Needs upgrade support	Yes
Custom request headers from the browser	No	No	Yes
Nest setup	`@Sse()` in a controller	A gateway and an adapter	A `@Get()` route

Use WebSockets when the client also streams data back at a high rate, for example in chat or collaborative editing. Use polling when updates are rare or when you track many items at once (more on that below). For one long job and one watcher, SSE is the best fit.

How to use @Sse in NestJS

The smallest working endpoint returns an Observable. Nest writes every emitted value as a frame and ends the response when the Observable completes.

import { Controller, MessageEvent, Sse } from "@nestjs/common";
import { Observable, interval, map, take } from "rxjs";

@Controller("demo")
export class DemoController {
  @Sse("ticks")
  ticks(): Observable<MessageEvent> {
    return interval(1000).pipe(
      take(5),
      map((i) => ({ data: { tick: i } })),
    );
  }
}

Objects in data are serialized as JSON. The MessageEvent interface in @nestjs/common 12.1.3 has five optional fields: data, id, type, retry and comment. The full list of features is in the NestJS SSE docs.

I checked the response headers with curl -D -. Nest 12.1.3 sends Content-Type: text/event-stream, Cache-Control: private, no-cache, no-store, must-revalidate, max-age=0, no-transform, Connection: keep-alive and X-Accel-Buffering: no. The last one tells Nginx not to buffer the stream, which is the most common reason SSE "works locally but not in production". You don't have to set it yourself.

Streaming job progress: one ReplaySubject per job

A real job runs in a worker, not in the controller. The worker needs somewhere to publish progress, and the SSE route needs somewhere to subscribe. In Snagbox that is a small service holding one RxJS subject per job (source). This is a trimmed version:

import { Injectable } from "@nestjs/common";
import { Observable, ReplaySubject } from "rxjs";

export type JobEvent =
  | { type: "progress"; seq: number; percentage: number }
  | { type: "complete"; seq: number; url: string }
  | { type: "error"; seq: number; message: string };

@Injectable()
export class JobEventsService {
  private readonly channels = new Map<string, ReplaySubject<JobEvent>>();

  private channel(jobId: string): ReplaySubject<JobEvent> {
    let subject = this.channels.get(jobId);
    if (!subject) {
      // Buffer of 1: a client that joins mid-job gets the latest frame at once.
      subject = new ReplaySubject<JobEvent>(1);
      this.channels.set(jobId, subject);
    }
    return subject;
  }

  emit(jobId: string, event: JobEvent): void {
    this.channel(jobId).next(event);
  }

  finish(jobId: string, event: JobEvent): void {
    const subject = this.channel(jobId);
    subject.next(event);
    subject.complete();
    // Late subscribers still get the terminal frame for a while, then we free it.
    setTimeout(() => this.channels.delete(jobId), 5 * 60_000).unref();
  }

  stream(jobId: string): Observable<JobEvent> {
    return this.channel(jobId).asObservable();
  }
}

Why ReplaySubject(1) and not Subject? Users don't open the progress page at the exact moment a job starts. They refresh, switch tabs, or open it from a notification. A plain Subject only delivers future values, so a late client sees an empty progress bar until the next update arrives.

I measured this. A job emitted progress every 2 seconds, and a client connected between two updates, 5 seconds in, five times. With ReplaySubject(1) the first frame arrived in 2 to 4 ms. With Subject it took 451 to 1,002 ms, which is simply the wait for the next emit. With slower jobs, such as a big download that reports every few seconds, that wait gets longer.

Keep the buffer at 1. Progress is a state, not a log, so the latest frame is all a new client needs, and a bigger buffer only replays stale percentages.

This map lives in one process. If you run several API instances, the worker's events have to reach whichever instance holds the client's connection. Put a broker in between, such as Redis pub/sub, and feed each instance's subjects from it.

The production SSE controller

Here is the route, close to Snagbox's downloads controller but with three changes I made after testing:

import { Controller, MessageEvent, NotFoundException, Param, Sse } from "@nestjs/common";
import { Observable, endWith, ignoreElements, interval, map, merge, of, share, takeUntil } from "rxjs";
import { JobEventsService, type JobEvent } from "./job-events.service.js";
import { JobStore } from "./job-store.js";

const HEARTBEAT_MS = 15_000;
const toMessage = (event: JobEvent): MessageEvent => ({ id: String(event.seq), data: event });

@Controller("jobs")
export class JobsController {
  constructor(
    private readonly events: JobEventsService,
    private readonly store: JobStore,
  ) {}

  @Sse(":id/events")
  stream(@Param("id") id: string): Observable<MessageEvent> {
    const job = this.store.get(id);
    if (!job) throw new NotFoundException(`No job ${id}`);

    // Finished before the client connected: send the terminal frame and stop.
    if (job.last && job.last.type !== "progress") return of(toMessage(job.last));

    const events$ = this.events.stream(id).pipe(map(toMessage), share());
    const done$ = events$.pipe(ignoreElements(), endWith(null));
    // A comment frame (": ping") keeps proxies from reaping the idle socket.
    const heartbeat$ = interval(HEARTBEAT_MS).pipe(
      map((): MessageEvent => ({ comment: "ping" })),
      takeUntil(done$),
    );
    return merge(events$, heartbeat$);
  }
}

JobStore is wherever you keep job state. Snagbox keeps its download records in Postgres through Prisma. I ran this exact controller and checked each branch with curl:

An unknown id returns a normal 404 JSON response. Throwing before you return the Observable works, because Nest hasn't sent the stream headers yet. Under the spec, a non-200 response makes EventSource give up rather than retry, which is what you want for a job that doesn't exist.
A finished job returns one complete frame and ends.
A running job streams frames with id: 6, id: 7 and so on, matching the job's own sequence number, with : ping comments in between.

Why set the id yourself

If a message has no id, Nest 12.1.3 adds one: a counter that starts at 1 on each connection. I tested what that means for reconnects in headless Chrome. The browser reconnected and sent Last-Event-ID: 3, and the new connection numbered its frames from 1 again. The header is there, but it no longer means anything.

Using the job's sequence number as the id fixes that. On reconnect, read the header with @Headers("last-event-id") and skip events the client has already seen. For progress, the ReplaySubject already sends the latest state, so you can often ignore the header and still be correct.

The heartbeat: a comment, not a data frame

Snagbox merges a heartbeat into the stream every 15 seconds. The comment in its source says why: proxies reap idle connections, and the Next.js rewrite proxy in front of the API is one of them. takeUntil(done$) stops the timer when the job ends, so the heartbeat never holds a finished stream open.

Snagbox sends the heartbeat as data: {"type":"ping"} and every client has to ignore it. On Nest 12.1.3 you can return { comment: "ping" } instead. Nest writes it as : ping, gives it no id, and EventSource doesn't fire any event for it. I confirmed both in the curl output and in Chrome.

The share() matters too. Both merge and done$ subscribe to events$, and share() makes them use one subscription to the job channel instead of two.

The client: close the EventSource when the job ends

This is the mistake I'd most expect to reach production. When the job finishes, the Observable completes and Nest ends the response. To EventSource, an ended response is a dropped connection, so it waits for the retry delay and connects again.

I tested this with an endpoint that sent three events and completed, with retry: 300. In 1.6 seconds Chrome received the same three events three times, plus the first event of a fourth run. For a progress bar that means flicker and wasted requests. For "show a toast when the download is ready", it means the toast fires again and again.

The fix is on the client: treat the terminal event as the end.

type JobEvent =
  | { type: "progress"; seq: number; percentage: number }
  | { type: "complete"; seq: number; url: string }
  | { type: "error"; seq: number; message: string };

export function watchJob(jobId: string, onEvent: (event: JobEvent) => void) {
  const source = new EventSource(`/api/jobs/${jobId}/events`, { withCredentials: true });

  source.onmessage = (message) => {
    const event = JSON.parse(message.data) as JobEvent;
    onEvent(event);
    if (event.type === "complete" || event.type === "error") source.close();
  };

  // Network blips are retried by the browser. A 404 or 401 closes the stream.
  source.onerror = () => {
    if (source.readyState === EventSource.CLOSED) onEvent({ type: "error", seq: -1, message: "stream closed" });
  };

  return () => source.close();
}

Two more things I checked in Chrome:

Named events skip onmessage. If you set type: "progress" on the Nest MessageEvent, the frame goes out as event: progress, and only addEventListener("progress", ...) receives it. In my test, onmessage got the unnamed frame and missed the named one. Either put the type inside data, as above, or add a listener for every event name you send.
EventSource can't send custom headers. The constructor takes a URL and a withCredentials flag, nothing else. If your API uses an X-API-Key or a bearer token, use a cookie session for the browser, a short-lived signed token in the query string, or fetch() with a streamed response body and your own frame parser.

Don't open one stream per item: the six-connection limit

Over HTTP/1.1, browsers allow only six connections per host, and each open EventSource holds one for as long as it lives. Snagbox's controller has a comment about this: batch downloads poll GET /v2/downloads?ids=... instead of opening one stream per job, because "a 50-item batch would stall on its own event streams".

I measured how bad it is. A page in headless Chrome 155 opened 8 EventSources to my local Nest server over plain HTTP/1.1. Six opened within 5 ms. The other two never opened during the 3-second window. Then the page made an ordinary fetch() to the same server, and it was still pending after 5 seconds. Six progress streams can freeze the rest of your app's API calls on that host.

You have three ways out:

Serve over HTTP/2. All requests share one connection, and the limit becomes the number of concurrent streams the server allows. MDN's EventSource page notes that this defaults to 100. If a proxy or CDN in front of your API already speaks HTTP/2 to the browser, you may have this for free.
Multiplex. Open one stream per user or per batch and include the job id in every event.
Poll a batch endpoint for many items. This is what Snagbox does for playlists:

@Get()
getMany(@Query("ids") ids = "") {
  return ids
    .split(",")
    .map((id) => id.trim())
    .filter(Boolean)
    .slice(0, 100)
    .map((id) => this.store.get(id) ?? { id, status: "unknown" });
}

One request every second or two for a 50-item batch costs far less than 50 streams, and it can't block anything.

SSE vs polling: what one job costs

I ran one simulated job that lasted 10 seconds and emitted 40 progress updates, one every 250 ms. A Node.js client watched it three ways, and I counted the bytes from the socket itself (socket.bytesRead and socket.bytesWritten), so HTTP headers are included. The client and server ran on the same box, over localhost, with the Express adapter.

Transport	Requests	Updates seen	Bytes down	Bytes up	Total
SSE, one stream	1	40 of 40	4,437	79	4,516
Polling every 1 s	11	10 of 40	3,525	913	4,438
Polling every 250 ms	41	40 of 40	13,144	3,362	16,506

Polling once a second used about the same bytes as SSE but showed only a quarter of the updates, so the bar moves in jumps and can show a value up to a second old. Polling fast enough to see every update took 41 requests and 3.7 times the bytes. SSE delivered each update 0.8 ms after the server emitted it on average, with a 2 ms maximum.

Each SSE update cost about 110 bytes, which is mostly the JSON. Each polled response carried around 320 bytes, because every one repeats the HTTP headers. With API-key auth, a rate limiter and logging on every request, the request count matters more than the bytes.

How much memory does an open SSE stream use?

An open stream is a socket, a response object and an RxJS subscription. I opened 1,000 and then 5,000 more concurrent streams against the same job and read the server's resident memory from /proc/<pid>/status. The client ran in a separate process.

Open streams	Server RSS before	RSS after	Per stream
1,000	75.8 MB	138.0 MB	about 64 KB
5,000	138.7 MB	305.8 MB	about 34 KB

The per-stream figure fell at the larger count, probably because the first batch also paid one-off costs as the heap grew (RSS didn't shrink between the runs). Treat it as a rough range for Nest on Express and Node 22, not a constant. It does show that one instance can hold thousands of idle progress streams. Your file-descriptor limit (ulimit -n) and proxy timeouts are more likely to stop you first.

I also counted live subscriptions in the service. With 5,000 streams open, the count was 5,000. 1.5 seconds after the clients disconnected, it was 0. Nest unsubscribes from your Observable when the client goes away, so the RxJS teardown runs and the subject doesn't leak subscribers.

If your handler does async setup before it returns the Observable, such as opening a database cursor or an LLM session, Nest 12.1.3 also has an @SseSignal() parameter decorator. It injects an AbortSignal that fires when the stream ends, so you can release setup resources even if the client left before the Observable existed.

A smooth progress bar: never let it go backwards

One Snagbox detail isn't about SSE but shows up in every progress UI. Snagbox runs yt-dlp, which downloads video and audio as two separate passes and reports each from 0 to 100%. Forwarded as-is, the bar fills, snaps back to zero and fills again.

Snagbox's ProgressAggregator fixes this. When downloaded bytes drop, it banks the finished pass. It keeps the percentage monotonic and caps it at 99.9 while the process is alive, because the last pass finishing isn't the job finishing, since the merge still has to run. Only the complete event reports 100%. If your job has more than one phase, do the same before anything reaches the stream.

How I tested

Box: Linux, 8 vCPUs, shared with other workloads. Node.js 22.20.0, @nestjs/core 12.1.3 on @nestjs/platform-express 12.1.3, RxJS 7.8.2, TypeScript 5.9, compiled to ESM.
Jobs were simulated with setInterval, so the tests measure the transport and Nest, not a real download.
Bytes came from the client socket's counters, with keep-alive for the polling client.
The late-joiner test ran five times per subject type, joining 5.0 to 5.5 s into a job that emitted every 2 s.
Browser tests used puppeteer-core driving Chrome 155 headless, against http://127.0.0.1 over HTTP/1.1.
Memory is VmRSS of the Nest process, read before opening streams and 4 seconds after the last one opened.

These are single-machine, localhost numbers. Over a real network, polling gets worse, because each request pays the round trip, while SSE pays it once.

Common mistakes with NestJS SSE

Not closing the EventSource on the terminal event. The browser reconnects and replays the job.
Relying on Nest's automatic ids. They restart at 1 on every connection. Use your own sequence.
Sending type on the MessageEvent and listening with onmessage. Named events only reach addEventListener.
Using a plain Subject. Late clients wait for the next update. Use ReplaySubject(1).
One stream per list item over HTTP/1.1. Six streams block the host. Poll a batch endpoint or use HTTP/2.
No heartbeat behind a proxy. Idle streams get cut. Send a comment frame every 15 to 30 seconds.
Putting the API key in a header the browser can't send. EventSource has no headers option.
Keeping job channels forever. Delete them a few minutes after the terminal event, as Snagbox does.

For the queue side of long-running work, read Building an AI automation pipeline in Node.js with BullMQ. If you're on an older Nest version, the NestJS 12 migration guide covers the upgrade. For a secure API base to put this in, see my NestJS + Prisma API starter.

Key takeaways

NestJS streams SSE from any @Sse() route that returns an Observable, and sets text/event-stream, no-cache and X-Accel-Buffering: no for you.
A ReplaySubject(1) per job gave late clients their first frame in 2 to 4 ms, against up to 1,002 ms with a plain Subject.
Set id from your job's sequence number. Nest's automatic ids restart at 1 on every reconnect.
Close the EventSource on the terminal event. A completed stream made Chrome reconnect and replay it three times in 1.6 s.
Send heartbeats as { comment: "ping" }, which the browser ignores and Nest leaves without an id.
Over HTTP/1.1, Chrome opened 6 of 8 streams and then stalled a normal fetch(). Use HTTP/2, one multiplexed stream, or a batch polling endpoint.
For one 10-second job, SSE used 1 request and 4,516 bytes. Polling every 250 ms needed 41 requests and 16,506 bytes for the same updates.

Originally published on fabwaseem.com, where I write about Node.js, NestJS, Next.js and AI automation.

Prisma 8 vs Prisma 7: Should You Upgrade? A Tested Migration Guide

Waseem Anjum — Sun, 18 Oct 2026 18:52:09 +0000

Heads up if any of your projects, CI jobs or Dockerfiles run npm install prisma without a version pin: since August 2026 that installs a Prisma 8 release candidate. I migrated a Prisma 7 app on PostgreSQL 17 side by side, and this is what I found.

Prisma 8 is a rewrite of Prisma ORM, not a version bump. The schema becomes a contract, prisma generate becomes prisma contract emit, @prisma/client is replaced by @prisma/orm-postgres, and queries are chained (db.orm.public.User.where(...).all()). It is still a release candidate, but since August 2026 npm install prisma installs it.

That last fact is the urgent part. Any Prisma 7 project, CI job or Dockerfile that installs prisma without a version now gets a CLI with no generate, migrate or db push. I upgraded a real Prisma 7 app on PostgreSQL 17 with the official side-by-side path, and this guide gives the commands, the output, two gotchas the docs don't spell out, and a clear answer on whether to move now. Facts are cited to the Prisma ORM release status page.

What is Prisma 8?

Prisma 8 (Prisma ORM 8) is the next major version of Prisma ORM, a typed data layer for TypeScript. You describe models in a contract file, prisma contract emit writes contract.json and contract.d.ts, and you query through a db client from @prisma/orm-postgres. There is no generated PrismaClient, and migrations are TypeScript files you can review.

Key facts on October 17, 2026:

	Prisma ORM 7	Prisma ORM 8
npm tag	`prisma@prev` (7.10.1)	`prisma@latest` (8.0.0-rc.23)
Status	Stable, supported	Release candidate, GA "expected in October 2026"
Runtime package	`@prisma/client` + a driver adapter	`@prisma/orm-postgres` (8.0.0-rc.18)
Schema file	`schema.prisma`	`contract.prisma` (first line `// use prisma-8`)
Codegen	`prisma generate`	`prisma contract emit`
Queries	`prisma.user.findMany({ where })`	`db.orm.public.User.where(...).all()`
Migrations	`migrate dev` / `migrate deploy` (SQL)	`migration plan` / `db migrate` (TypeScript)
Databases	PostgreSQL, MySQL, SQL Server, SQLite, MongoDB, CockroachDB	PostgreSQL; MongoDB early access; SQLite experimental
Node.js	20.19+, 22.12+ or 24+	22.18+, 24.11+ or 26+
TypeScript	5.4+	5.9+

The CLI and the library are versioned separately, so prisma 8.0.0-rc.23 and @prisma/orm-postgres 8.0.0-rc.18 are a matching pair. Prisma says "any two latest versions work together."

Is Prisma 8 stable? When is the release date?

No, not yet. Prisma 8 is a release candidate, and Prisma's release status page says general availability "is expected in October 2026." On October 17, 2026 the newest builds were prisma 8.0.0-rc.23 (published October 15) and @prisma/orm-postgres 8.0.0-rc.18 (October 14). Prisma warns that "some details of the API may still change."

Two support dates follow from the release:

Prisma ORM 7 keeps receiving bug fixes and security updates "for 18 months from the day Prisma ORM 8 reaches general availability."
Prisma ORM 6 receives security patches only until November 19, 2026.

So there is no rush to leave Prisma 7, but Prisma 6 projects should move to 7 now.

Why does `npm install prisma` install Prisma 8?

Because Prisma moved the npm latest tag to Prisma 8 while it is still an RC. Prisma's August 28 changelog says the release "makes Prisma 8 available through prisma@latest." Prisma 7 is now prisma@prev. A Prisma 7 project that installs prisma without a version range gets a CLI that cannot read its workflow.

I ran the old commands with the Prisma 8 CLI in a Prisma 7 project:

$ npx prisma generate
✘ [CLI.UNKNOWN_COMMAND] No command registered for `generate`
$ npx prisma migrate deploy
✘ [CLI.UNKNOWN_COMMAND] No command registered for `migrate`, did you mean `migration`?
$ npx prisma db push
✘ [CLI.UNKNOWN_COMMAND] No command registered for `push`, did you mean `update`?

Do this today, even if you never upgrade: pin both packages, then grep your CI, Dockerfiles and scripts for npx prisma and prisma@latest.

{
  "devDependencies": { "prisma": "^7" },
  "dependencies": { "@prisma/client": "^7" }
}

Anywhere a command runs without a lockfile, write npx prisma@7 migrate deploy instead of npx prisma migrate deploy. If you build images with a multi-stage Dockerfile like the one in my Next.js Dockerfile guide, the npm ci step respects the lockfile; a separate npx prisma ... line in a later stage does not.

What changed in Prisma 8?

Almost everything you type. The schema is a contract, codegen is contract emit, the client is built in src/prisma/db.ts, queries are chained, migrations are TypeScript packages tracked by a hash marker in the database, and several Prisma 7 features ($extends, nested updates, increment, JSON filters, P2002 codes) are missing. Your database tables and data do not change.

Commands

Prisma 7	Prisma 8
`prisma generate`	`prisma contract emit`
`prisma migrate dev`	`prisma db update`, or `prisma migration plan` + `prisma db migrate`
`prisma migrate deploy`	`prisma db migrate`
`prisma db push`	`prisma db init` (empty database), then `prisma db update`
`prisma db pull`	`prisma contract infer`
`prisma format`	`prisma contract format`
`prisma migrate reset`, `prisma db seed`, `prisma studio`	None in the Prisma 8 CLI

Queries

Prisma 7	Prisma 8
`prisma.user.findMany({ where: { active: true } })`	`db.orm.public.User.where({ active: true }).all()`
`findUnique` / `findFirst`	`.where(...).first()` (returns `null`)
`select: { id: true }`	`.select("id")`
`include: { posts: true }`	`.include("posts")`
`orderBy: { id: "asc" }`	`.orderBy((u) => u.id.asc())`
`take` / `skip`	`.limit(n)` / `.offset(n)`
`create({ data: {...} })`	`.create({...})` (no `data` wrapper)
`contains: "ali"` / `mode: "insensitive"`	`.like("%ali%")` / `.ilike("%ali%")`
`$transaction(async (tx) => ...)`	`db.transaction(async (tx) => ...)` with `tx.orm`
`$disconnect()`	`db.close()`

public is the PostgreSQL schema the table lives in. The full mapping is in Prisma's Coming from Prisma ORM 7 reference.

Schema types

In a hand-written contract, @db. attributes become the field type (String @db.VarChar(255) is VarChar(255)), Json must be written Jsonb, @updatedAt is temporal.updatedAt(), cuid() is cuid(2), and implicit many-to-many relations need an explicit join model. DateTime values come back as Temporal.Instant, which Node.js 22 and 24 do not have built in. On my Node.js 24.22.0, node -p "typeof Temporal" printed undefined, so a hand-written contract needs temporal-polyfill.

What is missing in Prisma 8?

Prisma 8 does not yet have several Prisma 7 features. The release status page lists $extends, "filtering inside JSON columns, atomic increment, most nested writes, transaction isolation levels, and the P2002-style error codes." $extends will not return; middleware, custom collections and scopes replace it. If your app relies on these, stay on Prisma 7 for now.

Prisma 7 feature	In Prisma 8
`$extends`	Will not be added. Use middleware, `Collection` subclasses or scopes
`{ increment: 1 }`	Not available. Use raw SQL or read and write in a transaction
JSON path filters	Not available. `Jsonb` compares as a whole; use raw SQL
`connectOrCreate`, nested `update`/`upsert`/`delete`, `set`	Not available. Only nested `create`, `connect`, `disconnect`
`isolationLevel`, `timeout`, nested transactions	Not available
`P2002` / `P2025` error codes	Use `error.sqlState` (`23505` = unique violation) or codes like `RUNTIME.NO_ROWS`
`omit`, `relationLoadStrategy`, TypedSQL, read replicas	Not available
`has` / `hasSome` on `String[]`	Not available. The field works; filter with raw SQL
MySQL, SQL Server, CockroachDB	Not yet. Stay on Prisma 7

I replaced an increment with the documented raw SQL builder, and it ran on 8.0.0-rc.18:

import { db } from "./prisma/db.ts";

const post = db.sql.public.Post;
const bump = db.raw.sql`UPDATE "Post" SET views = views + 1 WHERE id = ${id} RETURNING id, views`
  .returnsRow({ id: post.columns.id, views: post.columns.views })
  .build();

const rows = await db.runtime().query(bump); // [ { id: 1, views: 3 } ]

How do I migrate from Prisma 7 to Prisma 8?

Run both versions side by side on the same database. One command (npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma) renames Prisma 7 to prisma7, installs Prisma 8, and lets it read your existing schema.prisma. You then sign the database, move routes one at a time, and hand migrations to Prisma 8 only when you choose.

This is the path from Prisma's official Prisma ORM 7 to 8 guide, and the prisma8-and-7-example repo shows each phase. My test app was a Hono API on Prisma 7.10.1 with @prisma/adapter-pg, PostgreSQL 17.11, Node.js 24.22.0, a Role enum, a DateTime @default(now()), a Json? column and an increment update.

Step 1: Run orm init

npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma

Write prisma@latest in full, because inside a Prisma 7 project npx prisma still runs version 7. In CI or from a coding agent, the command stops and asks for consent:

CLI.CONSENT_REQUIRED: "Prisma 7 is installed as `prisma`. Keep it as @prisma/prisma7
(binary prisma7) and move `prisma` to Prisma 8, and rename prisma.config.ts to
prisma7.config.ts?" requires explicit consent, and the session is not interactive.
Grant it by passing --confirm app.

Note that it had already added @prisma/orm-postgres to package.json before it stopped. With --confirm app it finished and changed exactly this:

   "dependencies": {
     "@prisma/adapter-pg": "^7.10.1",
     "@prisma/client": "^7.10.1",
+    "@prisma/orm-postgres": "^8.0.0-rc.18",
   },
   "devDependencies": {
+    "@prisma/cli-engine": "^0.7.0",
+    "@prisma/prisma7": "^7.10.1",
-    "prisma": "^7.10.1",
+    "prisma": "^8.0.0-rc.23",
   }

It renamed prisma.config.ts to prisma7.config.ts (now importing @prisma/prisma7/config), wrote a new prisma.config.ts, and emitted the client into src/prisma/:

// prisma.config.ts (written by orm init)
import "dotenv/config";
import { definePrismaConfig } from "@prisma/cli-engine";
import { defineConfig as ormConfig, prisma7Schema } from "@prisma/orm-postgres/config";

export default definePrismaConfig({
  orm: ormConfig({
    contract: prisma7Schema("prisma/schema.prisma"),
    output: "src/prisma",
    db: { connection: process.env["DATABASE_URL"]! },
  }),
});

npx prisma --version now reports 8.0.0-rc.23, and npx prisma7 generate still writes the Prisma 7 client. Update every script and CI step that must keep using Prisma 7 to call prisma7.

Step 2: Sign the database

$ npx prisma db sign
✔ app: signed b3b45c6c5fd8… (no marker before)
✔ Database signed
✔ Advanced ref "db" → b3b45c6c5fd8…

$ npx prisma db verify
✔ Database marker and schema match contract

db sign changes no tables. It adds a prisma_contract.marker table that records which contract hash the database satisfies. Prisma 7 still owns migrations, so after every prisma7 migrate dev or prisma7 migrate deploy, run npx prisma contract emit and npx prisma db sign again.

Step 3: Move one route

// src/routes/users.ts — now on Prisma 8
import { db } from "../prisma/db.ts";

users.get("/", async (c) => {
  const result = await db.orm.public.User.include("posts", (posts) =>
    posts.orderBy((post) => post.id.asc()),
  )
    .orderBy((user) => user.id.asc())
    .all();
  return c.json(result);
});

users.post("/", async (c) => {
  const body = await c.req.json<{ email: string; name?: string }>();
  try {
    return c.json(await db.orm.public.User.create(body), 201);
  } catch (error) {
    // No P2002 in Prisma 8: check the PostgreSQL SQL state instead
    if (error instanceof Error && "sqlState" in error && error.sqlState === "23505") {
      return c.json({ error: "email already exists" }, 409);
    }
    throw error;
  }
});

The posts route stayed on Prisma 7, including its increment. A post written through Prisma 7 appeared in the next Prisma 8 read, and a duplicate email returned my 409. tsc --noEmit passed on TypeScript 6.0.3 and, as a bonus, on TypeScript 7 7.0.2.

Step 4: Hand migrations to Prisma 8

When you are ready, convert the Prisma 7 schema into a real contract, point the config at it, sign, then plan a change:

npx prisma contract print --output prisma8/contract.prisma
# set contract: "prisma8/contract.prisma" in prisma.config.ts
npx prisma contract emit
npx prisma db sign

The printed contract produced the same hash as the Prisma 7 schema (unchanged, already signed), so nothing drifted. It mapped my types like this:

// use prisma-8
namespace public {
  model User {
    id        Int                @id @default(autoincrement())
    email     String
    name      String?
    role      pg.enum(Role)      @default("USER")
    createdAt TimestampString(3) @default(now())
    posts     Post[]

    @@index([email], map: "User_email_key", unique: true)
  }

  native_enum Role {
    USER = "USER"
    ADMIN = "ADMIN"
  }
}

Then I added bio String? and ran the new migration loop:

$ npx prisma contract emit
$ npx prisma migration plan --name add_user_bio
→ Review migrations/app/20261017T1408_baseline and migrations/app/20261017T1409_add_user_bio
$ npx prisma db migrate --advance-ref db
✔ Applied 1 migration(s) (1 operation(s)) across 1 contract space(s)
├─ Add column "bio" to "User"
$ npx prisma db verify
✔ Database marker and schema match contract

The first plan writes a baseline (the schema Prisma 7 built) plus your change. db migrate skips the baseline because the marker already records it. Each migration is a reviewable migration.ts:

override get operations() {
  return [
    this.addColumn({
      schema: "public",
      table: "User",
      column: col("bio", "text", { codecRef: { codecId: "pg/text@1" } }),
    }),
  ];
}

The Prisma 7 routes kept working after the new column. From here, retire prisma7 migrate from your scripts, move the remaining routes, and finally remove @prisma/prisma7, @prisma/client and @prisma/adapter-pg.

What broke when I ran Prisma 7 and 8 side by side?

Two things the guide doesn't warn about. First, orm init needs --confirm app in any non-interactive shell (CI, Docker, coding agents). Second, createdAt timestamps written by Prisma 8 were 5 hours off. Prisma 7 fills @default(now()) in the client in UTC, but Prisma 8 leaves it to the database, which used my server's local time zone.

The evidence, from the same User table:

id | createdAt                 written by
 1 | 2026-10-17 14:06:44.701   Prisma 7 (UTC)
 2 | 2026-10-17 19:08:52.282   Prisma 8 (server time zone Asia/Karachi, UTC+5)
 4 | 2026-10-17 14:09:08.795   Prisma 7 (UTC)

Prisma 7 created the column as TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, which is timestamp without time zone. Prisma's own mapping table says @default(now()) in Prisma 8 "is a database default." For a timestamp column, PostgreSQL then writes the time in the session's TimeZone setting, which defaults to the server's. After ALTER DATABASE p8demo SET timezone TO 'UTC', Prisma 8 wrote 14:09:20 at 14:09:20 UTC.

Many managed PostgreSQL services default to UTC, so you may never see this. Check before mixing writers:

SHOW timezone;  -- must be UTC (or Etc/UTC) while Prisma 7 and 8 both write

Also note the data type change: read through prisma7Schema(...), DateTime comes back as a string such as "2026-10-17 14:06:44.701", not a Date. My JSON responses changed format between the two routes (2026-10-17T14:06:44.701Z from Prisma 7), so API clients that parse dates should be tested.

Should I upgrade to Prisma 8 now?

Not for production apps yet. Pin Prisma 7 today, because that protects you from the latest tag change, and plan the move after GA. Start with Prisma 8 now only for new PostgreSQL projects that don't need the missing features, or to trial it on one route of an existing app with the side-by-side setup.

Your situation	Recommendation
Prisma 6	Upgrade to Prisma 7 before November 19, 2026
Prisma 7 on MySQL, SQL Server or CockroachDB	Stay on 7; Prisma 8 doesn't support them yet
Prisma 7 using `$extends`, nested updates, JSON filters or `P2002`	Stay on 7 until those have replacements you accept
Prisma 7 on PostgreSQL, simple CRUD	Pin 7 now; trial 8 on one route after GA
New PostgreSQL project	Prisma 8 is reasonable; expect small API edits until GA
Using Accelerate	Switch connections before December 1, 2026 regardless

What happens to Prisma Accelerate?

Prisma retires Accelerate on December 1, 2026, according to its October 2 changelog. If your connection string starts with prisma+postgres://accelerate.prisma-data.net, switch to a pooled connection or the serverless driver before then. Accelerate's query caching has no replacement, so remove cacheStrategy from your queries first.

The same changelog sets a second deadline: Prisma Postgres Early Access databases, the ones still on PostgreSQL 16, "are deleted on November 1, 2026 at 00:00 UTC." Move each one to a new database before then. Both deadlines apply whether you stay on Prisma 7 or move to 8.

Prisma 8 upgrade checklist

Pin Prisma 7 first, then handle the deadlines, then migrate on your own schedule. These steps follow the official guide plus what I hit in testing.

Pin prisma and @prisma/client to ^7 and replace every unpinned npx prisma in CI and Dockerfiles with npx prisma@7 or a lockfile install.
Leave Accelerate before December 1, 2026, and move Early Access Prisma Postgres databases before November 1.
Check requirements: Node.js 22.18+, 24.11+ or 26+, TypeScript 5.9+ with strict, PostgreSQL.
Audit for missing features: $extends, increment, nested updates, JSON filters, isolation levels, P2002 handling.
Check the database time zone with SHOW timezone; and set it to UTC if Prisma 7 and 8 will both write.
Run npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma (add --confirm app in CI).
Run npx prisma db sign, then move one low-risk route to db.orm.
After each prisma7 migration, run prisma contract emit and prisma db sign.
Transfer migrations with contract print, db sign, migration plan, db migrate --advance-ref db.
Remove Prisma 7 when nothing imports @prisma/client.

Common Prisma 8 mistakes

The most common mistakes are letting prisma@latest slip into a Prisma 7 build, running Prisma 8's db init or db update against a database Prisma 7 already manages, forgetting to re-sign after a Prisma 7 migration, and assuming DateTime and error handling behave the same in both clients.

Mistake	Symptom	Fix
Unpinned `prisma` in CI	`No command registered for generate`	Pin `^7` or use `npx prisma@7`
`orm init` in CI without consent	`CLI.CONSENT_REQUIRED`	Add `--confirm app`
`db init` / `db update` on a Prisma 7 database	Skips the signed handoff; the guide says to run neither	`db sign`, then the phase 4 handoff
Not re-signing after `prisma7 migrate`	`db verify` reports a contract mismatch	`contract emit`, then `db sign`
Catching `P2002` in moved routes	Unique violations crash as 500s	Check `error.sqlState === "23505"`
Server time zone not UTC	Prisma 8 timestamps offset by hours	`ALTER DATABASE ... SET timezone TO 'UTC'`
Expecting `Date` objects	Strings or `Temporal.Instant` instead	Convert at the API boundary
Hand-written contract on Node.js 24	`Temporal` is undefined	`import "temporal-polyfill/full/global"`

Related: I benchmarked Prisma 8 RC against Prisma 7 and Drizzle in Drizzle vs Prisma in 2026: Prisma 8 RC had the slowest bundled cold start (about 370 ms). If you use Better Auth, note that Better Auth 1.7 supports Prisma 5 to 7 but not Prisma 8 yet; see my Better Auth with Next.js 16 setup.

Related: Prisma's @default(uuid(7)) generates IDs in the client and sets no database default. On PostgreSQL 18 you can use dbgenerated("uuidv7()") instead; see my UUIDv7 in PostgreSQL 18 benchmark.

Key takeaways

Prisma 8 is a release candidate (prisma 8.0.0-rc.23, @prisma/orm-postgres 8.0.0-rc.18 on October 17, 2026) with GA expected in October 2026, but npm's latest tag already installs it.
Pin prisma and @prisma/client to ^7 today; the Prisma 8 CLI has no generate, migrate or db push.
Prisma 8 replaces schema.prisma with a contract, prisma generate with prisma contract emit, and @prisma/client with @prisma/orm-postgres and chained queries.
$extends, increment, most nested writes, JSON filters, isolation levels and P2002 codes are missing, and only PostgreSQL is fully supported.
orm init --from-prisma7-schema runs Prisma 7 and 8 side by side on one database; it needs --confirm app outside an interactive terminal.
Check SHOW timezone before mixing writers: Prisma 8 leaves now() to the database, which skewed my timestamps by 5 hours.
Prisma 7 is supported for 18 months after Prisma 8 GA, Prisma 6 security patches end November 19, 2026, and Accelerate retires December 1, 2026.

Originally published on fabwaseem.com.

TypeScript 7 Upgrade Guide: What Breaks, ESLint, Next.js and Real Benchmarks

Waseem Anjum — Sun, 18 Oct 2026 18:51:06 +0000

I tested the TypeScript 7 upgrade and ran into three catches that are easy to miss: removed tsconfig options, a typescript-eslint break, and a side-by-side setup that changes which compiler next build uses. Here is the full guide with the exact errors and fixes.

TypeScript 7 is the native, Go-based rewrite of the TypeScript compiler, and it has been the latest version on npm since July 8, 2026. It type-checks the same code as TypeScript 6 but much faster. On this box Hono's source built 5.2x faster (3.01 s to 0.58 s), with identical JavaScript output.

The upgrade is usually one npm install, with three real catches. Every option deprecated in TypeScript 6 is now a hard error. TypeScript 7 has no programmatic API, so typescript-eslint refuses to run. And the side-by-side workaround quietly changes which compiler next build uses. I hit all three while testing, so this guide gives the exact errors and fixes, cited to the official TypeScript 7 announcement.

What is TypeScript 7?

TypeScript 7 is a faithful port of the TypeScript compiler and language service from TypeScript to Go. It ships as the normal typescript npm package with the same tsc command. Microsoft says it "typically" yields "speedups between 8x and 12x on full builds" through native code and shared-memory multithreading. The type system and emitted JavaScript match TypeScript 6.0.

Key facts at a glance:

	TypeScript 6.0	TypeScript 7.0
Written in	TypeScript (runs on Node.js)	Go (native binary, multithreaded)
npm package	`typescript@6` / `@typescript/typescript6`	`typescript@7` (`latest`, 7.0.2)
Type checking	Reference behavior	Same semantics, with `stableTypeOrdering` always on
Deprecated options	Error, silenced by `ignoreDeprecations: "6.0"`	Hard error, cannot be silenced
Programmatic API	Yes (`ts.createProgram`, ...)	None yet; planned for 7.1
Editor	Built-in TS server	LSP server, VS Code extension

The announcement adds that "practically any TypeScript code that compiles cleanly with TypeScript 6.0 (with the stableTypeOrdering flag on, and without any ignoreDeprecations flag set) should compile identically in TypeScript 7.0."

Is TypeScript 7 stable and ready for production?

Yes, for compiling and type-checking. TypeScript 7.0 is a stable release, and the team tested it with companies including Bloomberg, Canva, Figma, Google, Linear, Notion, Sentry, Slack and Vercel. It is not ready for tools that need the compiler API, such as typescript-eslint and Vue, Svelte, Astro or MDX tooling, until TypeScript 7.1 ships a new API.

Quotable results from the announcement:

Slack's CI type-checking went "from about 7.5 minutes to 1.25 minutes."
The new language server "reduced failing language server commands by over 80%, and reduced server crashes by over 60%" compared with 6.0.
Opening a file with an error in the VS Code codebase dropped from about 17.5 seconds to under 1.3 seconds.

The TypeScript 7.1 iteration plan lists "Stabilize API" as its first item. It scheduled the 7.1 beta for October 6 and the stable release for November 24, 2026. On October 17, 2026 npm still had no 7.1 beta, only nightly 7.1.0-dev builds under the next tag, so treat the date as a target.

How much faster is TypeScript 7? (my benchmark)

On an 8-vCPU Linux box, TypeScript 7.0.2 built Hono's source (189 files, about 26,000 lines, declarations plus JavaScript) in a median 0.58 seconds, against 3.01 seconds for TypeScript 6.0.3. That is a 5.2x speedup with 27% less peak memory. Both compilers emitted byte-identical JavaScript for all 188 output files.

The run: tsc -p tsconfig.build.json on Hono at commit 5ca49b0, three runs each, Node.js 24.22.0, measured with os.wait4 for wall time and peak RSS.

Compiler	Median	Runs	Peak memory
TypeScript 6.0.3	3.01 s	2.85, 3.01, 3.08	528 MB
TypeScript 7.0.2 (default, 4 checkers)	0.58 s	0.58, 0.50, 0.59	383 MB
TypeScript 7.0.2 `--checkers 8`	0.61 s	0.61, 0.60, 0.62	416 MB
TypeScript 7.0.2 `--singleThreaded`	0.98 s	0.98, 1.03, 0.89	250 MB

My 5.2x is below Microsoft's 8x to 12x because this project is small. Startup time weighs more on a 3-second build than on VS Code's 125-second one, so expect larger gains on larger codebases. Two things surprised me:

More checkers didn't help here. --checkers 8 was no faster than the default of 4 and used more memory. The announcement says extra checkers help "larger codebases" at "the cost of increased memory usage."
Even single-threaded, TypeScript 7 was 3x faster and used half the memory. On small CI runners --singleThreaded or --checkers 1 is a reasonable choice.

Does TypeScript 7 emit the same output?

The JavaScript was identical. The .d.ts files were not: 25 of 188 declaration files differed. In 16 the only change was quote style ('/' instead of "/"). In 9, TypeScript 7 wrote a reference such as toArray: typeof toArray where TypeScript 6 had inlined the full function type:

-    toArray: (children: Child) => Child[];
+    toArray: typeof toArray;

These are equivalent types, but if you publish a library, diff your generated declarations or run your API report tool before releasing a version built with TypeScript 7.

What breaks when upgrading to TypeScript 7?

Three things break most often. Every compiler option deprecated in TypeScript 6.0 is now a hard error that ignoreDeprecations no longer silences. The new defaults (types: [], rootDir: "./", strict: true) surface errors in existing configs. And any tool that imports the typescript API fails, because 7.0 ships without one.

Removed tsconfig options

I ran a deliberately old tsconfig.json through both compilers. TypeScript 6 already reports these as errors (TS5101/TS5107, "will stop functioning in TypeScript 7.0"), but you can silence them with "ignoreDeprecations": "6.0". TypeScript 7 reports TS5102/TS5108 and ignores that flag (with it set, 7.0.2 still exited 1):

tsconfig.json(3,15): error TS5108: Option 'target=ES5' has been removed. Please remove it from your configuration.
tsconfig.json(5,25): error TS5108: Option 'moduleResolution=node10' has been removed. Please remove it from your configuration.
tsconfig.json(6,5): error TS5102: Option 'baseUrl' has been removed. Please remove it from your configuration.
  Use '"paths": {"*": ["./*"]}' instead.
tsconfig.json(7,24): error TS5090: Non-relative paths are not allowed. Did you forget a leading './'?
tsconfig.json(8,5): error TS5102: Option 'downlevelIteration' has been removed. Please remove it from your configuration.
tsconfig.json(9,24): error TS5108: Option 'esModuleInterop=false' has been removed. Please remove it from your configuration.

The full list of removals and their replacements, from the announcement:

Removed in TypeScript 7	Use instead
`target: "es5"`, `downlevelIteration`	`es2015` or later (a bundler can down-level if you must)
`moduleResolution: "node"` / `"node10"` / `"classic"`	`"nodenext"` (Node) or `"bundler"` (Vite, Next.js, webpack)
`module: "amd"`, `"umd"`, `"systemjs"`, `"none"`	`"esnext"` or `"preserve"`
`baseUrl`	`paths` with `./`-relative entries
`esModuleInterop: false`, `allowSyntheticDefaultImports: false`	Remove (always on)
`alwaysStrict: false`	Remove (always on)
`module Foo {}` namespace syntax	`namespace Foo {}`
`import ... assert { type: "json" }`	`import ... with { type: "json" }`
`tsc file.ts` inside a folder with `tsconfig.json`	`tsc --ignoreConfig file.ts`

New defaults that cause errors

After removing those options, two TypeScript 6 defaults (which 7 keeps) produced new errors:

error TS5011: The common source directory of 'tsconfig.json' is './src'. The 'rootDir' setting must be
explicitly set to this or another path to adjust your output's file layout.

src/index.ts(2,19): error TS2591: Cannot find name 'process'. Do you need to install type definitions for node?
Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

rootDir now defaults to ./, and types now defaults to [], so @types/* packages are no longer included automatically. This is the config that compiled and ran on TypeScript 7.0.2:

{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "outDir": "dist",
    "rootDir": "./src",
    "types": ["node"]
  },
  "include": ["src"]
}

Other defaults to know: strict is true, module is esnext, noUncheckedSideEffectImports is true, and stableTypeOrdering is always on.

Language and JavaScript changes

Template literal inference now keeps Unicode code points whole. This compiles on TypeScript 7 and fails on 6, which also makes it a quick way to prove which compiler a tool is running:

// lib/which-ts.ts — compiles only on TypeScript 7
type HeadTail<S> = S extends `${infer Head}${infer Tail}` ? [Head, Tail] : never
export const check: HeadTail<'😀abc'> = ['😀', 'abc']

TypeScript 6 reports Type '"😀"' is not assignable to type '"�"', because it splits the emoji into two UTF-16 halves.

JSDoc-typed JavaScript is also stricter: @enum, @class, a bare ? type and Closure-style function(string): void are no longer recognized. The CHANGES.md file tracks the full list.

Does typescript-eslint work with TypeScript 7?

No. typescript-eslint 8.71.2 (the latest on October 17, 2026) declares typescript >=4.8.4 <6.1.0 as a peer dependency and throws at startup when it finds TypeScript 7. Because eslint-config-next uses it, npm run lint fails in every Next.js app that upgrades. The fix is to keep TypeScript 6 installed under the typescript name for the API.

This is the exact error from npx eslint . in a Next.js 16.4.2 app after npm i -D typescript@7.0.2:

typescript-eslint does not support TS 7.0.
Please see https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6.0 to run typescript-eslint using the TS 6 API.
See also https://github.com/typescript-eslint/typescript-eslint/issues/10940 for tracking typescript-eslint's support for TS >=7.1

Oops! Something went wrong! :(
ESLint: 9.39.5
Error: typescript-eslint does not support TS 7.0.

Support is tracked in typescript-eslint issue #10940 and depends on the 7.1 API.

How do I run TypeScript 7 and 6 side by side?

Install TypeScript 7 under an alias such as @typescript/native, and install @typescript/typescript6 under the typescript name. Tools that import typescript (ESLint, Vue, Svelte) get the 6.0 API, while npx tsc runs the TypeScript 7 binary. This is the setup the TypeScript team recommends in its announcement.

{
  "devDependencies": {
    "@typescript/native": "npm:typescript@^7.0.2",
    "typescript": "npm:@typescript/typescript6@^6.0.2"
  }
}

What I saw after npm install:

$ npx tsc -v
Version 7.0.2
$ npx tsc6 -v
Version 6.0.3
$ npx eslint .
(no output, exit 0)

The compatibility package ships a tsc6 binary, so the two never fight over the name tsc.

The catch: next build now uses TypeScript 6

With the alias setup, next build type-checks with TypeScript 6, not 7. Next.js resolves the package named typescript, finds the compatibility package and runs its tsc6. I proved it with the emoji file above: npx tsc passed, but next build failed with the TypeScript 6 error:

  Running TypeScript ...
lib/which-ts.ts(3,42): error TS2322: Type '"😀"' is not assignable to type '"�"'.
Failed to type check.

So pick one of two setups until typescript-eslint supports 7.1:

Setup	`next build` checks with	ESLint (type-aware)	Best for
A. `typescript@7` only	TypeScript 7 (fast)	Broken	Projects that lint with Biome or oxlint, or no type-aware lint
B. Alias: `typescript` = TS 6, `@typescript/native` = TS 7	TypeScript 6	Works	Projects on `eslint-config-next`

With setup B, add npx tsc --noEmit as its own CI step to get TypeScript 7's speed for type checking. Next.js's typescript.ignoreBuildErrors would skip the slower check in next build, but only use it if that tsc step blocks the merge, because the Next.js docs call that option "very dangerous" on its own.

Does Next.js support TypeScript 7?

Yes. Since Next.js 16.3, next build can type-check with TypeScript 7, and in 16.4 it uses the project's tsc CLI by default (experimental.useTypeScriptCli: true), which works without the compiler API. Install typescript@^7 and it is used automatically. In my test the "Running TypeScript" step dropped from 1,368 ms to 231 ms.

The Next.js 16.3 release post says: "To start using TypeScript 7 for type checking during next build, just bump your project's local dependency." The TypeScript config docs add the trade-off: CLI type checking "prints the native tsc diagnostics" and "does not apply Next.js-specific code frames," and it checks every file your tsconfig.json includes, test files too.

My measurements on the Next.js 16.4.2 app from my use cache guide:

	TypeScript 5.9.3 (create-next-app default)	TypeScript 7.0.2
`npx tsc --noEmit`	1.37 s	0.38 s
`next build` "Finished TypeScript in"	1,368 ms	231 ms
Real type error caught by `next build`	Yes	Yes (`TS2322`, build fails)

create-next-app 16.4.2 still writes "typescript": "^5" into new projects, so new apps start on 5.9 until you upgrade. The app's default tsconfig (moduleResolution: "bundler", no baseUrl) needed no changes for TypeScript 7.

TypeScript 7 upgrade checklist

To upgrade safely, get to TypeScript 6.0 with zero deprecation errors first, then install TypeScript 7, fix the types and rootDir defaults, decide how to keep the 6.0 API for ESLint and framework tooling, and add TypeScript 7 to CI. Library authors should also diff their generated .d.ts files before publishing.

Upgrade to TypeScript 6.0 and remove ignoreDeprecations. Fix every TS5101/TS5107 deprecation error; each becomes a hard TypeScript 7 error.
Replace baseUrl with ./-relative paths, and moduleResolution: "node" with "bundler" or "nodenext".
Install TypeScript 7: npm i -D typescript@^7 (or the alias setup if step 6 applies).
Add "types": ["node"] (plus jest, bun and so on) if globals like process stop resolving.
Set rootDir when tsconfig.json sits above src and you emit files.
Check API-dependent tools: typescript-eslint, eslint-config-next, Vue/Volar, Svelte, Astro, MDX, Angular templates. If you use any, keep typescript pointed at @typescript/typescript6.
Add npx tsc --noEmit to CI and check that it runs version 7 (npx tsc -v).
Tune parallelism: try --checkers 1 or --singleThreaded on small CI runners and higher --checkers on large monorepos, and measure.
Libraries: diff .d.ts output between 6 and 7 before publishing.
Editor: install the TypeScript 7 VS Code extension, and use "Disable TypeScript 7 Language Server" for Vue or Svelte projects.

Common TypeScript 7 upgrade mistakes

The most common mistakes are upgrading straight from 5.x without passing through 6.0's deprecation errors, assuming the alias setup makes next build use TypeScript 7, forgetting the new types: [] default, and trusting a passing build while lint is silently skipped. Each produces either a confusing error or a slower build than you expected.

Mistake	Symptom	Fix
Skipping TypeScript 6	Wall of `TS5102`/`TS5108` errors	Upgrade to 6.0 first and clear its deprecations
Keeping `ignoreDeprecations: "6.0"`	Still errors on 7	Remove it and fix the options
`typescript@7` with `eslint-config-next`	"typescript-eslint does not support TS 7.0"	Alias setup B
Alias setup but expecting fast `next build`	Build still uses `tsc6`	Run `npx tsc --noEmit` in CI as well
Relying on automatic `@types/*`	`Cannot find name 'process'` (TS2591)	`"types": ["node"]`
Upgrading a Vue, Svelte or Astro app's editor	Lost template type checking	Keep TypeScript 6 for the editor
Publishing a library without checking `.d.ts`	Different declaration text	Diff and review before release

If you deploy through Docker, rebuild without cache after changing the compiler. My Next.js Dockerfile guide shows a multi-stage build where npm run build, and with it the type check, runs in the builder stage.

Related: Prisma 8 needs TypeScript 5.9 or newer, and its client type-checked cleanly on TypeScript 7.0.2 in my test. See Prisma 8 vs Prisma 7: should you upgrade?

Related: on NestJS, TypeScript 7 isn't usable through the Nest CLI yet: nest build asks for TypeScript 6 until 7.1. Plain tsc 7 works. Details in my NestJS 12 migration guide.

Related: Oxlint's type-aware mode runs on typescript-go too. On this site's code it matched all 80 typescript-eslint findings in 1.29 s vs 20.5 s; details in Oxlint vs Biome vs ESLint.

Key takeaways

TypeScript 7 is the native Go port of TypeScript, latest on npm since July 8, 2026 (7.0.2), with the same type system as 6.0.
On Hono's source it built 5.2x faster than TypeScript 6 on my 8-vCPU box, with identical JavaScript output.
Everything deprecated in TypeScript 6 is a hard error in 7: es5, node10 resolution, baseUrl, AMD/UMD modules, esModuleInterop false.
New defaults bite: types is [] and rootDir is ./, so add "types": ["node"] and an explicit rootDir.
typescript-eslint does not support TypeScript 7; keep @typescript/typescript6 under the typescript name until 7.1 ships an API.
Next.js 16.3+ type-checks with TypeScript 7 automatically, but the alias setup makes next build use TypeScript 6, so run npx tsc in CI too.
Library authors should diff .d.ts output, which can differ in quote style and typeof references.

Originally published on fabwaseem.com.