use client doesn't mean browser-only

nextjsreactssr

I thought use client meant "this only runs in the browser."

It doesn't. It marks a boundary in the module graph: Next.js puts the file, and everything it imports, into the client bundle, the JavaScript sent to the browser. Server Component code stays on the server. Being in the client bundle does not stop the server from rendering the component: on a direct visit, the server still renders it to HTML first, at build time for a static page or per request for a dynamic one, and the browser then runs the bundle to hydrate that HTML. On a later client-side navigation, the server sends only the RSC Payload and no HTML, so Next.js renders the component in the browser alone.


The crash that taught me

This broke during next build:

'use client'
import { useEffect } from 'react'
 
function MyComponent() {
  useEffect(() => {}, [window])  // ReferenceError: window is not defined
  return <div />
}

This worked fine:

'use client'
import { useEffect } from 'react'
 
function MyComponent() {
  useEffect(() => {
    console.log(window.scrollX)  // no crash
  }, [])
  return <div />
}

Both snippets are use client. The first puts window in the dependency array, the second inside the callback.

The 2024 snippets had no import { useEffect }. Without it, every Next.js version fails earlier with useEffect is not defined, so the import is added here.

The first snippet, rerun in October 2026 on several Next.js versions in a minimal App Router project:

Next.jsnext buildnext dev
13.4 to 14.1ReferenceError: window is not definedsame error
14.2 to 15.5passes500, same error
16 (Turbopack by default)ReferenceError: window is not defined500, same error

Versions actually run: 13.4.19, 13.5.6, 14.0.4, 14.1.4, 14.2.0, 14.2.35, 15.0.8, 15.1.12, 15.3.9, 15.5.12, 16.4.3. On 16.4.3, next build --webpack passes.

From 14.2 (April 2024), a production webpack build turns on experimental.optimizeServerReact by default. It removes useEffect calls from the server bundle, dependency array included, so [window] is never evaluated while prerendering. next dev and Turbopack builds keep the call. To confirm the setting is the cause, 14.2 and 15.5 were rebuilt with it off, and the build failed. With it turned on in 14.1, the build passed.

The setting does not remove every form:

  • import { useEffect } from 'react': it checks the dependency array. If the array contains a function call, such as [getSize()], it keeps the whole useEffect, because that function may have side effects. The kept getSize() reads window.innerWidth during prerender, the server has no window, so the build fails.
  • import React from 'react' with React.useEffect(...): it does not check the dependency array and always removes the call. So even [getSize()] builds.
  • import * as React from 'react' with React.useEffect(...): it does not recognize the call as useEffect and keeps it. So even [window] fails the build.

14.2.0, 14.2.35, 15.0.8, 15.3.9 and 15.5.12 all give the results above. The rules are in the optimize_server_react source (linked in References).


What's actually happening

On a direct visit, a use client component lives two lives:

  1. Server -- Node.js runs your render function, produces HTML. useState initializer runs. The dependency array literal is evaluated, because it is an argument to the useEffect(...) call inside the render function. But useEffect callbacks don't run: React's docs say Effects only run on the client.
  2. Browser -- HTML shows up first. Then hydration attaches event handlers to that HTML, and from then on setState updates the screen. useEffect callbacks run now.

The dependency array [window] is evaluated during step 1. Node.js hits window, doesn't find it, throws.

The callback () => { console.log(window.scrollX) } is just a function definition during step 1. Node.js sees it but never calls it. It only runs in step 2.


Where is window safe?

LocationServer runs it?window safe?
Top-level variableYesNo
useState initializerYesNo
useEffect dependency arrayYesNo
useEffect callbackNoYes
Event handlerNoYes

The dependency array row says "Yes" because when the server render runs the component function, the arguments of the useEffect(...) call, [window] included, are computed first. On Next.js 14.2 to 15.5, though, a default next build removes a call like useEffect(() => {}, [window]) at compile time, so the server render never reaches that line, which is why the build passes on those versions.

One escape hatch works at the top level:

const isBrowser = typeof window !== 'undefined'

typeof on an undeclared variable returns "undefined" instead of throwing. That's a JavaScript thing, not a React thing.

Use it to guard a call, not to render different HTML. With {isBrowser ? <A /> : <B />}, the server renders B because isBrowser is false, and the browser's first render produces A. Hydration then reports a mismatch: React requires the server HTML to match the browser's initial render output. Guarding a call is fine when the call does not change what renders, as in if (isBrowser) console.log(window.location.href): on the server isBrowser is false and console.log is never called; in the browser it only prints a line, so both sides render the same HTML.

If a component cannot be rendered on the server at all, Next.js has an opt-out: next/dynamic with { ssr: false }, which skips the server render for that Client Component. The option only works inside a Client Component; using it in a Server Component is an error.


The mental model

use client doesn't mean "skip the server." It puts the file and its imports into the client bundle. On a direct visit, the browser uses that JavaScript to hydrate the server's HTML; on a client-side navigation there is no HTML, and the component renders in the browser alone.

Effect callbacks (useEffect, and useLayoutEffect too) and event handlers never run on the server. On a direct visit without ssr: false, the component's function body runs on the server first, and the useState initializer and dependency arrays inside it are evaluated with it. next dev always shows that error; whether next build shows it depends on the Next.js version (see the table above).


References