Admin RootLayout passes a server-made viewport element into the client DocumentRoot's <head> — duplicate tag, and it can suspend <head> and break hydration in Next dev
Maintainers usually reply within 1 day
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 35/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Stale
- Tech stack
- next.js, react, typescript
- Domain
- frontend
Research direction
Read packages/ui/src/layouts/Root/index.tsx and packages/ui/src/layouts/Root/DocumentRoot.tsx, then compare them with packages/next/src/adapters/viewport.ts. The issue proposes removing the viewport prop and its getViewportMeta call because the Next metadata adapter already emits the tag. Confirm the admin has one viewport meta tag and check that the reported development hydration failure is resolved; linked pull request #19706 is already open.
Written by the indexing model from the issue text.
Description
Describe the Bug
@payloadcms/ui's server RootLayout creates a <meta name="viewport"> React element on the server and passes it as the viewport prop into the client DocumentRoot, which renders it inside <head>:
packages/ui/src/layouts/Root/index.tsx—viewport={getViewportMeta(req.headers.get('user-agent') ?? undefined)}packages/ui/src/layouts/Root/DocumentRoot.tsx— renders{viewport}inside<head>
This causes two problems:
1. The tag is emitted twice. @payloadcms/next's generateViewport adapter (packages/next/src/adapters/viewport.ts) already emits the identical viewport meta through Next's metadata API (same getNextViewport logic, including maximumScale: 1 for iPhone user agents), so a standard admin layout ends up with two <meta name="viewport"> tags.
2. In Next.js 16 development it can suspend <head> during hydration, which trips a React bug and fails hydration of the whole admin. Because the element is created in a server component and rendered by a client component, Next's dev server streams its React debug rows (owner/stack) separately, over the dev websocket. When those rows arrive after hydration has already started, the element is still a blocked Flight chunk, so <head> suspends. React then replays the head fiber, and due to https://github.com/react/react/issues/37551 the replay overwrites the single saved hydration position outside <head> with a node inside <head>. <body> then hydrates against <head>'s nodes: "Hydration failed because the server rendered HTML didn't match the client", and the whole document is client-rendered.
Whether it fires depends on dev-server timing. In one project, a long-running dev server failed almost every load of some admin views (collection create/edit) while other views never failed; a freshly restarted server never failed at all. Production builds have no debug channel and are unaffected.
Reproduction Steps / Evidence
Observed on Payload 4.0.0-beta.6 (@payloadcms/[email protected]), Next.js 16.4.6, react/react-dom 19.3.1, dev server (next dev):
- Instrumenting React's singleton hydration path in the browser showed every failing load entering
<head>twice, with the second entry overwriting the saved cursor with a node inside<head>— the exact mechanism of react/react#37551. Clean loads entered<head>once. - Serving the same pages with the
viewportprop removed fromRootLayout: 0/6 failing loads, against 3/3 failing unmodified at the same moment. - With the prop removed, exactly one
<meta name="viewport">remains (the one fromgenerateViewport), and the admin behaves identically.
Suggested fix
Drop the viewport prop from RootLayout/DocumentRoot (and the getViewportMeta call), since the Next adapter's generateViewport already emits the same tag. DocumentRoot's own doc comment already points this way ("adapters with router-managed metadata supply it through head"), so an adapter without router-managed viewport metadata could pass it via the existing head prop instead. This removes the duplicate tag and the dev-only <head> suspension regardless of when the React bug is fixed.
- Dominant language
- TypeScript
- Stars
- 45.8k
- Forks
- 4.4k
- Avg merge
- 2d 16h
- Merged PRs (30d)
- 251
Getting set up
Starts the project's dev container in your browser, under your own GitHub account.
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from payloadcms/payload
-
db-d1-sqlite: upsert is aliased to updateOne, so payload.kv.set never inserts new keysPossibly taken @pcbeingused333 claimed this today. OpenBug db: d1-sqlite Payload OSS
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
payloadcms/payload#19766 ·
Maintainers usually reply within 1 day
-
Document bar (.doc-controls__content) overflows a 375 px viewport, clips "Created" and fails axe scrollable-region-focusablePossibly taken A pull request linked to this issue is open or already merged. Openarea: ui Bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
payloadcms/payload#19690 ·
Maintainers usually reply within 1 day
-
[v4] Blocks thumbnails croped 3:2Possibly taken @samiarif02 claimed this 2 days ago. Openarea: ui Bug Payload OSS status: needs-triage v3
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
payloadcms/payload#19609 ·
Maintainers usually reply within 1 day
-
Scheduled publish jobs are not deleted when their document is deleted (string id in the job, raw id in the cleanup)Possibly taken @volodymyrshk claimed this 10 days ago. Openarea: core Bug db: sqlite
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
payloadcms/payload#19448 ·
Maintainers usually reply within 1 day
-
plugin-multi-tenant: `isGlobal` collections redirect tenant-scoped users to `/admin` since 3.93.0 (GlobalViewRedirect prop-name mismatch)Possibly taken @JarrodMFlesch claimed this 10 days ago. OpenBug plugin: multi-tenant
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
payloadcms/payload#19420 · 1 assignee ·
Maintainers usually reply within 1 day
All issues in payloadcms/payload
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
milind-soni/OpenMausBot#6730 ·
Maintainers usually reply within 1 day
-
`@angular/[email protected]` depends on vulnerable Vite 7.3.7 - GHSA-p4f5-76q4-ffq7 (Critical RCE)Openarea: @angular/build
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
angular/angular-cli#34764 ·
Maintainers usually reply within 1 day
-
status/need-triage
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
google-gemini/gemini-cli#30384 · 1 comment ·
Maintainers usually reply within 1 day
-
P2
Difficulty 1/5 Under an hour Newbie friendliness 84/100
Maintainers usually reply within 1 day
-
area:image documentation good first issue
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 1 day