Improving site performance by shipping more CSS

GitHub's Primer Design System powers various features on the platform, such as buttons, banners, and breadcrumbs. However, the existing CSS-in-JS solution began to cause performance issues. Initial page loads took longer due to styles being initialized on the client, server-side rendering performance declined, and style updates grew out of control as component count increased.

To address these issues, the Primer team decided to switch to CSS Modules. This format allows writing and using native CSS features while maintaining the colocation and encapsulation that CSS-in-JS provided. With CSS Modules, styles are authored in a separate CSS file alongside the JavaScript source for the component. It treats all class names as local by default, preventing collisions and challenges that can arise from global selectors.

Importantly, styles are rolled up into CSS stylesheets, eliminating the need for client or server runtime behavior.

The transition to CSS Modules required updating every Primer component and GitHub component utilizing this technique. To minimize risks, the team adopted an incremental migration strategy. For each component, they added a new file that translated existing styles to CSS Modules, added the component to a feature flag that toggled between the new and old styles, and used visual regression tests to ensure identical snapshots between the CSS-in-JS and CSS Modules solutions.

The process involved gradual rollout to teams, GitHub staff, and all users, allowing the team to catch issues early and verify performance benefits.

By December 2024, all Primer components were migrated to CSS Modules. The team experienced significant performance improvements, including 55% less time to server-side render a page and 25% less time for components on a page to initialize. These results prompted further exploration of CSS Modules in other parts of GitHub and the eventual goal of dropping support for CSS-in-JS across the company.

One challenge in removing CSS-in-JS was the usage of the sx prop, which allowed styling and customizing components within Primer. The sx prop provided excellent TypeScript support, co-location of styles with components, and a convenient inline object for customization. However, it also had high runtime costs and scaling issues as the number of components using sx increased.

To mitigate these issues, the team created wrapper components in a transitive library called @primer/styled-react. This library allowed the use of sx in newly migrated components, enabling GitHub's UI codebase to continue consuming components through @primer/styled-react while the team realized performance gains. This approach enabled the migration of thousands of sx props without disrupting the GitHub UI codebase.