Payload CMS + Next.js 16.2: Compatibility Status & Upgrade Guide

Payload CMS and Next.js 16 are now fully compatible. If you've been holding off on upgrading because of uncertainty around support, that uncertainty is resolved. This article originally tracked the progress toward compatibility — starting with the critical Turbopack HMR fix that unblocked everything. That fix landed, the Payload team shipped official support, and the combination works in production.

Here's a summary of what changed, what was blocking things before, and where to go from here.

Where Things Stand: Full Compatibility Confirmed

Payload CMS officially supports Next.js 16. The mixed experiences developers were having earlier in the cycle — dependency conflicts, broken next/config internals, inconsistent behavior between projects — are resolved. The Payload team merged official Next.js 16 support in Pull Request #14456, and developers are running the stack in production without workarounds.

The official work is tracked in Pull Request #14456 on the Payload repository. This PR represents the effort to bring full Next.js 16 compatibility to Payload CMS.

The Turbopack HMR Breakthrough

The biggest obstacle preventing smooth compatibility was a Turbopack Hot Module Replacement bug. Developers were encountering an error that made development practically impossible: "Could not find the module X in the React Client Manifest." This issue, tracked as #85883 in the Next.js repository, affected anyone trying to use Payload with Next.js 16's Turbopack bundler.

Here's why this matters: Turbopack is Next.js's new bundler designed to replace Webpack, offering significantly faster builds and hot reloading during development. When HMR breaks, your development experience becomes frustrating at best and completely blocked at worst. Every code change requires a full rebuild instead of instant updates.

The Vercel team merged a fix for this Turbopack HMR issue. This removed the primary technical barrier that was preventing Payload from working smoothly with Next.js 16 — and the Payload team delivered official support shortly after.

What Full Compatibility Unlocks

The headline feature is Turbopack as your default bundler — both in development and production builds. The Next.js team reports:

• 5–10x faster Fast Refresh during development
• 2–5x faster production builds
• Turbopack File System Caching (beta) for faster startup times on large projects

Beyond Turbopack, full Next.js 16 compatibility gives Payload projects access to:

• New caching model: use cache directive and Partial Pre-Rendering (PPR) for instant navigation (Payload support coming in a future release)
• React Compiler support (stable): Built-in automatic memoization without manual useMemo/useCallback
• View Transitions API and useEffectEvent() hook via React 19.2
• Next.js Devtools MCP: Model Context Protocol integration for improved debugging workflows

What the Payload Team Shipped

This wasn't a version bump. The Payload team shipped multiple PRs alongside the upstream Next.js fixes:

• Conditional tabs breaking due to unstable tab IDs in Next.js 16 (#15270)
• Import map reliability during HMR to fix hot reloading (#14474)
• Turbopack build support with correct handling of external packages (#14475)
• Error spam during HMR when using Turbopack (#14502)
• withPayload wrapper compatibility (#14473)

Full list in the main Next.js 16 support PR.

Next.js 16.2: The Stack Gets Faster Again

If you've already upgraded, there's more good news. Next.js 16.2 ships a significant rendering speed improvement — Server Components payload deserialization runs up to 350% faster, which translates to 25–60% faster rendering to HTML in real applications. The official benchmark included Payload CMS specifically, and the gains are substantial.

The release also ships five debugging improvements that remove common sources of lost developer time.

→ Next.js 16.2: What's New and What It Means for Payload Projects

Why This Mattered From a Security Perspective

The timing of this progress couldn't be better. As I detailed in my article about the CVSS 10.0 vulnerability, staying on outdated versions of Next.js is no longer just about missing out on performance improvements or new features. There's a legitimate security concern with the npm supply chain attack that affects older versions.

When compatibility issues are cosmetic, you can justify waiting. When they're security-related, the calculation changes entirely. Having Payload work properly with Next.js 16 means you won't have to choose between using your preferred CMS and maintaining a secure application.

How to Upgrade

Requirements

• Payload CMS: v3.73.0 or later
• Next.js: 16.2.0 or later

Step 1: Update dependencies

{
  "dependencies": {
    "payload": "^3.73.0",
    "next": "^16.2.0"
  }
}

Run your package manager:

npm update
# or
pnpm update

Step 2: Verify Turbopack is active

Next.js 16 uses Turbopack by default. Start your dev server and confirm the output:

 ▲ Next.js 16.2.0
 - Local:        http://localhost:3000
 - Turbopack (dev) started in XXXms

Step 3: Handle the async params breaking change

Route params and search params are now async in Next.js 16. Update your page components:

Before (Next.js 15):

export default function Post({ params }: { params: { slug: string } }) {
  return <div>{params.slug}</div>
}

After (Next.js 16):

export default async function Post({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  return <div>{slug}</div>
}

See the Next.js 16 upgrade guide for the full list of breaking changes including next/image defaults and the new proxy.ts middleware model.

Step 4: Test your Payload admin

After upgrading, verify:

1. Live Preview — open any collection with live preview enabled and confirm HMR works correctly
2. Conditional fields — test any tabs or conditional field logic
3. File uploads — verify media collections handle uploads properly

One thing worth knowing: how you deploy with Next.js 16. Payload works best on a persistent Node.js server — the serverless model on Vercel creates real problems with Payload's initialization lifecycle, database connection pooling, and admin operations. Full guide on the right setup:

→ Deploy Payload CMS with Next.js 16: Self-Hosted Guide

The short version: output: "standalone", multi-stage Docker build, Nginx in front, and Postgres on the same machine or a managed instance in the same datacenter. That setup runs reliably and is cheaper than Vercel Pro once you account for usage-based pricing. If you're comparing hosting options beyond a raw VPS, I've also written a comparison of Fly.io, Cloud Run, Railway and other self-hosted alternatives.

If your project handles multiple languages, full Next.js 16 compatibility also removes friction around Payload's localization system and next-intl. Setting up Payload CMS localization with next-intl walks through the full configuration.

For large content migrations or bulk data operations post-upgrade, large data imports in Payload with Drizzle transactions covers the patterns that keep those operations safe and reliable.

If you upgraded and ran into something specific — a dependency conflict, a config issue, something in the admin panel — drop it in the comments and I'll take a look.

If you're considering a migration to Payload from another CMS, I've written a complete migration overview covering what's involved. Payload itself is free and open-source, but if you're wondering what it actually costs to run in production, the pricing breakdown covers hosting, infrastructure, and total cost of ownership.

If you're running Payload CMS and Next.js 16 in production and want a senior Payload specialist to review your architecture or build with you, I work with a small number of clients at a time. Thanks, Matija