Skip to main content

ADR-DS-001: Monorepo og byggverktøy

StatusUtkast

Beslutning​

Alle pakker samles i én Monorepo med pnpm som pakkebehandler og Turborepo for build-orkestrering.

Monorepo​

Alle pakker i samme repo med workspace-protokoll (workspace:*) for interne avhengigheter. Pakker publisert til npm: indeks-tokens, indeks-utils, indeks-css, indeks-web, indeks-react. Private pakker: indeks-docs, indeks-eksempel og indeks-storybook.

pnpm​

Erstattet npm. To sentrale sikkerhetsmekanismer:

shamefully-hoist=false sikrer streng isolasjon — pakker kan bare bruke avhengigheter de selv har deklarert i package.json. Det forhindrer at kode ved et uhell bruker transitive avhengigheter, noe som reduserer risikoen for at en ondsinnet pakke kan nå kode den ikke skal ha tilgang til.

strict-peer-dependencies=true tvinger frem eksplisitte peer dependency-erklæringer, slik at versjonskonflikter oppdages tidlig i utviklingen fremfor hos konsumenter i produksjon.

Content-addressable storage betyr at hver pakkeversjon lagres én gang på disken og verifiseres med en hash ved installasjon — manipulasjon av nedlastede pakker oppdages umiddelbart.

Turborepo​

Erstattet Lerna for bygging. ^build sikrer riktig byggerekkefølge basert på dependency-grafen — indeks-css bygges aldri før indeks-tokens er ferdig. Caching baseres på innholdshasher av kildefiler og avhengigheter: hvis ingenting har endret seg siden forrige bygg, hoppes pakken over. Parallell bygging der det er mulig.

Drivere for beslutningen​

  • Tett kobling mellom pakker krever koordinert utvikling i samme repo
  • Kjent monorepo-mønster fra eksisterende SpareBank 1 designsystem (@sb1/ffe-*)
  • Bedre sikkerhet enn npm for pakkebehandling
  • Intelligent caching for raskere CI og lokal utvikling

Bakgrunn​

Designsystemet har tette avhengigheter mellom pakkene:

indeks-tokens → indeks-utils → indeks-css → indeks-web → indeks-react

En endring i tokens påvirker hele kjeden. Pakkene må kunne utvikles og testes i sammenheng, ikke isolert. Vi startet med npm workspaces og Lerna, men npm manglet sikkerhetsfunksjoner og Lerna var utdatert og treg.

Problemstilling​

Hvilken monorepo-strategi og verktøykjede støtter koordinert utvikling og testing på tvers av tett koblede pakker, med god sikkerhet og intelligent caching?

Konsekvenser​

Hvem påvirkes?​

Alle utviklere som jobber med designsystemet må bruke pnpm og forstå workspace-konsepter.

Ulemper​

  • Hele repoet må klones (ikke bare én pakke)
  • Utviklere må installere pnpm — ikke alle har det fra før
  • CI-miljøer må konfigureres med pnpm
  • Noen eldre pakker kan ha problemer med pnpms strenge node_modules-struktur

Tiltak mot ulemper​

  • Turborepo-caching og parallellisering gjør CI raskt til tross for én stor repo
  • Dokumentasjon veileder nye utviklere gjennom oppsett

Forkastede alternativer​

Separate repositories per pakke​

Hver pakke i sitt eget git-repository, publisert uavhengig.

Forkastet fordi: Vanskelig å koordinere endringer på tvers av pakker. En token-endring krever PR i fire separate repos med nøye rekkefølge — i praksis upraktisk.

Én stor pakke​

Slå sammen alle pakker til ett npm-pakke.

Forkastet fordi: Konsumenter som bare trenger tokens eller CSS må ta inn React-kode. Umuliggjør uavhengig versjonering.

npm (i stedet for pnpm)​

npm er standard og forhåndsinstallert hos alle Node.js-brukere.

Forkastet fordi: Mangler pnpms sikkerhetsisolasjon og er tregere, særlig ved store dependency-grafer. Gammel npm-basert løsning var allerede en kilde til problemer.

Yarn Berry (Plug'n'Play)​

Yarns nye arkitektur med zero-installs og PnP-resolver i stedet for node_modules.

Forkastet fordi: Plug'n'Play bryter mange verktøy som forventer en tradisjonell node_modules-mappe (Jest, Storybook m.fl.) og krever stor migrasjonsoverhead for å gjøre eksisterende tooling kompatibelt.

Nx​

Et build-system med monorepo-støtte og avansert dependency-graf.

Forkastet fordi: Mer komplekst enn nødvendig for dette prosjektet. Turborepo dekker behovene med vesentlig enklere konfigurasjon.

Lerna​

Det opprinnelige verktøyet vi brukte for monorepo-håndtering.

Forkastet fordi: Utdatert, treg, og Lerna-teamet anbefaler selv Nx eller Turborepo for nye prosjekter. Vi opplevde konkrete ytelses- og vedlikeholdsproblemer.

Deltakere

Utarbeidet avTeam Designsystem