How do you write a JavaScript module that uses browser-only globals such as `document` but is also imported by server code running in Node, so it does not crash on either host?

## Why import time is the dangerous moment A module body executes exactly once, when it is first evaluated. If a browser-only global is read there, the read happens as a consequence of somebody typing `import './widget.js'` — including the server that renders your page. ```js // widget.js — breaks any Node import of this file const initialWidth = window.innerWidth; // ReferenceError in Node document.addEventListener('click', onClick); export function render() { /* ... */ } ``` The consumer did nothing browser-specific; it merely imported a function. Because module evaluation propagates, the failure is not local: the importing module fails too, and so does its importer. That is why "it crashes on the server" so often points at a single stray top-level line. The fix is structural, not defensive: ```js // widget.js — safe to import anywhere let initialWidth = 0; export function mount(container) { if (typeof document === 'undefined') return; // no host to mount into initialWidth = window.innerWidth; container.addEventListener('click', onClick); } ``` Now importing is inert and only `mount()` requires a browser. ## Why the guard must use typeof An identifier that resolves to no binding throws on **reference**, before any operator or comparison runs: ```js if (window) {} // ReferenceError in Node if (window !== undefined) {} // ReferenceError in Node if (window?.document) {} // ReferenceError in Node — optional chaining does not help if (typeof window !== 'undefined') {} // safe if (globalThis.window) {} // also safe: a missing property is just undefined ``` Optional chaining is the trap people fall into most. `?.` protects you from a value that is `null` or `undefined`; it does nothing about a binding that does not exist. Reading through `globalThis` works because property access on an existing object returns `undefined` for a missing key. ## Detect the capability, not the host `typeof window !== 'undefined'` answers "is there a `window`?", which is not quite "am I in a browser" and definitely not "can I do the thing I want". Ask directly about the API you are about to call: ```js const canObserve = typeof IntersectionObserver === 'function'; const canStore = typeof localStorage !== 'undefined'; ``` Capability checks stay correct as runtimes evolve and as your code runs in contexts that are neither a plain tab nor a plain server process. They also read better: the condition names the reason for the branch. ## Give both hosts something sensible to do A guard that silently returns is fine for effects (mounting, focusing, measuring). For values, decide deliberately what the server should produce, because whatever you return is what gets rendered: ```js export function getTheme() { if (typeof localStorage === 'undefined') return 'light'; // server default return localStorage.getItem('theme') ?? 'light'; } ``` Be aware that a server default which disagrees with the browser value is exactly how hydration mismatches appear; the honest options are to pick a stable default and correct it after the page is interactive, or to pass the real value from the server explicitly. ## When the dependency is the problem Sometimes it is not your code but a package that reads `document` in its own module body. A static `import` of it is enough to break the server, no matter how carefully you guard your own calls. The answer is to keep it out of the static graph and pull it in only on the branch that has a browser: ```js export async function showChart(el) { if (typeof document === 'undefined') return; const { default: Chart } = await import('some-dom-only-lib'); new Chart(el); } ``` Because the specifier is only resolved when that line runs, the server never evaluates the offending module. ## Testing that it holds The cheap regression test is to import the module in a Node context and assert that nothing throws — no DOM emulation, no browser. Anything that fails that test has a host access at evaluation time. Pair it with a browser-side test that the guarded function does its work when a document exists. Two tiny tests keep a whole class of production-only failures from recurring. ## The summary a candidate should give Imports are inert; effects are explicit; guards use `typeof` and name a capability; browser-only dependencies are loaded lazily from inside the browser branch. That is the whole discipline, and it is why the code survives both hosts without a pile of environment flags.