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 the latest Next.js canary. Do not use Payload with the stable Next.js 16.0.* releases.

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, the following issue must be resolved:

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
We may also need to wait for vercel/next.js#84029 to be resolved. However, hydration errors can likely be suppressed temporarily, allowing us to ship Next.js 16 support without it.

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	819.99 KB	⚠️ +8.95 KB (+1.1%)
packages/payload/meta_index.json	esbuild/index.js	1.23 MB	⚠️ +2.04 KB (+0.2%)
packages/payload/meta_shared.json	esbuild/exports/shared.js	164.47 KB	⚠️ +204 B (+0.1%)
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	281.03 KB	✅ -2 B (-0.0%)
packages/ui/meta_client.json	esbuild/exports/client_optimized/index.js	1.16 MB	⚠️ +5.69 KB (+0.5%)
packages/ui/meta_shared.json	esbuild/exports/shared_optimized/index.js	14.44 KB	⚠️ +2 B (+0.0%)

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%, 663.65 KB
dist/views/Version	${{\color{Goldenrod}{ █▌ }}}$ 6.2%, 50.37 KB
dist/views/Document	${{\color{Goldenrod}{ ▍ }}}$ 1.9%, 15.47 KB
dist/views/List	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 11.30 KB
dist/views/Root	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 9.04 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.66 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ █████████████████▏ }}}$ 68.8%, 843.13 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▉ }}}$ 3.5%, 43.31 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.2%, 383.12 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.81 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.1%, 578.42 KB
dist/elements/FolderView	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 29.21 KB
dist/elements/BulkUpload	${{\color{Goldenrod}{ ▌ }}}$ 2.3%, 27.11 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.77 KB
dist/elements/Table	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.50 KB
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.19 KB
dist/fields/Upload	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 14.02 KB
dist/fields/Blocks	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 13.71 KB
dist/elements/QueryPresets	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 10.35 KB
dist/elements/PublishButton	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 8.69 KB
dist/providers/Folders	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.46 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.56 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.01 KB
(other)	${{\color{Goldenrod}{ ████████████▍ }}}$ 49.9%, 576.92 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

LeoAnt02 · 2025-12-08T03:17:27Z

Looking forward to having payload compatible next16 and turbo

Do we have an estimation on when this is going to be available ?

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 13 commits December 7, 2025 17:27

Update error message

e81dde6

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

f0b514f

bump nextjs peerdeps

926626c

bump nextjs canary

68f8e94

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

cf3d370

bump react types

291e4d3

bump templates

a53e749

fix cjs

5ba5cbc

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

10bf491

fix cjs

2bd3300

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

acef283

use esbuild for creating cjs withPayload

b3a3c15

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

6fa474a

AlessioGr added 16 commits December 7, 2025 19:25

bump esbuild, specify target node.js versions

4c88018

target nodejs version

667846f

do not swallow error

8096491

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

1bee1ca

fix cjs/esm support

aba54fc

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

a0125d7

fix comments and console msgs

a7367c0

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: next.js 16 support #14456

feat: next.js 16 support #14456

AlessioGr commented Nov 3, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Nov 3, 2025 •

edited

Loading

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!

LeoAnt02 commented Dec 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

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!

LeoAnt02 commented Dec 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

AlessioGr commented Nov 3, 2025 •

edited

Loading

github-actions bot commented Nov 3, 2025 •

edited

Loading