Transient Props in styled‑components v6: Ensuring Consistent Class Names After the v5→v6 Upgrade

Background

styled‑components switched from a custom prop‑filtering strategy in v5 to the transient‑prop pattern ($‑prefixed props) in v6, alongside an internal stylis v4 upgrade. The new model removes implicit prop forwarding to the DOM, but it also changes how class names are generated during server‑side rendering (SSR) and client hydration.

Constraints

After migrating to v6, team members have observed that class names produced on the server differ from those generated on the client when transient props are used, leading to hydration mismatches. The library offers no built‑in mechanism to scope or deduplicate these class names across the rendering boundary.

Unresolved Decision

There is no documented approach for synchronizing transient‑prop‑driven class names between SSR and client hydration. Teams must decide whether to rely on a Babel/SWC plugin configuration, enforce a naming convention, or implement a custom deduplication strategy.

Questions

1. What best‑practice patterns exist for keeping transient‑prop class names stable across SSR and client hydration in styled‑components v6?

2. How does the new stylis v4 processing affect class name determinism when transient props are used, and can this be mitigated?

3. Are there recommended Babel or SWC plugin setups that preserve class name consistency without manual intervention?