GitHub's CSS Modules Migration Boosts Performance
How switching from CSS-in-JS reduced rendering time by 55%
1CSS-in-JS performance bottlenecks
By 2023, GitHub's Primer Design System faced critical performance issues as component counts grew. Client-side style initialization slowed page loads, SSR performance degraded, and style updates became unmanageable. The CSS-in-JS approach that worked for smaller scales became unsustainable, requiring a fundamental architectural change to maintain GitHub's performance standards.
2CSS Modules solution criteria
The Primer team needed a solution that eliminated runtime costs while maintaining component encapsulation. CSS Modules emerged as the ideal choice, allowing native CSS usage with local scoping by default. Crucially, the migration had to prevent any breakage across GitHub's massive codebase during transition, requiring careful planning and execution strategies.
3Incremental migration strategy
The team implemented a phased approach: creating parallel CSS Modules files, feature flagging components, and rigorous visual regression testing. This allowed gradual rollout from internal teams to all users. By December 2024, all Primer components migrated successfully, achieving 55% faster SSR and 25% quicker component initialization.
4SX prop migration challenge
The sx prop represented GitHub's biggest CSS-in-JS legacy issue, with thousands of instances across the codebase. A transitional @primer/styled-react package maintained compatibility while new components used pure CSS Modules. From April 2025, engineers migrated 6,419 props over six months, observing SSR improvements up to 22% on some pages.
5AI-accelerated final push
By April 2026, GitHub leveraged Copilot coding agents to complete the migration at unprecedented speed. Two engineers eliminated the remaining 895 sx props in three weeks - a task that previously required eight engineers for six months. This demonstrated how AI tooling could accelerate large-scale refactoring efforts.
6Theme system overhaul
Seven GitHub themes and high-contrast modes relied on styled-components. The team decoupled theming by moving variables to @primer/css while maintaining JavaScript utilities during transition. Another careful migration phase ensured theme stability before final dependency removal in mid-2026.
7Architectural safeguards
Feature flags and gradual rollouts proved critical for risk mitigation. The team could stress test changes in production, quickly identify issues, and implement fixes without user impact. This safety net enabled GitHub to complete the massive architectural shift without service disruptions.
8Performance outcomes
The complete migration to CSS Modules delivered system-wide improvements beyond initial Primer component gains. Server-side rendering became consistently faster across all pages, client-side style processing reduced significantly, and GitHub's UI became more maintainable at scale.
9Large-scale refactoring lessons
GitHub's four-year migration demonstrates how to execute fundamental technology shifts in complex systems. The success combined technical solutions (CSS Modules) with organizational strategies (phased rollouts, AI assistance). This case study offers valuable patterns for other enterprises facing similar architectural transitions.
Original article: GitHub Engineering — GitHub's CSS Modules Migration Boosts Performance