Docusaurus "Can't render static file" (window/useState) in CI

By Daniel Zoghalchali·Latchkey

Docusaurus prerenders pages to static HTML on the server, where window and document do not exist. A component that touches them at render time throws and the build cannot render that file.

What this error means

docusaurus build fails with "Can't render static file for pathname ..." and an underlying "ReferenceError: window is not defined" or "document is not defined".

[ERROR] Docusaurus server-side rendering could not render static page with path /.
ReferenceError: window is not defined

Common causes

Browser globals accessed during render

A component reads window or document in the render body, which runs during server-side prerendering where those globals are undefined.

A browser-only library imported at module top level

A package that assumes a browser is imported and executed at build time, throwing before the page can render.

How to fix it

Guard browser code to client only

1. Move window/document access into an effect that runs only in the browser.
2. Or wrap the component in <BrowserOnly> so it does not render during SSR.
3. Rebuild to confirm prerendering succeeds.

import { useEffect, useState } from 'react';
useEffect(() => { setWidth(window.innerWidth); }, []);

Use ExecutionEnvironment or BrowserOnly

Render browser-only UI with Docusaurus BrowserOnly, or gate code with ExecutionEnvironment.canUseDOM.

import BrowserOnly from '@docusaurus/BrowserOnly';

<BrowserOnly>{() => <Chart />}</BrowserOnly>

How to prevent it

• Access window/document only inside effects or BrowserOnly.
• Gate browser-only imports with ExecutionEnvironment.canUseDOM.
• Run docusaurus build in CI so SSR errors surface before deploy.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation