Next.js › Custom App & Document in Pages Router

Why can you not use React hooks like useState inside the custom Document component?

Intermediate

Answer

The custom Document component only renders on the server to generate the initial HTML shell, and it never re-renders on the client, so hooks that manage interactive client side state have no purpose there and are not supported in this file.

// This would not work as expected in _document.js
// because Document only runs once on the server
function Document() {
  // useState is not appropriate here
}

Real-world example A developer tries adding a useState hook inside _document.js to track a loading flag, but quickly learns this file only builds the static page shell and moves that logic into _app.js instead.

Common follow-ups: Where should client side interactive logic be placed instead?;What lifecycle does the Document component follow compared to a normal page?

Client Components & Hydration;Layouts & Templates