window is not defined in Next.js: dove nasce e come si corregge

Risposta breve: durante il render sul server window non esiste. L'errore compare ogni volta che un modulo legge window all'import o un componente lo legge nel corpo del render. Sposta l'accesso in useEffect, oppure importa il componente solo sul client.

Il messaggio esatto

ReferenceError: window is not defined
    at Object. (/app/lib/analytics.js:3:12)
    at Module._compile (node:internal/modules/cjs/loader:1358:14)

La riga indicata è quasi sempre al livello superiore del file, non dentro una funzione. È il dettaglio che distingue un errore di rendering da un errore di import.

Perché succede

Next.js esegue il codice dei Server Component e il prerender delle pagine in Node. Node non ha window, document, localStorage né navigator. Un modulo che inizializza un client analytics al momento dell'import viene eseguito anche in quel contesto.

La correzione, tre livelli

Se il valore serve solo dopo l'interazione, useEffect è sufficiente: gira solo nel browser e non partecipa al prerender.

"use client";
import { useEffect, useState } from "react";

export function Width() {
  const [width, setWidth] = useState(0);
  useEffect(() => {
    const onResize = () => setWidth(window.innerWidth);
    onResize();
    window.addEventListener("resize", onResize);
    return () => window.removeEventListener("resize", onResize);
  }, []);
  return {width || "—"};
}

Se il componente intero dipende dal browser, una mappa, un editor, una canvas, caricalo senza SSR. In App Router ssr: false è consentito solo dentro un Client Component.

"use client";
import dynamic from "next/dynamic";

const Editor = dynamic(() => import("./editor"), { ssr: false });

export function EditorShell() {
  return ;
}

Se l'errore arriva da una libreria, la via più pulita è una guardia esplicita più un import dinamico: il modulo non viene valutato finché non serve.

Quando la correzione non funziona

typeof window !== "undefined" evita il crash ma non è una soluzione: il valore calcolato sul server resta diverso da quello del client, e ottieni un hydration mismatch al posto del ReferenceError. Allo stesso modo, spostare l'accesso in una funzione che viene chiamata durante il render non cambia nulla: conta quando viene eseguita, non dove è scritta.

Come prevenirlo

• Tieni le API del browser in un solo modulo, sempre importato dinamicamente.
• Aggiungi la regola lint che vieta window nei file senza "use client".
• Testa la build, non solo il dev server: il prerender è il punto in cui il problema emerge.

Dove continuare

Per partire da codice già eseguibile: componenti React, una dashboard con shell e tutti i blocchi con preview. Le guide collegate sono App Router, struttura e confini client/server e quanto pesa una libreria UI; il confronto utile è copy-paste o headless.