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.

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

All Next.js 16 / React issues known to us are resolved. Now, we only need to get the remaining failing tests to pass.

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
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.

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	945.32 KB	🆕 Added
packages/payload/meta_index.json	esbuild/index.js	1.31 MB	🆕 Added
packages/payload/meta_shared.json	esbuild/exports/shared.js	164.88 KB	🆕 Added
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	281.40 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	16.32 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}{ ████████████████████▋ }}}$ 82.5%, 776.25 KB
dist/views/Version	${{\color{Goldenrod}{ █▎ }}}$ 5.4%, 50.45 KB
dist/views/Dashboard	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 16.48 KB
dist/views/Document	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 16.00 KB
dist/views/List	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 11.27 KB
dist/views/Root	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 9.03 KB
dist/views/Versions	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 6.16 KB
dist/views/API	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.08 KB
dist/elements/Nav	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 5.53 KB
dist/views/Account	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 5.46 KB
dist/elements/DocumentHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 4.81 KB
dist/views/Login	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 4.41 KB
dist/views/ForgotPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 3.09 KB
dist/layouts/Root	${{\color{Goldenrod}{ }}}$ 0.3%, 2.91 KB
dist/views/CreateFirstUser	${{\color{Goldenrod}{ }}}$ 0.3%, 2.81 KB
dist/templates/Default	${{\color{Goldenrod}{ }}}$ 0.3%, 2.63 KB
dist/views/BrowseByFolder	${{\color{Goldenrod}{ }}}$ 0.3%, 2.56 KB
dist/views/CollectionFolders	${{\color{Goldenrod}{ }}}$ 0.3%, 2.44 KB
dist/views/ResetPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 2.40 KB
dist/views/Logout	${{\color{Goldenrod}{ }}}$ 0.2%, 1.94 KB
(other)	${{\color{Goldenrod}{ ████▍ }}}$ 17.5%, 164.39 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ █████████████████ }}}$ 68.0%, 887.58 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▊ }}}$ 3.3%, 43.58 KB
dist/collections/operations	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 38.51 KB
dist/versions/migrations	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 18.50 KB
dist/auth/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 15.46 KB
dist/globals/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 12.92 KB
dist/queues/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 12.80 KB
dist/fields/config	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 12.51 KB
dist/utilities/configToJSONSchema.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 12.04 KB
dist/fields/validations.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.21 KB
dist/bin/generateImportMap	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.61 KB
dist/collections/config	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 8.35 KB
dist/uploads/fetchAPI-multipart	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.74 KB
dist/index.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.69 KB
dist/database/migrations	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.50 KB
dist/config/orderable	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.27 KB
dist/collections/endpoints	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.21 KB
dist/config/sanitize.js	${{\color{Goldenrod}{ }}}$ 0.4%, 5.58 KB
dist/auth/strategies	${{\color{Goldenrod}{ }}}$ 0.4%, 5.49 KB
dist/auth/endpoints	${{\color{Goldenrod}{ }}}$ 0.4%, 5.42 KB
(other)	${{\color{Goldenrod}{ ████████ }}}$ 32.0%, 418.41 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████████████▋ }}}$ 78.8%, 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.54 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/getVersionsConfig.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 1.04 KB
dist/utilities/flattenAllFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 943 B
dist/folders/utils	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 916 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/fields/getFieldPaths.js	${{\color{Goldenrod}{ }}}$ 0.3%, 485 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
(other)	${{\color{Goldenrod}{ █████▎ }}}$ 21.2%, 34.21 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.14 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.11 KB
dist/features/toolbars	${{\color{Goldenrod}{ █▌ }}}$ 6.4%, 17.75 KB
dist/features/upload	${{\color{Goldenrod}{ █▎ }}}$ 5.0%, 13.77 KB
dist/features/textState	${{\color{Goldenrod}{ █ }}}$ 4.0%, 11.08 KB
dist/features/relationship	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 9.03 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.15 KB
dist/features/converters	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 7.05 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%, 243.00 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████▍ }}}$ 49.7%, 578.70 KB
dist/elements/FolderView	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 29.29 KB
dist/elements/BulkUpload	${{\color{Goldenrod}{ ▌ }}}$ 2.4%, 27.61 KB
dist/elements/WhereBuilder	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 16.96 KB
dist/views/Edit	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 16.70 KB
dist/fields/Relationship	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 15.79 KB
dist/elements/Table	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 15.74 KB
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.23 KB
dist/fields/Upload	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 14.20 KB
dist/fields/Blocks	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 13.70 KB
dist/elements/QueryPresets	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 10.33 KB
dist/elements/PublishButton	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 9.05 KB
dist/providers/Folders	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.45 KB
dist/elements/LivePreview	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.38 KB
dist/elements/ListHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.90 KB
dist/elements/HTMLDiff	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.81 KB
dist/fields/Array	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.73 KB
dist/views/CollectionFolder	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.38 KB
dist/elements/ReactSelect	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.34 KB
dist/views/List	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.99 KB
(other)	${{\color{Goldenrod}{ ████████████▌ }}}$ 50.3%, 584.61 KB

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

