Diagnosing and Fixing StencilJS SSR Hydration Mismatch

Recognizable Condition

When a Stencil app built with stencil build --ssr loads in the browser you may see a brief flicker followed by a console warning:

Stencil: Hydration mismatch

or a stack trace mentioning Cannot read property … of undefined during the client takeover. The page still renders, but the component tree is rebuilt from scratch, which hurts performance and can break stateful logic.

Common Causes

• Missing hydration marker – the server‑generated HTML lacks the <!-- client-hydrate --> comment, so Stencil thinks the DOM is “stale”.
• Browser‑only references in component state – accessing window, document, or other globals during componentWillLoad or render causes a crash on the server.
• Non‑serializable props – Maps, Sets, or objects with circular references cannot be stringified into the SSR payload, so the client receives incomplete data.
• Hydration marker format mismatch – upgrading from Stencil 2.x to 3.x without updating the root index.html template can generate a different marker syntax.

Diagnostic Table

Client consoleComponent stateSSR payloadTemplate version

Check	What to Look For	Expected Result
Server output	Open dist/index.html after stencil build --ssr	Contains <!-- client-hydrate --> comment immediately after <body>
Open DevTools, reload page	No “Hydration mismatch” warning
Inspect component instance in Elements panel	State properties defined, no undefined errors
View network request for app.js and app.css	Payload contains serializable JSON
Check src/index.html for <!-- client-hydrate --> marker	Matches the version used by your Stencil build

Ordered Checks & Fixes

1. Verify the hydration marker
   • Run npx stencil build --ssr in your project root.
   • Open dist/index.html and search for <!-- client-hydrate -->.
   • If missing, update src/index.html to include the comment just after <body> and rebuild.
2. Guard browser globals
   • Wrap any window or document usage in a runtime check:

     if (typeof window !== 'undefined') {
       // safe to use
     }

   • Prefer componentWillLoad for side‑effects that only run on the client.
3. Serialize component props
   • Replace Map or Set with plain arrays or objects before passing them as props.
   • If you must use a complex type, provide a toJSON method or convert to a serializable shape in componentWillLoad.
4. Align SSR and client templates
   • When upgrading to Stencil 3.x, generate a fresh index.html with stencil generate or copy the template from the new package.
   • Ensure the <!-- client-hydrate --> comment matches the new marker format.
5. Re‑hydrate after fixes
   • Clear browser cache or use incognito mode.
   • Reload the page and confirm the console shows no hydration warnings.
   • Use the Elements panel to verify that the component tree remains the same after load.

Concrete Example

Suppose you have a <my-widget> component that reads the viewport width on load:

export class MyWidget {
  viewport: number;

  componentWillLoad() {
    this.viewport = window.innerWidth; // ❌ will crash on SSR
  }

  render() {
    return {this.viewport};
  }
}

Fix:

export class MyWidget {
  viewport: number;

  componentWillLoad() {
    if (typeof window !== 'undefined') {
      this.viewport = window.innerWidth;
    }
  }

After rebuilding, dist/index.html will contain the hydration marker, and the console will no longer emit the mismatch warning.

Escalation Criteria

• If the hydration warning persists after the above steps, check that stencil.config.ts has ssr: true and that buildDocs: false (docs builds can interfere with SSR output).
• Verify that the build output is served from the correct directory (e.g., /dist vs. /build) – a mismatch can cause the client to load a stale app.js that doesn’t match the server HTML.
• If the issue is limited to a single component, isolate it by creating a minimal reproduction and opening a GitHub issue against the Stencil repository.

Limitations & Practical Checks

• SSR hydration mismatches are only reproducible in a browser environment; Node.js unit tests won’t surface them.
• Some third‑party libraries (e.g., D3, Chart.js) internally access window and may need to be loaded lazily via import() inside a componentWillLoad guard.
• After any change, run npx stencil build --ssr --dev and serve with npx stencil serve --ssr to quickly verify the result.