feat: next.js 16 support #14456

AlessioGr · 2025-11-03T17:21:46Z

This PR updates this monorepo and all templates to use Next.js 16. Running our test suites against Next.js 16 is required to guarantee support.

Individual, Next.js 16-related fixes, will be made in separate, smaller PRs (listed below).

Current Status / Known Issues

You can use Next.js 16 with Payload, as long as you're using the latest Payload version and Next.js 16.1.0+ or the latest Next.js canary.

What to expect when using the latest Payload version and Next.js canary:

✅ Turbopack build: Turbopack build supported when using the latest Payload version and the latest Next.js canary. No issues are expected.
✅ HMR: When using Next.js 16.1.0-canary.15 or higher, no issues are expected. Otherwise, HMR may flood your console with errors if you're using turbopack.
Admin Panel:
- ❌ You may run into occasional hydration errors when navigating through the admin panel
- ❌ Navigating through the admin panel, at least during dev and when using turbopack, may feel slower. This issue was introduced in 15.4.2-canary.17. It's present in both Next.js 15.5 and Next.js 16

When is Next.js 16 support ready? What are we waiting on?

Before we can guarantee full support for Next.js 16, one remaining issue must be resolved by the Next.js / React team:

We need to wait for vercel/next.js#84029 to be resolved. We initially expected these hydration errors to be suppressible, but that turned out not to be the case. As a result, this issue is now the final blocker for Next.js 16 support. Most of the CI e2e test failures in this PR are the result of this issue.

The following Next.js issues have been resolved and are no longer blockers:

Turbopack HMR stability - vercel/next.js#85883
Currently breaks when a live-preview–enabled page is open (related Payload issue).
The Next.js team is actively working on a fix: PR #86239. Fixed in Next.js canary
~~Turbopack Build support: PR #86375.~~ Fixed in Next.js canary

List of Next.js 16-related PRs that were extracted from this branch

github-actions · 2025-11-03T17:28:42Z

📦 esbuild Bundle Analysis for payload

This analysis was generated by esbuild-bundle-analyzer. 🤖

Meta File	Out File	Size (raw)	Note
packages/next/meta_index.json	esbuild/index.js	820.63 KB	🆕 Added
packages/payload/meta_index.json	esbuild/index.js	1.24 MB	🆕 Added
packages/payload/meta_shared.json	esbuild/exports/shared.js	164.50 KB	🆕 Added
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	281.03 KB	🆕 Added
packages/ui/meta_client.json	esbuild/exports/client_optimized/index.js	1.17 MB	🆕 Added
packages/ui/meta_shared.json	esbuild/exports/shared_optimized/index.js	14.44 KB	🆕 Added

Largest paths

