GitHub's 3-Year Migration to CSS Modules Cuts SSR Time 55%

Why GitHub Chose CSS Modules

CSS Modules allow developers to write styles in CSS files alongside component source code, with class names scoped locally by default to reduce conflicts. Crucially for this migration, CSS Modules eliminate the need for client-side or server-side runtime behavior; styles are bundled into CSS files sent with the page HTML.

Migration Process

The effort began with the Primer design system. The team added CSS Modules files for each component, used feature flags to toggle between the old and new styling approaches, and employed visual regression testing to verify visual parity. Rollout expanded from the Primer team to GitHub employees, then to all users.

By December 2024, all Primer components had migrated to CSS Modules. However, much of the codebase still used the sx prop for inline style customization. While sx integrated well with TypeScript and design tokens, its dynamic nature increased runtime cost and made scaling harder as component count grew.

Managing the Migration at Scale

To avoid breaking existing usage, GitHub created an intermediate library @primer/styled-react that allowed continued use of sx on already-migrated components, while components not needing sx could import directly from @primer/react.

Removal of sx started in April 2025 with approximately 7,760 usages. With help from an internal VS Code plugin and codemod tools, a group of 8 engineers migrated 6,419 usages in 6 months, yielding 1% to 22% SSR improvements on some pages. By April 2026, 2 engineers using GitHub Copilot coding agent reduced the remaining 895 usages to zero in 3 weeks.

Visual theming posed another challenge. GitHub supports 7 themes, each with a high-contrast mode, and parts of the system were tied to styled-components. The team migrated JavaScript theming utilities while continuing to define color variables in CSS.

What This Means for Developers

GitHub's data shows that eliminating runtime styling logic delivers tangible performance gains when UIs grow in complexity. However, the most valuable takeaway is not CSS Modules itself, but the implementation approach: phased compatibility, feature flags, visual testing, progressive rollout, and auditable automation.

The process also demonstrates that migrating from CSS-in-JS involves more than changing how styles are written. It requires removing the sx prop, decoupling theming from styled-components, and maintaining component compatibility over an extended period.

Therefore, these results do not guarantee identical benefits for every project; the gains are tied to GitHub's scale, component architecture, and its specific use of dynamic styling.

Author: 聆听音乐的鱼 Reference: https://github.blog/engineering/architecture-optimization/improving-site-performance-by-shipping-more-css/