Package shared components

Packages UI components and styles as explicit versioned contracts that work across consuming applications and build environments.

component-packaging-versioning

Team members using this skill

See how it helps

When is it useful?

Use when a UI library is consumed by multiple applications or workspaces.

What does it help you do?

Defines explicit exports, framework peer dependencies and removable unused modules.
Distributes styles, tokens and assets without losing required CSS.
Checks server-rendering safety and versions public API or layout changes.

Try asking this

Package our button and dialog library so importing a button excludes the editor dependency. Inspect the production bundle from a minimal consumer. It should contain the button's required styles but neither editor code nor duplicate framework runtime.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

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.

Included files 1

SKILL.md