Siteperformance verbeteren door meer CSS te leveren

Auteurs: Josh Black & Marie Lucca Datum: 25 september 2026

Het Primer Design System vormt de basis voor veel van de ervaringen die je vandaag op GitHub ziet. Van knoppen en banners tot breadcrumbs; deze fundamentele componenten moeten toegankelijk, flexibel en performant zijn in een breed scala aan scenario's.

In 2023 begon het aantal componenten op bepaalde pagina's echter explosief te groeien. Dit leidde tot verschillende prestatieproblemen met onze bestaande CSS-in-JS-oplossing:

• De initiële paginalading duurde langer omdat stijlen aan de clientzijde moesten worden geïnitialiseerd.
• De prestaties van server-side rendering (SSR) namen af naarmate de verzameling van stijlen verschoof van de client.
• Updates aan stijlen werden onbeheersbaar naarmate het aantal componenten per pagina toenam.

Het werd duidelijk dat het Primer-team het probleem bij de bron moest aanpakken. We hadden een alternatief nodig dat de client- en serverkosten van onze huidige oplossing volledig zou vermijden. Bovendien moest elk alternatief op een manier worden geïmplementeerd die breuken in de functionaliteit van GitHub tijdens de migratie zou voorkomen.

Introductie van CSS (Modules)

Het Primer-team vond een oplossing die aan al onze criteria voldeed: CSS Modules. Dit formaat stelt ons in staat om native CSS-functies te schrijven en te gebruiken, terwijl we toch de colocatie en inkapseling behouden die we gewend waren van CSS-in-JS.

Met CSS Modules worden stijlen geschreven in een CSS-bestand naast de JavaScript-broncode van het component. Hierdoor kunnen we alle klassennamen standaard als 'lokaal' behandelen, wat botsingen en uitdagingen die gepaard gaan met globale selectors voorkomt. Dit formaat verwijdert bovendien de noodzaak voor runtime-gedrag aan de client- of serverzijde. In plaats daarvan worden stijlen gebundeld in CSS-stylesheets die als onderdeel van de HTML van een pagina worden verzonden.

Deze oplossing verschilde echter radicaal van de CSS-in-JS-oplossing die we op dat moment hadden. De wijziging vereiste een update van elk Primer-component en elk component op GitHub dat met deze techniek was gebouwd. Gelukkig zijn design systems het perfecte middel om dit soort wijzigingen op grote schaal door te voeren.

Een geleidelijke overstap naar CSS Modules

Het plan voor de overstap naar CSS Modules was helder: het Primer-team moest updates leveren voor elk van zijn componenten om ze om te zetten van CSS-in-JS naar CSS Modules. Tegelijkertijd mochten deze updates het gebruik van de componenten binnen GitHub niet verstoren. Tot slot moest de onderliggende techniek voor CSS-in-JS blijven werken voor alle componenten in GitHub die deze nog gebruikten.

Vanwege deze beperkingen kozen we voor een incrementele migratiestrategie. Voor elk component was het plan als volgt:

1. Een nieuw bestand toevoegen dat bestaande stijlen vertaalt naar CSS Modules.
2. Het component toevoegen aan een feature flag om te kunnen schakelen tussen de nieuwe en oude stijlen.
3. Bestaande visuele regressietests gebruiken om te verifiëren dat de snapshots identiek waren tussen de CSS-in-JS-oplossing en CSS Modules.
4. De feature flag geleidelijk uitrollen naar ons eigen team, daarna naar het personeel van GitHub en uiteindelijk naar alle gebruikers om eventuele problemen vroegtijdig te detecteren.

Dit proces creëerde een sterke feedbackloop. Door het gebruik van feature flags kon de migratie veilig plaatsvinden, terwijl we duidelijke signalen kregen over de prestatievoordelen van CSS Modules.

Tegen december 2024 waren alle componenten in Primer gemigreerd. We zagen over de hele linie prestatiewinsten, in het bijzonder:

• 55% minder tijd voor het server-side renderen van een pagina.
• 25% minder tijd voor het initialiseren van componenten op een pagina.

Wegbewegen van CSS-in-JS bij GitHub