Path	Size
dist/graphics/Logo	${{\color{Goldenrod}{ █████ }}}$ 20.0%, 3.12 KB
../../node_modules	${{\color{Goldenrod}{ ████▎ }}}$ 17.0%, 2.65 KB
dist/graphics/Icon	${{\color{Goldenrod}{ ██▍ }}}$ 9.8%, 1.52 KB
dist/utilities/formatDocTitle	${{\color{Goldenrod}{ ██▏ }}}$ 8.5%, 1.32 KB
dist/providers/TableColumns	${{\color{Goldenrod}{ █▍ }}}$ 5.5%, 862 B
dist/utilities/groupNavItems.js	${{\color{Goldenrod}{ █▎ }}}$ 5.2%, 814 B
dist/utilities/getGlobalData.js	${{\color{Goldenrod}{ █▏ }}}$ 4.9%, 762 B
dist/utilities/api.js	${{\color{Goldenrod}{ █▏ }}}$ 4.8%, 756 B
dist/elements/Translation	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 493 B
dist/utilities/handleTakeOver.js	${{\color{Goldenrod}{ ▋ }}}$ 2.8%, 440 B
dist/utilities/traverseForLocalizedFields.js	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 399 B
dist/elements/withMergedProps	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 339 B
dist/utilities/getVisibleEntities.js	${{\color{Goldenrod}{ ▌ }}}$ 2.1%, 329 B
dist/utilities/getNavGroups.js	${{\color{Goldenrod}{ ▍ }}}$ 1.9%, 301 B
dist/elements/WithServerSideProps	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 232 B
dist/utilities/handleGoBack.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 180 B
dist/fields/mergeFieldStyles.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 159 B
dist/utilities/handleBackToDashboard.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 152 B
dist/forms/Form	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 147 B
dist/utilities/abortAndIgnore.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 146 B
(other)	${{\color{Goldenrod}{ ████████████████████ }}}$ 80.0%, 12.51 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

…eliably

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 30 commits January 19, 2026 10:12

fix flakes when closing toasts. Multiple toasts are now closed more r…

516c965

…eliably

bump nextjs

00dd14f

versions flakiness

f2e325f

templates

0a0b329

fix more flakiness

de03674

test: skip incorrectly written test

324b90f

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

bed2ee6

fix flaky localization test suite

32a8615

use test utilities

fe48596

fix flaky date test suite

b44be49

fix incorrect json tests

c51bf29

fix more toast-related flakes

8e870b5

fix more toast issues

be42f64

add missing nextjs image qualities config

37fec85

here too

2ac09d1

templates

3c8d590

remove duplicative toast closing logic

bd746b2

bless locked documents e2e suite with much-needed clearAndSeedEverything

928aaaf

fix flaky form-state tests

ec4eca7

fix incorrect toast handling in test

feb5f7e

fix access control e2e test suite

7917bdc

types

f5c325c

fix toast handling

250530b

fix types

620ff0c

add missing item to onlyBuiltDependencies

d212a46

fix weird multi tenant e2e setup, duplicate seeding and flakiness

c380cb6

deflake test

4508d31

add seed and clear to bulk edit e2e tests

3777c0a

fix tabs tests

cba0686

simplify test

c47b47d

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

16 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

16 participants

AlessioGr commented Nov 3, 2025 •

edited

Loading

github-actions bot commented Nov 3, 2025 •

edited

Loading