These visualization shows top 20 largest paths in the bundle.

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████████████▎ }}}$ 81.4%, 664.25 KB
dist/views/Version	${{\color{Goldenrod}{ █▌ }}}$ 6.2%, 50.37 KB
dist/views/Document	${{\color{Goldenrod}{ ▍ }}}$ 1.9%, 15.48 KB
dist/views/List	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 11.30 KB
dist/views/Root	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 9.08 KB
dist/views/Versions	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 6.02 KB
dist/views/API	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 6.01 KB
dist/elements/Nav	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 5.61 KB
dist/views/Account	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 5.41 KB
dist/elements/DocumentHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 4.90 KB
dist/views/Login	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 4.48 KB
dist/views/Dashboard	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 3.74 KB
dist/views/ForgotPassword	${{\color{Goldenrod}{ }}}$ 0.4%, 3.13 KB
dist/layouts/Root	${{\color{Goldenrod}{ }}}$ 0.4%, 2.91 KB
dist/views/CreateFirstUser	${{\color{Goldenrod}{ }}}$ 0.3%, 2.83 KB
dist/templates/Default	${{\color{Goldenrod}{ }}}$ 0.3%, 2.63 KB
dist/views/BrowseByFolder	${{\color{Goldenrod}{ }}}$ 0.3%, 2.58 KB
dist/views/ResetPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 2.53 KB
dist/views/CollectionFolders	${{\color{Goldenrod}{ }}}$ 0.3%, 2.46 KB
dist/views/Logout	${{\color{Goldenrod}{ }}}$ 0.2%, 1.99 KB
(other)	${{\color{Goldenrod}{ ████▋ }}}$ 18.6%, 151.71 KB

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ █████████████████▏ }}}$ 68.7%, 844.06 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▉ }}}$ 3.5%, 43.34 KB
dist/collections/operations	${{\color{Goldenrod}{ ▊ }}}$ 3.0%, 36.43 KB
dist/auth/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 15.23 KB
dist/queues/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 12.11 KB
dist/globals/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 11.98 KB
dist/fields/config	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 11.95 KB
dist/utilities/configToJSONSchema.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 11.83 KB
dist/fields/validations.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.21 KB
dist/bin/generateImportMap	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.38 KB
dist/database/migrations	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.07 KB
dist/collections/config	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.90 KB
dist/uploads/fetchAPI-multipart	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.74 KB
dist/index.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.65 KB
dist/config/orderable	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.27 KB
dist/collections/endpoints	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.00 KB
dist/auth/strategies	${{\color{Goldenrod}{ }}}$ 0.4%, 5.50 KB
dist/config/sanitize.js	${{\color{Goldenrod}{ }}}$ 0.4%, 5.49 KB
dist/auth/endpoints	${{\color{Goldenrod}{ }}}$ 0.4%, 5.42 KB
dist/utilities/telemetry	${{\color{Goldenrod}{ }}}$ 0.4%, 5.31 KB
(other)	${{\color{Goldenrod}{ ███████▊ }}}$ 31.3%, 384.99 KB

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████████████▊ }}}$ 79.0%, 127.13 KB
dist/fields/validations.js	${{\color{Goldenrod}{ █▌ }}}$ 6.3%, 10.21 KB
dist/fields/baseFields	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 2.79 KB
dist/utilities/deepCopyObject.js	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 2.51 KB
dist/auth/cookies.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 1.55 KB
dist/utilities/flattenTopLevelFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 1.42 KB
dist/fields/config	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.28 KB
dist/utilities/flattenAllFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 943 B
dist/folders/utils	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 916 B
dist/utilities/getVersionsConfig.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 895 B
dist/utilities/unflatten.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 779 B
dist/utilities/sanitizeUserDataForEmail.js	${{\color{Goldenrod}{ }}}$ 0.4%, 713 B
dist/utilities/getFieldPermissions.js	${{\color{Goldenrod}{ }}}$ 0.4%, 651 B
dist/collections/config	${{\color{Goldenrod}{ }}}$ 0.4%, 570 B
dist/bin/generateImportMap	${{\color{Goldenrod}{ }}}$ 0.3%, 561 B
dist/auth/sessions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 525 B
dist/utilities/getSafeRedirect.js	${{\color{Goldenrod}{ }}}$ 0.3%, 423 B
dist/utilities/deepMerge.js	${{\color{Goldenrod}{ }}}$ 0.3%, 413 B
dist/utilities/formatLabels.js	${{\color{Goldenrod}{ }}}$ 0.2%, 380 B
dist/utilities/appendUploadSelectFields.js	${{\color{Goldenrod}{ }}}$ 0.2%, 360 B
(other)	${{\color{Goldenrod}{ █████▎ }}}$ 21.0%, 33.85 KB

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
dist/features/blocks	${{\color{Goldenrod}{ ███▏ }}}$ 12.6%, 35.02 KB
dist/lexical/plugins	${{\color{Goldenrod}{ ██▉ }}}$ 11.5%, 32.00 KB
dist/lexical/ui	${{\color{Goldenrod}{ ██▏ }}}$ 8.8%, 24.36 KB
dist/features/experimental_table	${{\color{Goldenrod}{ ██▏ }}}$ 8.5%, 23.70 KB
dist/packages/@lexical	${{\color{Goldenrod}{ █▋ }}}$ 6.8%, 18.99 KB
dist/features/link	${{\color{Goldenrod}{ █▋ }}}$ 6.5%, 18.04 KB
dist/features/toolbars	${{\color{Goldenrod}{ █▌ }}}$ 6.4%, 17.75 KB
dist/features/upload	${{\color{Goldenrod}{ █▏ }}}$ 4.9%, 13.73 KB
dist/features/textState	${{\color{Goldenrod}{ █ }}}$ 4.0%, 11.08 KB
dist/features/relationship	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 8.96 KB
dist/lexical/utils	${{\color{Goldenrod}{ ▊ }}}$ 3.0%, 8.22 KB
dist/features/debug	${{\color{Goldenrod}{ ▋ }}}$ 2.7%, 7.39 KB
dist/utilities/fieldsDrawer	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 7.12 KB
dist/features/converters	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 7.04 KB
dist/lexical/config	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 5.08 KB
dist/features/lists	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 5.00 KB
dist/features/format	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 3.46 KB
dist/lexical/LexicalEditor.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 3.17 KB
dist/lexical/theme	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.62 KB
dist/features/indent	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.50 KB
(other)	${{\color{Goldenrod}{ █████████████████████▊ }}}$ 87.4%, 242.76 KB

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████▌ }}}$ 50.0%, 578.37 KB
dist/elements/FolderView	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 29.20 KB
dist/elements/BulkUpload	${{\color{Goldenrod}{ ▌ }}}$ 2.3%, 27.13 KB
dist/elements/WhereBuilder	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 16.85 KB
dist/views/Edit	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 16.16 KB
dist/fields/Relationship	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 15.76 KB
dist/elements/Table	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.50 KB
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.25 KB
dist/fields/Upload	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 14.06 KB
dist/fields/Blocks	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 13.70 KB
dist/elements/QueryPresets	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 10.35 KB
dist/elements/PublishButton	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 8.71 KB
dist/providers/Folders	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.50 KB
dist/elements/LivePreview	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.38 KB
dist/elements/ListHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.84 KB
dist/elements/HTMLDiff	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.81 KB
dist/fields/Array	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.55 KB
dist/views/CollectionFolder	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.43 KB
dist/elements/ReactSelect	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.31 KB
dist/views/List	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.00 KB
(other)	${{\color{Goldenrod}{ ████████████▌ }}}$ 50.0%, 577.91 KB

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Path	Size
dist/graphics/Logo	${{\color{Goldenrod}{ █████▋ }}}$ 22.5%, 3.12 KB
../../node_modules	${{\color{Goldenrod}{ ████▊ }}}$ 19.1%, 2.65 KB
dist/graphics/Icon	${{\color{Goldenrod}{ ██▊ }}}$ 11.0%, 1.52 KB
dist/utilities/formatDocTitle	${{\color{Goldenrod}{ ██▍ }}}$ 9.6%, 1.32 KB
dist/providers/TableColumns	${{\color{Goldenrod}{ █▌ }}}$ 6.2%, 862 B
dist/utilities/groupNavItems.js	${{\color{Goldenrod}{ █▍ }}}$ 5.9%, 816 B
dist/utilities/api.js	${{\color{Goldenrod}{ █▍ }}}$ 5.5%, 756 B
dist/elements/Translation	${{\color{Goldenrod}{ ▉ }}}$ 3.6%, 493 B
dist/utilities/handleTakeOver.js	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 440 B
dist/elements/withMergedProps	${{\color{Goldenrod}{ ▌ }}}$ 2.4%, 339 B
dist/elements/WithServerSideProps	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 232 B
dist/utilities/handleGoBack.js	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 192 B
dist/fields/mergeFieldStyles.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 159 B
dist/utilities/handleBackToDashboard.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 153 B
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 147 B
dist/utilities/abortAndIgnore.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 146 B
dist/utilities/hasSavePermission.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 136 B
dist/utilities/findLocaleFromCode.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 84 B
dist/utilities/sanitizeID.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 77 B
dist/utilities/isEditing.js	${{\color{Goldenrod}{ }}}$ 0.4%, 59 B
(other)	${{\color{Goldenrod}{ ███████████████████▍ }}}$ 77.5%, 10.73 KB

