GitHub's Primer Design System Migrates to CSS Modules for Performance Improvement

Performance Challenges with CSS-in-JS

In 2023, the Primer Design System, which powers GitHub's user experiences, faced performance challenges due to an increasing number of components on pages. The existing CSS-in-JS solution led to longer initial page loads because styles were initialized on the client. Server-side rendering performance also declined as style collection shifted from the client, and style updates became difficult to manage as component counts grew.

Adopting CSS Modules

To resolve these issues, the Primer team adopted CSS Modules. This solution allows for native CSS features while providing colocation and encapsulation similar to CSS-in-JS. With CSS Modules, styles are authored in CSS files alongside JavaScript source for components, treating class names as local by default to prevent collisions.

Technical Implementation and Benefits

CSS Modules remove the need for client or server runtime behavior. Instead, styles are rolled up into CSS stylesheets that are sent as part of the HTML for a page. This approach directly addresses the performance bottlenecks caused by client-side style initialization and server-side style collection.

Migration Strategy

The transition to CSS Modules requires updating every Primer component and all GitHub components that previously used the CSS-in-JS technique. The Primer team is delivering these updates gradually, ensuring that the changes do not break existing functionality within GitHub during the migration process.