Unverified Commit 6e0d99dd authored by Pete Hunt's avatar Pete Hunt Committed by GitHub

docs+test: root-cause dev-only <html> attribute strip after hydration

Diagnosis of the reported regression where a pre-hydration inline script's
class/attribute on <html> is stripped after hydration in next dev (works in
16.2.11, broken on the 16.3 line; production unaffected).

Root cause: the vendored React reconciler upgrade in #92945
(19.3.0-canary-fef12a01-20260413 -> da9325b5-20260417, first shipped in
16.3.0-canary.3). The App Router enables React StrictMode by default in dev
(__NEXT_STRICT_MODE_APP), and React's dev-only double-invoke-effects now
disappears+reappears the root <html>/<head>/<body> HostSingletons on initial
mount. release/acquireSingletonInstance strip every attribute off the live
node and re-apply only React's props, wiping the script-seeded class.

Confirmed via published-canary bisect (canary.2 good, canary.3 bad) and a
crossover swap of only the vendored React bundle (isolates the cause to React,
not Next.js code). Exact path: flushPassiveEffects -> commitDoubleInvokeEffects
InDEV -> doubleInvokeEffectsOnFiber -> reappearLayoutEffects ->
acquireSingletonInstance('html').

Fix belongs upstream in React (make singleton release/acquire a no-op during
the dev double-invoke); validated locally by guarding both paths. Dev
workaround: reactStrictMode: false. See NOTES.md.

- Harden the repro test to gate its assertion on a post-hydration effect so it
  cannot false-pass before the strip.
- Add NOTES.md with the full root-cause writeup, verdict, and workaround.
parent 4b598a56
# `<html>` class stripped after hydration in `next dev` — root cause
## Symptom
An inline `<script>` in the root layout `<head>` that seeds a class/attribute
onto `document.documentElement` before React hydrates (the classic
"no flash of incorrect theme" pattern) has that class/attribute **stripped by
React shortly after hydration** — but only in `next dev`. Production is
unaffected. It works in 16.2.11 and regressed in the 16.3 line.
Reported as: "Next.js 16.3.0-preview.9 removes a localStorage-seeded `<html>`
class after hydration … same code works on 16.2.11. Root-layout reconciliation
issue?"
## Verdict
**Real, confirmed dev-only regression — not a non-issue.** It is not a bug in
Next.js application/reconciliation code; it comes from the **vendored React
reconciler** and only manifests because the App Router enables React
StrictMode by default in dev.
## How it was pinned down
- Reproduced with a MutationObserver: attributes are added by the script, then
reset to empty by a React commit on the **same** `<html>` node after
hydration (`["dark|1","|null"]`).
- Matrix (published packages):
| Version | prod | dev |
| ---------------- | ---- | ------------ |
| 16.2.11 | ok | ok |
| 16.3.0-preview.9 | ok | **stripped** |
- Bisected published canaries: **canary.2 = good, canary.3 = bad.**
- The only client/React change in that range that affects a plain app is the
vendored React upgrade **#92945**
(`19.3.0-canary-fef12a01-20260413` → `da9325b5-20260417`).
- Crossover experiment (holding Next.js code constant, swapping only the
vendored React bundle) confirmed causation:
- canary.3 Next + canary.2 React → **good**
- canary.2 Next + canary.3 React → **bad**
## Mechanism (exact call path)
```
flushPassiveEffects
→ commitDoubleInvokeEffectsInDEV (React StrictMode dev-only)
→ doubleInvokeEffectsOnFiber (simulated unmount → remount)
→ disappearLayoutEffects → releaseSingletonInstance(<html>) // strips attrs
→ reappearLayoutEffects → commitHostSingletonAcquisition
→ acquireSingletonInstance("html") // strips attrs, re-applies only React's props
```
- `<html>`/`<head>`/`<body>` are React **HostSingletons**. Acquiring/releasing
one removes every attribute on the live DOM node and re-applies only the
props in React's vdom. The root layout renders no `className` on `<html>`, so
the script-seeded class/attribute is wiped.
- The App Router wraps the app in `<React.StrictMode>` by default in dev
(`__NEXT_STRICT_MODE_APP` defaults to `true`; see
`packages/next/src/build/define-env.ts`). StrictMode's dev "double-invoke
effects" simulates unmount+remount on initial mount; the upgraded React now
reaches the **root** `<html>` singleton during that simulation.
- Both React versions contain the singleton release/acquire code; the upgrade
changed the fiber-flag gating (added bit `2^27`) so the double-invoke now
traverses down to the root singleton on initial mount, which it did not
before. Production never runs double-invoke, so it is unaffected.
## Fix
The correct fix is **upstream in React**: host-singleton release/acquire should
be a no-op during StrictMode's dev double-invoke (the node never actually left
the document, so its live attributes must be preserved). This was validated
locally by guarding `releaseSingletonInstance` and `acquireSingletonInstance`
to skip the destructive attribute strip while the double-invoke is active —
with StrictMode on, the seeded class then survives.
Because Next.js only vendors React's compiled output (synced via
`pnpm sync-react`), there is no correct Next.js application-code fix; the change
must land in React and be pulled in via a React sync. Do **not** disable the
default StrictMode or hand-edit the vendored bundle as a "fix".
## Workaround (users, dev only)
Set `reactStrictMode: false` in `next.config.js` — verified to stop the strip.
Production is not affected regardless.
## About this test
`html-class-hydration.test.ts` asserts the **correct** behavior (the seeded
class survives hydration). It therefore **fails on current HEAD** (it reproduces
the bug) and will pass once the upstream React fix is vendored — or today with
`reactStrictMode: false`.
'use client'
import Link from 'next/link'
import { useEffect, useState } from 'react'
export default function Page() {
const [hydrated, setHydrated] = useState(false)
useEffect(() => {
// Runs after hydration + the dev-only StrictMode double-invoke of effects.
// By the time this commits, any post-hydration reset of <html> has happened.
setHydrated(true)
}, [])
return (
<main>
<p id="home">home</p>
{hydrated ? <span id="hydrated" /> : null}
<Link href="/second" id="to-second">
to second
</Link>
......
......@@ -6,24 +6,18 @@ describe('html-class-hydration', () => {
files: __dirname,
})
// Regression test for a dev-mode issue where a class seeded onto <html> by
// an inline script (before hydration) was stripped shortly after hydration.
// Regression test: a class seeded onto <html> by an inline script before
// hydration (the classic no-flash-of-incorrect-theme pattern) must survive
// hydration. A dev-only React StrictMode double-invoke of effects was
// re-acquiring the <html> host singleton after hydration, which strips every
// attribute the script added.
it('keeps a script-seeded <html> class after hydration', async () => {
const browser = await next.browser('/')
await browser.elementById('home')
await retry(async () => {
expect(
await browser.eval(
'document.documentElement.getAttribute("data-seeded")'
)
).toBe('1')
expect(
await browser.eval('document.documentElement.className')
).toContain('dark')
})
// Wait until the page's post-hydration effect has run. In dev this is after
// the StrictMode double-invoke, so any reset of <html> has already happened.
await browser.elementById('hydrated')
// Ensure it stays put after post-hydration effects/commits have settled.
await retry(async () => {
expect(
await browser.eval('document.documentElement.className')
......@@ -38,7 +32,7 @@ describe('html-class-hydration', () => {
it('keeps the class across a client-side navigation', async () => {
const browser = await next.browser('/')
await browser.elementById('home')
await browser.elementById('hydrated')
await browser.elementById('to-second').click()
await browser.elementById('second')
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment