Prerender build fails when component accesses window during static generation

Resolution

StencilJS does not provide a built-in production-build option or configuration flag to automatically shim or polyfill browser globals (such as window or document) during the prerendering process. Manual guarding is the only supported approach to prevent build-time failures when components are executed in the Node.js environment during static generation.

Execution Context and Constraints

During prerendering, StencilJS executes your component logic within Node.js to generate static HTML. Because Node.js lacks a DOM, any direct reference to window, document, or localStorage outside of a browser-safe context will throw a ReferenceError and crash the build process.

It is important to note that @Component encapsulation modes (Shadow DOM or Scoped DOM) only affect how the browser renders the final output; they do not isolate the Node.js execution environment from these missing globals during the build phase.

Safe Lifecycle Hooks

To ensure browser-specific logic only runs on the client, use the following strategies:

• componentDidLoad(): This is the most reliable hook for browser-only logic. It does not execute during the static prerendering phase, making it the ideal location for initializing third-party libraries or accessing the window object.
• Manual Guards: For logic that must reside in the render() method or the constructor, use a type check:

  if (typeof window !== 'undefined') {
        // Browser-safe logic here
      }

Verification Steps

You can verify the environment behavior using these scoped tests:

1. Trigger Failure: Place console.log(window.location.href) directly inside the render() method. Run your build command with prerendering enabled; the build should fail.
2. Verify Success: Move that same console.log into componentDidLoad(). The build should now complete successfully, and the log will only appear in the browser's developer console at runtime.

Diagnostic Note: To provide more specific guidance, please confirm which version of StencilJS you are using, as lifecycle behavior is subject to change across major versions.