ADR-DS-005: React-bibliotek (Vite, ESM, React 18/19)
Beslutning
React-biblioteket bygges med Vite i library mode, distribueres som ESM-only, og støtter React 18 og 19 som peer dependency.
Vite
Library mode med vite-plugin-dts for TypeScript declarations. React defineres som external (peer dependency) — ikke bundlet inn i biblioteket. God integrasjon med Storybook.
ESM-only
"type": "module" i package.json. Ingen CJS-build. Build-target holdes synkronisert manuelt med .browserslistrc (via vite.shared.ts — se ADR-DS-001 og nettleserstøtte-baselinen), for å støtte nettlesere tilbake til Safari/iOS 15.4. Optimal tree-shaking slik at konsumenter bare betaler for det de bruker.
React 18 og 19
Peer dependency "react": "^18.0.0 || ^19.0.0" (samme for react-dom) — støtter både React 18 og 19. Det senker terskelen for konsumenter som fortsatt er på React 18, samtidig som React 19 anbefales. Vi holder oss til API-er som finnes i begge for å unngå å utestenge React 18-konsumenter.
Drivere for beslutningen
- Rask build og hot-reload for god utvikleropplevelse
- ESM er moderne JavaScript-standard og støtter optimal tree-shaking
- Bred React-støtte (18 og 19) senker adopsjonsterskelen for early adopters
Bakgrunn
Komponentbiblioteket trenger en bundler, et distribusjonsformat og en strategi for React-versjonsstøtte. ESM (ES Modules) er nå native i alle moderne nettlesere og Node.js-versjoner. React 19 ble sluppet i desember 2024.
Problemstilling
Hvilken bundler, distribusjonsformat og React-versjonsstrategi gir best utvikleropplevelse, optimal tree-shaking og langsiktig holdbarhet for komponentbiblioteket?
Konsekvenser
Hvem påvirkes?
Konsumenter med eldre CJS-prosjekter må ta i bruk bundler. Konsumenter på React 18 og 19 kan bruke biblioteket direkte.
Ulemper
- Inkompatibel med eldre CJS-prosjekter som ikke bruker bundler
- Å støtte både React 18 og 19 begrenser oss til API-er som finnes i begge versjonene
- Vite er en abstraksjon over Rollup — feilsøking av edge cases i build kan kreve kunnskap om begge (ingen konkret mitigering, akseptert risiko)
Tiltak mot ulemper
- De fleste moderne bundlere (webpack, Vite, Parcel) håndterer ESM uten konfigurasjon
- React 19-spesifikke API-er brukes bare der de har en trygg fallback på React 18
Forkastede alternativer
Rollup direkte
Vite bruker Rollup under panseret — bruke Rollup direkte gir full kontroll uten et abstraksjonslag.
Forkastet fordi: Krever mer manuell konfigurasjon enn Vite, og vi mister Vites dev server og Storybook-integrasjon som brukes aktivt i utviklingsflyten.
tsup / esbuild
Raskere bundlere enn Rollup/Vite, særlig for TypeScript-prosjekter.
Forkastet fordi: Dårligere Storybook-integrasjon. Storybook er en sentral del av arbeidsflyten, og god integrasjon veier tyngre enn marginalt raskere build.
Webpack
Det mest utbredte build-verktøyet historisk sett.
Forkastet fordi: Kompleks konfigurasjon og tregere enn Vite. Library mode er ikke Webpacks primære styrke.
Dual CJS/ESM (begge formater)
Publisere både CommonJS og ES Module-versjoner for å støtte alle konsumenter.
Forkastet fordi: Dobbel vedlikeholdsbyrde og økt pakke-størrelse. CJS er på vei ut av Node.js-økosystemet, og å vedlikeholde det forsinker avviklingen.
Kun React 19 ("react": "^19.0.0")
Kun støtte React 19 og tvinge konsumenter på React 18 til å oppgradere.
Forkastet fordi: Utestenger early adopters som fortsatt er på React 18 og gjør adopsjonsterskelen unødvendig høy. Kostnaden ved å holde seg til API-er som finnes i begge versjonene er lav sammenlignet med å låse ute konsumenter. React 19 anbefales fortsatt, men kreves ikke.
Deltakere