Details

Next to the size is how much the size has increased or decreased compared with the base branch of this PR.

‼️: Size increased by 20% or more. Special attention should be given to this.
⚠️: Size increased in acceptable range (lower than 20%).
✅: No change or even downsized.
🗑️: The out file is deleted: not found in base branch.
🆕: The out file is newly found: will be added to base branch.

… times on load

The `DraggableSortable` (rendered in the list view when sorting columns) was unmounted and re-mounted multiple times when loading a page. This happened because the `useMemo` we used in `PillSelector` was returning a new function reference on each recomputation => every time it ran, `DraggableSortable` remounted. This means the ID generated by `useId` in `DraggableSortable` changed multiple times during load. This made the hydration issues in my [Next.js 16 PR](#14456) more difficult to debug. This PR removes the unnecessary re-mounting, improving performance and potentially reducing the risk of hydration issues.

This reverts commit 00702a2.

…-16-support

robertotcestari · 2025-12-15T19:06:33Z

Any news on this one?

AlessioGr · 2025-12-15T19:16:16Z

Any news on this one?

vercel/next.js#84029 has unfortunately become a blocker for Next.js 16 support, and we're waiting for that issue to be resolved. I've updated the PR description

kristianka · 2025-12-15T19:45:38Z

Thank you @AlessioGr for your hard work, hopefully Vercel can fix the issue soon!

cuihaoweb · 2025-12-30T06:47:40Z

Is there any progress?

MarkAtOmniux · 2025-12-30T13:21:59Z

Is there any progress?

Let the man cook!

wpenistone · 2026-01-01T09:49:15Z

happy new years

…ackages from 3.69.0 to 3.58.5 Downgraiding was necessary to avoid error with new payload widget feature CollectionCards Sources: - payloadcms/payload#15010 - payloadcms/payload#14456

AlessioGr · 2026-01-06T21:59:11Z

Progress: managed to create a minimal reproduction for the hydration issues here: https://github.com/AlessioGr/repro-hydration

Should make it easier for the React/Next.js team to resolve this.

green-s · 2026-01-07T20:58:44Z

Does this PR fix the problem?

AlessioGr · 2026-01-07T21:00:23Z

Does this PR fix the problem?

It does not, unfortunately

AlessioGr added 2 commits November 3, 2025 09:19

bump packages

d238227

bump dnd kit

0666056

github-actions bot added the created-by: Payload team label Nov 3, 2025

AlessioGr added 10 commits November 3, 2025 09:38

fix: hydration error from dnd kit library

a41cab2

fix

b64b871

perf: ensure pillselector draggablesortable does not remount multiple…

3b19cd3

… times on load

surpress hydration errors for now

a953320

chore: remove deprecated next config properties in monorepo

0a9815f

surpress more hydration errors

1412111

Fix HMR

bf341c4

fix flaky test - page.reload was logging out the user

690ed53

Merge remote-tracking branch 'origin/main' into feat/next-16-support

3a88243

fix

75b0235

AlessioGr mentioned this pull request Nov 4, 2025

perf(ui): avoid unnecessary remounting of DraggableSortable #14463

Merged

AlessioGr added 14 commits November 4, 2025 13:03

Merge remote-tracking branch 'origin/main' into fix/next-16-hmr

e1d0052

update templates

6e3fdf1

chore: regenerate lockfile

725e24c

chore: fix build

4dd9fa2

fix turbopack error

d8b766a

Merge branch 'temptest' into feat/next-16-support

2368473

lockfile

c496d57

templates: disable turbopack for build

00702a2

Merge remote-tracking branch 'origin/main' into feat/next-16-support

b3b9771

fix lint

ceb2515

fix template tests in ci

2edb1df

fix(next): turbopack build support

0bf4b7f

Revert "templates: disable turbopack for build"

f080567

This reverts commit 00702a2.

Merge remote-tracking branch 'origin/fix/turbo-bundle' into feat/next…

fb06d20

…-16-support

AlessioGr added 9 commits December 7, 2025 20:37

Merge branch 'feat/turbo-build-support' into feat/next-16-support

619c404

fix withpayload imports

18d4721

Merge branch 'feat/turbo-build-support' into feat/next-16-support

1693f53

fix peerdeps

c65bdbe

Merge remote-tracking branch 'origin/main' into feat/next-16-support

580cdbd

Merge remote-tracking branch 'origin/main' into feat/next-16-support

02f8b04

fix transaction errors

dd08fa9

Merge remote-tracking branch 'origin/main' into feat/next-16-support

27a6239

Merge remote-tracking branch 'origin/main' into feat/next-16-support

614feaf

AlessioGr added 4 commits December 18, 2025 12:59

nextjs 15.1.0

b3ec581

Merge remote-tracking branch 'origin/main' into feat/next-16-support

b267153

fix

c600a9d

bumps, templates

cb70a01

wp99cp mentioned this pull request Jan 3, 2026

[Bug]: Bigger Paragraph seems to be crashing cevi/conveniat-webpage#736

Open

AlessioGr added 6 commits January 5, 2026 18:45

Merge remote-tracking branch 'origin/main' into feat/next-16-support

fab3582

lockfile

c41f30e

templates

e0ad3d1

remove invalid configuration

bea5dd4

bump next

416f541

templates, lockfile

5c889f0

feat: next.js 16 support #14456

Are you sure you want to change the base?

feat: next.js 16 support #14456

Conversation

AlessioGr commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Current Status / Known Issues

When is Next.js 16 support ready? What are we waiting on?

List of Next.js 16-related PRs that were extracted from this branch

Uh oh!

github-actions bot commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 esbuild Bundle Analysis for payload

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Uh oh!

robertotcestari commented Dec 15, 2025

Uh oh!

AlessioGr commented Dec 15, 2025

Uh oh!

kristianka commented Dec 15, 2025

Uh oh!

cuihaoweb commented Dec 30, 2025

Uh oh!

MarkAtOmniux commented Dec 30, 2025

Uh oh!

wpenistone commented Jan 1, 2026

Uh oh!

AlessioGr commented Jan 6, 2026

Uh oh!

green-s commented Jan 7, 2026

Uh oh!

AlessioGr commented Jan 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

13 participants

AlessioGr commented Nov 3, 2025 •

edited

Loading

github-actions bot commented Nov 3, 2025 •

edited

Loading