Calculated component style differs between Develop and Build/Serve

[karjanme]

Preliminary Checks

• This issue is not a duplicate. Before opening a new issue, please search existing issues: https://github.com/gatsbyjs/gatsby/issues
• This issue is not a question, feature request, RFC, or anything other than a bug report directly related to Gatsby. Please post those things in GitHub Discussions: https://github.com/gatsbyjs/gatsby/discussions

Description

When viewing a website that has a component style calculated based on a media query, the style applied to the element in HTML differs from what was calculated/logged.

The issue is only present when building/serving the site.

The issue does not reproduce when developing the site.

Reproduction Link

https://github.com/karjanme/gatsby-bug

Steps to Reproduce

npm run develop

1. Open a web browser with the window width exceeding 900px
2. Load the website (http://localhost:8000/)
3. The navigation component is displayed (correct)

npm run build & npm run serve

1. Open a web browser with the window width exceeding 900px
2. Load the website (http://localhost:9000/)
3. The navigation component is not visible/displayed (incorrect)

Expected Result

The built/deployed website should show the navigation component on page load when the window width is greater than the min-width in the media query.

Actual Result

The built/deployed website does not show the navigation component on page load when the window width is

Environment

System:
    OS: Windows 10 10.0.19045
    CPU: (16) x64 Intel(R) Core(TM) i9-10885H CPU @ 2.40GHz
  Binaries:
    Node: 22.15.0 - C:\DevTools\NodeJS\v22.15.0\node.EXE
    Yarn: 1.22.21 - ~\AppData\Roaming\npm\yarn.CMD
    npm: 11.3.0 - C:\DevTools\NodeJS\v22.15.0\npm.CMD
  Languages:
    Python: 3.12.2
  Browsers:
    Edge: Chromium (127.0.2651.74)
  npmPackages:
    gatsby: ^5.15.0-next.2 => 5.15.0-next.2 
  npmGlobalPackages:
    gatsby-cli: 5.13.3

Config Flags

NONE

[Nischit-Ekbote]

Fix: SSR / hydration mismatch when using window.matchMedia

Hey 👋 thanks for reporting this!

What’s happening
Gatsby performs Server-Side Rendering (SSR) during the build step. On the server there’s no window (and no matchMedia), so any code that reads window during render will produce different HTML than the client. That causes a hydration mismatch and visual jumps (e.g. the missing navbar).

How to make your component SSR-safe

1. Only read browser APIs inside a client-only effect (useEffect) or after checking typeof window !== "undefined".
2. Render a stable fallback while hydrating (or return null) to avoid mismatched HTML.

Recommended pattern

import React, { useState, useEffect } from "react";

export default function Navigation() {
  const [isMounted, setIsMounted] = useState(false);
  const [isWide, setIsWide] = useState(false);

  useEffect(() => {
    setIsMounted(true);
    if (typeof window === "undefined") return;

    const mql = window.matchMedia("(min-width: 1024px)");
    const handle = (e) => setIsWide(e.matches);

    // initial value + subscribe
    setIsWide(mql.matches);
    mql.addEventListener("change", handle);
    return () => mql.removeEventListener("change", handle);
  }, []);

  // avoid SSR/client mismatch by rendering a consistent fallback
  if (!isMounted) return null; // or return a hidden nav fallback

  return (
    <nav className={isWide ? "navVisible" : "navHidden"}>
      {/* ... */}
    </nav>
  );
}

Reusable hook (optional, recommended for consistency)

function useMediaQuery(query, defaultValue = false) {
  const [matches, setMatches] = useState(() =>
    typeof window === "undefined" ? defaultValue : window.matchMedia(query).matches
  );

  useEffect(() => {
    if (typeof window === "undefined") return;
    const mql = window.matchMedia(query);
    const onChange = (e) => setMatches(e.matches);
    setMatches(mql.matches);
    mql.addEventListener("change", onChange);
    return () => mql.removeEventListener("change", onChange);
  }, [query]);

  return matches;
}

TL;DR: Don’t read window during render. Return a consistent fallback on the server, then initialize browser-dependent state in useEffect. This prevents hydration mismatches and visual jumps.