How to Fix Next.js 16 Hydration Errors Once and For All

// BAD — returns different values, causes hydration error
function BadWidth() {
  const width = typeof window !== 'undefined' ? window.innerWidth : 1024;
  return <div>{width}</div>; // server:1024 vs client:1440
}

// GOOD — defer to client with useState
'use client';
import { useState, useEffect } from 'react';

export function SafeWidth() {
  const [width, setWidth] = useState<number | null>(null);
  useEffect(() => setWidth(window.innerWidth), []);
  if (width === null) return <div suppressHydrationWarning />;
  return <div>{width}px</div>;
}

// GOOD — for localStorage
 export function useLocalStorage(key: string, fallback: string) {
  const [value, setValue] = useState(fallback);
  useEffect(() => {
    try { setValue(localStorage.getItem(key) ?? fallback); } catch {}
  }, [key, fallback]);
  return value;
}

'use client';
import { useState, useEffect, useId } from 'react';

// WRONG
export function BrokenTime({ts}:{ts:number}){
  const mins = Math.floor((Date.now()-ts)/60000);
  return <span>{mins}m ago</span>; // mismatch
}

// CORRECT
export function SafeTime({ts, serverNow}:{ts:number, serverNow:number}){
  const [now, setNow] = useState<number|null>(null);
  useEffect(()=>{ setNow(Date.now()); const id=setInterval(()=>setNow(Date.now()),60000); return ()=>clearInterval(id);},[]);
  const effective = now ?? serverNow;
  const mins = Math.floor((effective-ts)/60000);
  return <span suppressHydrationWarning>{mins<1?'now':`${mins}m`}</span>;
}

// CORRECT IDs
export function Label(){
  const id = useId(); // deterministic across server/client
  return <label htmlFor={id}>Name</label>;
}

// BAD — PPR shell has no user data
export default async function Page(){
  const user = await getUser(); // runs during prerender
  return <div>Welcome {user.name}</div>; // server: '' vs client: 'John'
}

// GOOD — wrap dynamic data in Suspense
import { Suspense } from 'react';
export default function Page(){
  return (
    <div>
      <Suspense fallback={<div>Welcome ...</div>}>
        <UserName />
      </Suspense>
    </div>
  );
}
async function UserName(){
  const user = await getUser();
  return <>Welcome {user.name}</>;
}

// Disable PPR per route if needed
export const experimental_ppr = false;

import type { NextConfig } from 'next';
const nextConfig: NextConfig = {
  compiler: {
    styledComponents: { ssr: true, displayName: true, minify: true }
  }
};
export default nextConfig;

// server-component.tsx
export async function ServerProfile({id}:{id:string}){
  const user = await db.user.findUnique({where:{id}});
  return <ClientProfile name={user.name} joinedAt={user.createdAt.toISOString()} />;
}

// client-profile.tsx
'use client';
export function ClientProfile({name, joinedAt}:{name:string, joinedAt:string}){
  const [formatted, setFormatted] = useState('');
  useEffect(()=> setFormatted(new Date(joinedAt).toLocaleDateString()), [joinedAt]);
  return <div>{name} <time suppressHydrationWarning>{formatted||joinedAt}</time></div>;
}

import Script from 'next/script';
export function Analytics(){
  return <Script src="https://..." strategy="afterInteractive" />;
}

export function withHydrationDebug<P>(Comp: React.ComponentType<P>, name:string){
  return (p:P)=>{ if(typeof window!=='undefined') console.log(`[${name}]`, p); return <Comp {...p}/> }
}