Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A Leaflet map crashes the Next.js build or shows up broken

ErrorReferenceError: window is not defined

Short answer

Leaflet reads window as soon as it loads, and Next.js renders Client Components on the server first, where window does not exist. Load the map component with next/dynamic and ssr set to false, inside a Client Component. If the map then shows but looks broken, import leaflet.css and give the container a height.

  • Applies to Next.js 15, Next.js 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the stack trace of the error. If it starts inside leaflet or react-leaflet while a page renders, the map is being imported on the server.

    npm run build 2>&1 | grep -n -B2 -A8 "window is not defined"
  2. 2Match what you see, then jump to its fix

    1. 1ReferenceError: window is not defined during next build or on the first page loadThe map component is rendered on the serverFix
    2. 2An error says ssr: false is not allowed with next/dynamic in Server Componentsssr: false is used in a Server ComponentFix
    3. 3No error, but the map area is empty or has no heightThe map loads but is blankFix

What does the error look like?

  • ReferenceError: window is not defined
  • window is not defined

Cause 1 of 3

The map component is rendered on the server

1Check

Client Components are prerendered to HTML on the server. Browser APIs such as window are not available there, so any module that touches window at import time fails.

grep -rn "react-leaflet\|from 'leaflet'" app components src 2>/dev/null

2Fix

Import the map with next/dynamic and ssr: false. The option works only in a Client Component, so put the call in a file that starts with 'use client'.

// app/map-loader.jsx
'use client'

import dynamic from 'next/dynamic'

const Map = dynamic(() => import('../components/Map'), {
  ssr: false,
  loading: () => <p>Loading map...</p>,
})

export default function MapLoader() {
  return <Map />
}

3Verify

The build finishes and the page renders the map in the browser.

npm run build

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 3

ssr: false is used in a Server Component

1Check

The option is not supported in Server Components, so a dynamic call in a plain page.js without 'use client' fails.

head -n 3 app/page.js

2Fix

Move the dynamic import into a small Client Component, as in the loader above, and render that component from the page.

// app/page.js (Server Component)
import MapLoader from './map-loader'

export default function Page() {
  return <MapLoader />
}

3Verify

The error is gone on the next build.

npm run build

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 3

The map loads but is blank

1Check

Leaflet needs its stylesheet and a container with a height. A div with no height has nothing to draw into.

grep -rn "leaflet.css\|MapContainer" app components src 2>/dev/null

2Fix

Import the stylesheet in the map component and give the container an explicit height.

// components/Map.jsx
'use client'

import 'leaflet/dist/leaflet.css'
import { MapContainer, TileLayer } from 'react-leaflet'

export default function Map() {
  return (
    <MapContainer center={[51.505, -0.09]} zoom={13} style={{ height: 400 }}>
      <TileLayer
        attribution="&copy; OpenStreetMap contributors"
        url="https://tile.openstreetmap.org/{z}/{x}/{y}.png"
      />
    </MapContainer>
  )
}

3Verify

Reload the page: the tiles fill a 400 pixel tall box.

npm run dev

Confirmed by leafletjs.com

Did this fix it?

How do I stop it coming back?

  • Treat every browser-only library the same way: load it in a Client Component with ssr: false, or touch it inside useEffect.
  • Set the map container height in CSS or inline style when you create the component.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

next/link throws React.Children.only on its children

Error: React.Children.only expected to receive a single React element child.

React.Children.only accepts exactly one React element and throws for anything else, including an array with one item.

3 causes, each with a fix

Web apps

Hydration failed after adding next-themes dark mode

Console reports a server and client mismatch on the html element

next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.