Gatsby + styled-components : `develop` cache le SSR cassé

Q: Pourquoi j’ai un FOUC (flash de contenu non stylé) avec styled-components en prod alors que tout marche en local sous Gatsby ?

Parce que gatsby develop fait un rendu full client-side via webpack-dev-server et n’exerce jamais le SSR. Si la config SSR de styled-components est cassée, le build prod génère des classes serveur dont le hash diffère du client : React remplace tout au mount, d’où le FOUC. Le mode dev masque le problème sur le critical path concerné.

Q: Comment vérifier rapidement si le SSR styled-components est cassé dans un build Gatsby ?

Lancez gatsby build puis grep data-styled public/index.html. Si la commande retourne du contenu, le SSR styled-components fonctionne ; si elle ne retourne rien, le SSR est cassé et le FOUC est garanti en prod. Ce check de 30 secondes est à automatiser en pre-merge dès qu’on touche aux styles.

19 mars 2026

Refacto styled-components sur MonSite. gatsby develop tourne nickel : pages OK, styles OK, hot reload OK. Je merge, deploy Netlify, ouverture du site → flash de contenu non stylé pendant ~1s puis tout se ré-applique. FOUC bien gras visible à chaque chargement.

Le piège

En gatsby develop, le rendu est full client-side via webpack-dev-server. Le SSR n’est pas exercé : si la config SSR de styled-components est cassée, on ne le voit jamais en local.

Le build prod (gatsby build) lui passe par le pipeline SSR de Gatsby. Sans gatsby-plugin-styled-components (ou avec une config Babel manquante), les classes générées côté serveur n’ont pas la même hash que côté client → mismatch → React remplace tout au mount → FOUC.

Au moment du refacto j’ai retiré gatsby-plugin-styled-components de gatsby-config.js parce que « ça marche sans en local ». C’était lui qui injectait le babel-plugin-styled-components nécessaire au SSR.

Le diagnostic 30 secondes

gatsby build
grep data-styled public/index.html

Retourne du contenu → SSR styled-components OK
Retourne rien → SSR cassé, FOUC garanti en prod

Le fix

Garder gatsby-plugin-styled-components dans gatsby-config.js :

module.exports = {
  plugins: [
    'gatsby-plugin-styled-components',
    // ...
  ],
}

Lessons learned

Ne jamais faire confiance à gatsby develop pour valider un refacto styled-components / SSR / hydration. C’est un mode CSR-only sur le critical path concerné.
Le check de 30s : gatsby build + grep data-styled public/index.html. À automatiser en pre-merge si on touche aux styles.
gatsby-plugin-styled-components n’est pas optionnel dès qu’on utilise styled-components. Le retirer est silencieusement cassant.
Vaut sans doute pareil pour gatsby-plugin-emotion, gatsby-plugin-mui et tout autre injecteur SSR de CSS-in-JS.

#gatsby #styled-components #ssr #react #frontend #monsite

Questions fréquentes

Pourquoi j’ai un FOUC (flash de contenu non stylé) avec styled-components en prod alors que tout marche en local sous Gatsby ?

Parce que gatsby develop fait un rendu full client-side via webpack-dev-server et n’exerce jamais le SSR. Si la config SSR de styled-components est cassée, le build prod génère des classes serveur dont le hash diffère du client : React remplace tout au mount, d’où le FOUC. Le mode dev masque le problème sur le critical path concerné.

Comment vérifier rapidement si le SSR styled-components est cassé dans un build Gatsby ?

Lancez gatsby build puis grep data-styled public/index.html. Si la commande retourne du contenu, le SSR styled-components fonctionne ; si elle ne retourne rien, le SSR est cassé et le FOUC est garanti en prod. Ce check de 30 secondes est à automatiser en pre-merge dès qu’on touche aux styles.

Peut-on retirer gatsby-plugin-styled-components si l’app fonctionne sans en développement ?

Non, le retirer est silencieusement cassant. C’est ce plugin qui injecte le babel-plugin-styled-components nécessaire au SSR ; sans lui, les hashs de classes serveur et client divergent. Il fonctionne « sans » uniquement parce que gatsby develop est en CSR-only et ne teste pas le SSR.

Le même piège SSR existe-t-il avec d’autres bibliothèques CSS-in-JS sous Gatsby ?

Oui, très probablement. Tout injecteur SSR de CSS-in-JS comme gatsby-plugin-emotion ou gatsby-plugin-mui joue le même rôle que gatsby-plugin-styled-components. Ne jamais se fier à gatsby develop pour valider un refacto SSR/hydration : validez toujours via gatsby build.