Een van de lastigste aspecten van het verwijderen van CSS-in-JS uit Primer was het gebruik van de sx prop. Deze prop was de manier om Primer-componenten te stylen en aan te passen; teams konden een inline object meegeven om alles aan het component te configureren. Dit vertegenwoordigde zowel de beste als de slechtste kanten van CSS-in-JS:

• Voordelen: Uitstekende TypeScript-ondersteuning met integratie van onze Design Tokens en colocatie (alles op één plek bij het component).
• Nadelen: Hoge runtime-kosten door de dynamische aard van de inline objects en schaalproblemen naarmate het aantal componenten dat sx gebruikte op een pagina groeide.

Om CSS-in-JS volledig te kunnen verwijderen, was de eerste stap het verminderen van het sx-gebruik in heel GitHub.

De dualiteit van Primer

Het is belangrijk op te merken dat hoewel het design system zelf officieel was overgestapt van styled-components, een groot deel van de GitHub-codebase dat nog niet was. Omdat sx props jarenlang de standaard waren, moesten duizenden van deze props worden gemigreerd voordat we GitHub konden overzetten naar de nieuwe @primer/react-versie die niet langer afhankelijk was van styled-components.

Om dit enorme werk uit te voeren met een hoog vertrouwen en laag risico, deden we dit niet in één keer. Naast de migratie naar CSS Modules en het gebruik van feature flags, creëerden we "wrapper"-componenten in een transitiebibliotheek genaamd @primer/styled-react. Dit pakket maakte het mogelijk dat bestaande UI-code nog steeds de sx prop kon gebruiken via de wrapper, terwijl we voor nieuwe gevallen direct de prestatiewinsten van @primer/react konden benutten.

Styled Box Zero

De volgende fase van het migratieproces verliep per pakket als volgt:

1. Vertaal alle sx-gebruik naar equivalente CSS Modules-bestanden (inclusief cross-referencing naar CSS-variabelen).
2. Vervang @primer/styled-react imports door @primer/react imports.
3. Test in de pre-productieomgeving.
4. Implementeer (deploy).

Het werk begon in april 2025 met een piek van ongeveer 7.760 sx-props die gemigreerd moesten worden. In eerste instantie ontwikkelde een van onze ontwikkelaars, Ian Sanders, een VS Code-plugin om te helpen bij de migratie per prop. Daarnaast werd er intern een codemod ontwikkeld om volledige bestanden in de GitHub-codebase te migreren. Hoewel er handmatige controle en validatie nodig was, was het proces grotendeels geautomatiseerd. Een rotatie van 8 engineers migreerde in 6 maanden tijd 6.419 props, waarbij de SSR-prestaties op sommige pagina's met 1% tot 22% verbeterden.

Tegen april 2026 was het landschap veranderd door de exponentiële groei van de mogelijkheden van Copilot. Met behulp van Copilot coding agents konden we de resterende 895 sx-props in slechts drie weken tijd terugbrengen naar nul, uitgevoerd door een team van twee engineers.

De strijd met de thema's

Na de sx-migraties was er nog één obstakel: de thema's. GitHub ondersteunt zeven verschillende thema's, inclusief variaties voor hoog contrast. Al dit was mogelijk gemaakt via styled-components. Voordat we de afhankelijkheden volledig konden verwijderen, moesten we de theming ontkoppelen.

Onze thema-variabelen waren altijd al gedefinieerd in CSS via ons @primer/css-pakket, maar we moesten het JavaScript-gebruik en de utilities die door styled-components werden mogelijk gemaakt, verwijderen. Na twee maanden van migraties, geleidelijke uitrol en het gebruik van feature flags, waren we klaar voor de definitieve verwijdering van de afhankelijkheden.

Alles is goed dat goed eindigt

Sinds juni 2026 draait GitHub voor 100% op CSS Modules. De veiligheidsmaatregelen die we hebben getroffen, stelden ons in staat om significante architecturale wijzigingen veilig door te voeren, deze in productie te testen en efficiënt te herstellen.

Wat begon als een CSS-migratie, bleek een geleidelijke herstructurering van de manier waarop GitHub UI op schaal stijlt, thematiseert en levert. We hebben sx, styled-components en styled-system volledig verwijderd uit de website, zonder dat dit leidde tot storingen. Het verbeteren van de prestaties en de gebruikerservaring blijft onze hoogste prioriteit.