Payload CMS Next.js 16 Support: Turbocharged Dev Builds

The Wait Is Finally Over

If you've been following Payload CMS development, you know we've been stuck in a frustrating holding pattern since Next.js 16 launched in November 2024. While the Next.js team shipped Turbopack as the default bundler with promises of 5-10x faster Fast Refresh, Payload projects remained chained to the slower Webpack-based development experience.

That changes today.

Payload CMS v3.73.0, released just two days ago, brings full Next.js 16 compatibility—including the Turbopack development server and build support we've been waiting for. After months of coordination between the Payload and Next.js teams to resolve blocking issues, your Payload projects can now access every Next.js 16 feature.

TL;DR

Payload CMS v3.73.0 adds full Next.js 16 support with Turbopack HMR and builds. Requires Next.js >16.1.1-canary.35 or 16.2.0+. Upgrade now for 5-10x faster development and access to all Next.js 16 features including React 19.2, enhanced routing, and the new caching model.

What This Unlocks for Your Payload Projects

The headline feature is Turbopack as your default bundler—both in development and production builds. This isn't just a incremental improvement; the Next.js team reports:

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

But Turbopack is just the beginning. Full Next.js 16 compatibility means your Payload projects now have access to:

New Caching and Performance Model

• Cache Components: New model using Partial Pre-Rendering (PPR) and use cache for instant navigation (Payload support coming in a future release)
• Enhanced updateTag() and revalidateTag() APIs for more granular cache control
• Optimized routing with layout deduplication and incremental prefetching

Developer Experience Improvements

• Next.js Devtools MCP: Model Context Protocol integration for improved debugging workflows
• Better logging for builds and development requests
• React Compiler Support (stable): Built-in automatic memoization without manual optimization

Modern React Features (React 19.2)

• View Transitions API support
• useEffectEvent() hook
• New <Activity/> component

Breaking Changes to Be Aware Of

Next.js 16 includes some breaking changes you'll need to handle:

• Async params: Route params and search params are now async by default
• next/image defaults: New default behavior for image optimization
• Middleware replaced by proxy.ts: Clarifies the network boundary in your application architecture

The Technical Journey: What It Took to Get Here

This wasn't a simple dependency version bump. The Payload team had to coordinate with Next.js core developers to resolve fundamental compatibility issues. Here's what was blocking Next.js 16 support:

Major Blockers (Now Resolved)

1. Turbopack HMR stability issues (Next.js #85883): Initially broke when live-preview pages were open. Fixed by the Next.js team in canary builds.

2. Turbopack build support (Next.js PR #86375): Production builds weren't working with Turbopack initially.

3. Hydration errors (Next.js #84029): The Payload team initially expected these to be suppressible, but they turned out to be a fundamental blocker requiring upstream Next.js fixes.

Payload-Specific Fixes

The Payload team shipped multiple PRs to support Next.js 16 properly:

• Conditional tabs breaking due to unstable tab IDs in Next.js 16 (#15270)
• Import map reliability during HMR to fix Next.js 16 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)
• Performance optimization to avoid unnecessary remounting of draggable components (#14463)

You can review the complete list of related PRs in the main Next.js 16 support pull request.

How to Upgrade Your Payload Project

Requirements

• Payload CMS: v3.73.0 or later
• Next.js: >16.1.1-canary.35 or 16.2.0+ (when released)

Step 1: Update Dependencies

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

Run your package manager's update command:

npm update
# or
pnpm update
# or
yarn upgrade

Step 2: Verify Turbopack Is Active

Next.js 16 uses Turbopack by default, but you can verify it's working by checking your development server output:

npm run dev

You should see output indicating Turbopack is running:

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

Step 3: Handle Breaking Changes

Review the Next.js 16 upgrade guide for async params and other breaking changes. The most common updates you'll need:

Before (Next.js 15):

// app/posts/[slug]/page.tsx
export default function Post({ params }: { params: { slug: string } }) {
  return {params.slug}
}

After (Next.js 16):

// app/posts/[slug]/page.tsx
export default async function Post({ params }: { params: Promise }) {
  const { slug } = await params
  return {slug}
}

Step 4: Test Your Payload Admin and Collections

The Payload admin UI works identically, but you should test:

1. Live Preview: Open any collection with live preview enabled and verify HMR works correctly
2. File uploads: Verify media collections handle uploads properly
3. Conditional fields: Test any collections using conditional field logic (tabs, conditional rendering)

What's Still Coming

Payload's official templates will be updated once Next.js 16.2.0 is officially released (not canary). Additionally, support for Next.js 16's new cache components using Partial Pre-Rendering will follow in a future Payload release.

Why This Matters for the Payload Ecosystem

This release represents more than just compatibility—it's a signal that Payload is keeping pace with the rapidly evolving Next.js ecosystem. The coordination between teams to resolve blocking issues shows the maturity of both projects.

For developers building production Payload applications, the performance improvements alone justify upgrading. Turbopack's 5-10x faster Fast Refresh means tighter feedback loops during development, especially on larger projects with complex collection schemas.

But perhaps more importantly, this unlocks the entire Next.js 16 feature set for Payload developers. As Next.js evolves its caching model, routing optimizations, and React 19 integration, Payload projects can take advantage of these improvements without being stuck on older Next.js versions.

Conclusion

After months of waiting since Next.js 16's November 2024 launch, Payload CMS developers finally have full access to Turbopack and all Next.js 16 features. The v3.73.0 release represents significant engineering effort from both the Payload and Next.js teams to resolve fundamental compatibility issues.

If you're running Payload in production, the performance improvements from Turbopack alone make upgrading worthwhile. Just be prepared to handle the async params breaking change and test your live preview workflows thoroughly.

The future roadmap includes support for Next.js 16's cache components and PPR integration—features that will further improve the performance characteristics of Payload-powered applications.

Ready to upgrade? Check the v3.73.0 release notes and the Next.js 16 support PR for complete technical details.