Does styled-components SSR rehydration tolerate server and client bundle mismatches during a zero-downtime rollout?

Direct answer

No. styled-components SSR rehydration does not reliably tolerate server and client bundle mismatches during a zero-downtime rollout. Without stable component identifiers, class names are derived from a runtime counter and style hash, so adding or removing a styled component early in the import graph shifts identifiers for every component that follows. If an older server bundle emits HTML and a newer client bundle hydrates it, the identifiers can drift, producing missing styles, duplicate CSS, or a flash of unstyled content.

Confirmed facts and likely explanation

Confirmed facts

• Default styled-components class names depend on runtime evaluation order, not source location.
• ServerStyleSheet records rules under those runtime identifiers, and client hydration looks them up by the same identifiers.
• babel-plugin-styled-components assigns stable componentId values from source location, removing evaluation-order dependence when the same options are applied to server and client builds.
• The plugin does not remove the requirement that server and client run the same styled-components major version.
• Streaming and concurrent rendering interleave component evaluation, making default counter-based names less predictable than classic renderToString; stable IDs protect identity but not CSS injection order or precedence.

Likely explanation

During a blue-green or canary rollout, the server may still render with the previous bundle while users receive the newer client bundle. The client then looks for class names that no longer match the markup. Enabling babel-plugin-styled-components on all artifacts eliminates the ordering dependency, but it introduces a deployment constraint: every server and client bundle must be rebuilt together with identical plugin configuration. Mixing plugin-enabled and plugin-disabled deploys creates a second mismatch vector.

Steps for this case

1. Pin the same styled-components major version in server and client dependencies.
2. Enable babel-plugin-styled-components with identical options in both server and client builds.
3. Rebuild server and client artifacts together; do not enable the plugin on only one side of the boundary.
4. Route old server markup to the old client bundle and new server markup to the new client bundle during the canary window.
5. Verify by rendering the same page with old and new server bundles, hydrating with the opposite client bundle in browser dev tools, and comparing generated class names and style tags.

Missing diagnostic detail

Are server and client running the same styled-components major version, and is babel-plugin-styled-components enabled identically on both sides? This changes the recommendation because different major versions can behave differently even with stable componentId enabled.

Review needed

Exact class-name behavior across styled-components major releases has not been independently verified here. Confirm your installed versions before treating componentId stability as a rollout guarantee.

node -e "console.log(require('styled-components/package.json').version)"