To fix both the hydration error and the annoying "light theme flicker" (flash of unstyled content), you need to read localStorage and inject the dark mode class before the browser paints the initial HTML page.
Since Next.js server-renders your code, any standard React state initialization based on localStorage will fail on the server, causing a mismatch. The solution is to use a blocking script with the dangerouslySetInnerHTML attribute inside your root layout.tsx.
The Solution
Update your root app/layout.tsx file to include an inline script right inside the <head> tag:
Why this works:
suppressHydrationWarning: You must add this attribute to the<html>tag. It tells Next.js not to throw an error when attributes (likeclassName="dark") differ between the server and the client during the initial HTML paint.- Blocking Script Execution: By placing the raw stringified function inside
<head>, the browser encounters it and runs it synchronously before rendering the body element. This instantly applies Tailwind's.darkclass, eliminating the white flash. - No Delays: The script executes before React even boots up or runs your hooks, completely bypassing the hydration mismatch pipeline for the theme state.