Gemeinsame Komponenten paketieren

Component Packaging & Versioning

When a design system or shared UI library is consumed across multiple packages, apps or workspaces (packages/ui, @org/design-system, @org/tokens), packaging mistakes can break bundler resolution, bloat client bundles, leak server-incompatible globals into SSR, or break consumers on minor updates.

1. Clean Package Exports & Tree-Shaking

• Explicit package.json exports map:
  • Declare entry points clearly (".", "./tokens.css", "./components/*") with matching types, import (ESM) and default conditions.
  • Set "sideEffects": ["*.css"] accurately so bundlers (Vite, Rollup, webpack, esbuild) tree-shake unused components without accidentally stripping required CSS imports!
• Avoid heavy barrel-file traps:
  • Ensure importing a lightweight <Button> does not eagerly pull in heavy optional dependencies (such as a rich-text editor, chart library, date-fns locales or syntax highlighter) via a single monolithic barrel file.
• Peer Dependencies vs. Direct Dependencies:
  • Declare host UI frameworks (react, react-dom, vue, @angular/core) as peerDependencies so consumers never bundle two competing copies of the framework runtime (which breaks hooks, reactivity and context/DI!).

2. CSS, Token & Asset Distribution

• Predictable style loading: decide and document clearly how styles are consumed:
  • A shared token/base stylesheet (@org/ui/tokens.css) imported once at the app root, plus either scoped component styles, CSS Modules, zero-runtime CSS-in-JS or utility classes.
• Font & icon paths: avoid hardcoded relative asset paths (url(../assets/font.woff2)) that break when consumed from a different workspace directory or bundler config.
• SSR & Hydration safety: never access window, document, localStorage or ResizeObserver unconditionally at module import time or during initial render — guard browser-only APIs inside lifecycle hooks (onMounted, useEffect, afterNextRender) and use deterministic ID generation (useId()) so server and client markup match.

3. Semantic Versioning (SemVer) & Deprecation Discipline

Treat every public surface of a shared component as a versioned contract:

• Patch: bug fixes, internal refactors and accessibility fixes that do not alter public props, slots or visual layout measurements.
• Minor: backward-compatible new components, new optional props/variants (with unchanged defaults) and new semantic tokens.
• Major (Breaking): removing or renaming a prop/slot/token, changing default prop behavior, altering public TypeScript types incompatibly, or changing layout dimensions in a way that breaks parent containers.
• Always accompany breaking changes with a clear migration guide, deprecation warnings and coordinated rollout across workspace consumers.