React 19 + Next.js 16: How Three Lint Errors Caused a Hydration Mismatch

After finishing the site-wide color system refactor, npm run lint was green and tsc reported no errors. But when I opened an article page in dev mode, the Next.js overlay showed a red error badge. The console reported a hydration mismatch:

A tree hydrated but some attributes of the server rendered HTML didn't match the client properties.

The diff pointed at an Expressive Code <pre> element — the server render lacked tabindex="0" and role="region", while the client render had them.

This post documents how I traced the issue through three seemingly unrelated lint errors and fixed the hydration warning along the way.

#The three lint errors

npm run lint was reporting three issues:

1. FilterBar.tsx: the count prop was defined but never used.
2. TocNav.tsx: synchronous setMounted(true) inside useEffect.
3. ArticleImageProvider.tsx: reading slidesRef.current during render.

The first two looked like quality issues; the third was a pattern React explicitly discourages. None of them lived inside Expressive Code, yet fixing all three made the hydration mismatch disappear.

#Pitfall 1: Redundant props in FilterBar

FilterBar accepted both count and countLabel:

1
export default function FilterBar({
2
  filter,
3
  onChange,
4
  count,
5
  options,
6
  countLabel,
7
}: {
8
  filter: string
9
  onChange: (value: string) => void
10
  count: number
11
  options: readonly FilterOption[]
12
  countLabel: string
13
}) {
14
  // ...
15
  <span className="ml-auto text-[13px] text-dim">{countLabel}</span>
16
}

Callers already passed a formatted count string via countLabel, so the component never needed count. This API redundancy does not directly cause hydration, but it adds unnecessary variance between server and client prop resolution — especially when countLabel is generated through i18n.

The fix was simple: drop count and let FilterBar only worry about displaying text.

1
export default function FilterBar({
2
  filter,
3
  onChange,
4
  options,
5
  countLabel,
6
}: {
7
  filter: string
8
  onChange: (value: string) => void
9
  options: readonly FilterOption[]
10
  countLabel: string
11
}) {
12
  // ...
13
}

Both call sites in PostList.tsx and PhotoGrid.tsx were updated.

#Pitfall 2: Mounted detection via useEffect

TocNav renders a fixed TOC into document.body through createPortal, so it must wait for client mount. The original implementation looked like this:

1
const [mounted, setMounted] = useState(false)
2

3
useEffect(() => {
4
  setMounted(true)
5
}, [])
6

7
if (!mounted) return null
8

9
return createPortal(gutter, document.body)

React 19's eslint rule react-hooks/set-state-in-effect flags this because a synchronous setState inside an effect causes a cascading render: first render with mounted=false, effect fires, immediate second render with mounted=true.

The better tool is useSyncExternalStore, which React designed exactly for "subscribing" to an external source — here, the fact that we are on the client:

1
import { useSyncExternalStore } from 'react'
2

3
const mounted = useSyncExternalStore(
4
  () => () => {},
5
  () => true,
6
  () => false,
7
)

The three arguments are:

• subscribe: no-op, because we do not need to listen for changes.
• getSnapshot: returns true on the client.
• getServerSnapshot: returns false on the server.

React can now know during SSR that this component should render null, and on the client that it should render the portal — without a second render pass.

#Pitfall 3: Reading a ref during render

ArticleImageProvider registers article images as lightbox slides. The original implementation stored slides in a ref:

1
const slidesRef = useRef<LightboxSlide[]>([])
2

3
const register = useCallback((slide: LightboxSlide) => {
4
  const existing = slidesRef.current.findIndex(s => s.src === slide.src)
5
  if (existing >= 0) return existing
6
  slidesRef.current.push(slide)
7
  return slidesRef.current.length - 1
8
}, [])
9

10
return (
11
  <ArticleImageContext.Provider value={{ register, open }}>
12
    {children}
13
    <PhotoLightbox
14
      slides={slidesRef.current}
15
      // ...
16
    />
17
  </ArticleImageContext.Provider>
18
)

The problem is the last line: slidesRef.current is read during render. React forbids this because refs are not render inputs; reading them produces different snapshots on the server and client.

The fix is to promote slides to state:

1
const [slides, setSlides] = useState<LightboxSlide[]>([])
2

3
const register = useCallback((slide: LightboxSlide) => {
4
  let index = -1
5
  setSlides(prev => {
6
    const existing = prev.findIndex(s => s.src === slide.src)
7
    if (existing >= 0) {
8
      index = existing
9
      return prev
10
    }
11
    index = prev.length
12
    return [...prev, slide]
13
  })
14
  return index
15
}, [])

The returned index is computed inside the state updater, so it stays consistent with React's batching. PhotoLightbox receives the slides state directly, and render no longer touches any ref.

#Why the hydration mismatch disappeared

The original hydration error was attributed to Expressive Code's <pre>, yet the fix lived in three unrelated components. My interpretation:

Hydration compares the entire tree. When a client boundary behaves unstably during the first render — for example, TocNav re-rendering immediately or ArticleImageProvider reading a ref — React can mis-attribute attribute differences further down the tree. The Expressive Code <pre> was likely the symptom; the real issue was unstable client boundaries polluting the hydration diff.

Once those boundaries became deterministic, the hydration path cleared up and Expressive Code's attribute differences stopped triggering a warning.

#Verification

After the fixes:

1
npm run lint && npx tsc --noEmit

Results:

• eslint: 0 errors, 0 warnings
• color audit: All tracked color pairings pass WCAG AA
• TypeScript: no errors

Opening an article page in dev mode now shows a clean Next.js indicator and 0 console errors.

#Takeaways

1. Do not ignore lint errors. The TocNav mounted effect and ArticleImageProvider ref read were "works but wrong" patterns. They do not crash immediately, but they create uncertainty at hydration time.
2. Use useSyncExternalStore for mount detection. It is the React-approved tool and avoids cascading renders.
3. Never read refs during render. Any data needed in render should come from state or props; refs belong in event handlers, effects, or imperative APIs.
4. Hydration errors can have upstream causes. When the console blames component A, inspect the whole client tree for unstable boundaries — the real fix may be elsewhere.