Ошибка `window is not defined` означает, что код дошёл до окружения без браузера. В App Router страницы и layouts по умолчанию являются Server Components, поэтому обращение к `window`, `document`, `localStorage` или `navigator` в их модульной области либо render-функции закономерно падает.

Первый безопасный шаг — не превращать всю страницу в Client Component. Найдите минимальный интерактивный остров: выбор темы, карта, редактор или виджет. Данные и секреты оставьте на сервере, а браузерную часть вынесите в отдельный файл с `use client`.

Момент выполнения определяет исправление

Где читается APIНаблюдаемый признакРабочее решение
Верхний уровень модуляПадение уже при import/buildКлиентская обёртка или dynamic import
Render компонентаОшибка при SSR либо несовпадение HTMLОдинаковый первый render, чтение после mount
Обработчик событияРаботает только после кликаClient Component с use client
useEffectAPI читается после hydrationПодходит для состояния, нужного только браузеру
Серверная функцияНет доступа к DOM по замыслуПередать данные, а не браузерный объект

Условие `typeof window !== "undefined"` помогает только там, где модуль уже удалось импортировать. Если зависимость обращается к DOM на верхнем уровне, проверка в компоненте выполняется слишком поздно. Поэтому в stack trace важен самый ранний пользовательский импорт, а не только строка финального ReferenceError.

Клиентская граница начинается в отдельном файле

// app/product/[id]/page.tsx — Server Component
import ProductGallery from './product-gallery'

export default async function Page({ params }) {
  const product = await getProduct((await params).id)
  return <ProductGallery images={product.images} />
}

// app/product/[id]/product-gallery.tsx
'use client'

import { useEffect, useState } from 'react'

export default function ProductGallery({ images }) {
  const [wide, setWide] = useState(false)
  useEffect(() => {
    const media = window.matchMedia('(min-width: 900px)')
    const sync = () => setWide(media.matches)
    sync(); media.addEventListener('change', sync)
    return () => media.removeEventListener('change', sync)
  }, [])
  return <Gallery images={images} mode={wide ? 'wide' : 'compact'} />
}

Директива ставится до imports. Она задаёт точку входа клиентского графа: все импорты ниже этой границы попадут в клиентский bundle. Поэтому перенос общего layout наверх быстро устраняет ошибку, но увеличивает JavaScript. Узкая обёртка сохраняет серверные преимущества остальной страницы.

Первый HTML не зависит от ширины экрана

Client Component тоже может участвовать в предварительном HTML первого открытия. Если render сразу ветвится по `window.innerWidth`, сервер и браузер способны построить разную разметку. Стабильнее отдать одинаковую компактную оболочку, а после mount уточнить режим. Ещё лучше — решить чисто визуальную адаптацию CSS media query без JavaScript.

  • Не записывайте объект Window, HTMLElement или функцию в props: граница требует сериализуемых значений.
  • Не передавайте API key в Client Component — его увидит браузерный bundle или запрос.
  • Не читайте localStorage ради начального HTML без состояния-заглушки либо серверного cookie-контракта.
  • Не добавляйте use client в корневой layout только ради одного виджета.
  • Не маскируйте различие suppressHydrationWarning, пока причина не локализована.

DOM-зависимая библиотека получает собственную обёртку

// app/ui/map-client.tsx
'use client'

import dynamic from 'next/dynamic'

const BrowserMap = dynamic(() => import('./browser-map'), {
  ssr: false,
  loading: () => <div aria-busy='true'>Загрузка карты…</div>,
})

export default function MapClient(props) {
  return <BrowserMap {...props} />
}

Отключение SSR оправдано, когда пакет принципиально не умеет загружаться без DOM. Это не универсальная заплатка: контент виджета появится позже, а его loading-state станет частью пользовательского опыта. Если библиотека обращается к браузеру только в методе и умеет безопасно импортироваться, обычного Client Component часто достаточно.

Проверка охватывает build, HTML и навигацию

  1. Запустить production build и сохранить первый stack trace без повторных обёрток.
  2. Открыть URL прямым запросом и убедиться, что сервер вернул содержательный HTML.
  3. Проверить консоль на ReferenceError и hydration warnings.
  4. Перейти на страницу клиентской навигацией и повторить действие виджета.
  5. Сравнить размер клиентских chunks до и после переноса границы.
  6. Отключить JavaScript и убедиться, что серверная часть страницы остаётся понятной.

Исправление принято, когда серверный build не импортирует DOM-зависимый код, первый HTML и первый клиентский render совместимы, виджет оживает после hydration, а лишняя часть страницы не переехала в client bundle. Для разбора подготовьте stack trace, дерево импортов, версии Next.js/React и минимальную пару server/client файлов.

Проверенные источники