How to build a web component library

Architecture determines how components are organised, built and distributed. The two main approaches are monorepo (all components in a single repository with independent packages) and single-package (one npm package containing all components).

The monorepo is the most scalable option for large teams. Tools like Turborepo, Nx or Lerna handle inter-package dependencies, run incremental builds and publish independent versions. The single-package approach is simpler to maintain when the team is small and the library has fewer than 30–40 components.

The technology choice depends on your organisation’s ecosystem. If all your products use React, building the library in React is the most pragmatic decision. If you have products across multiple frameworks, Web Components or an abstraction layer like Mitosis deserve consideration.

Web Components offer native interoperability with any framework, but their testing and tooling ecosystem is not yet as mature as React’s. Lit (by Google) is the most popular framework for building Web Components with a modern DX. In practice, many organisations opt for React and provide wrappers for other frameworks when needed.

Semantic versioning (semver) is non-negotiable. Consumers of your library need to know whether an update is safe (patch), adds functionality (minor) or breaks the API (major). Use tools like Changesets or semantic-release to automate changelog generation and npm publishing.

Publish to a private npm registry if the library is internal, or to public npm if it is open source. Set up CI/CD so that every merge to main automatically generates a new version based on accumulated changesets. This eliminates the manual process and reduces errors.

UI components require a specific testing strategy that combines unit tests, interaction tests and visual tests. Testing logic alone is not enough: you need to verify that the component renders correctly and that user interactions work as expected.

Storybook has become the standard for documenting and developing components in isolation. Each component has one or more "stories" that showcase its variants, states and use cases. Storybook addons let you add prop tables, interactive controls, accessibility checks and MDX documentation.

A good practice is writing stories during component development, not after. This forces you to think about the component API from the consumer’s perspective and catches design issues before they reach production.

A component library that bloats consuming apps' bundles will face immediate pushback. Configure the build to support tree shaking: publish ES modules (ESM), mark the package as sideEffects: false in package.json, and avoid barrel imports that prevent dead code elimination.

Measure each component’s size with tools like bundlephobia or size-limit. Set a size budget per component and monitor it in CI to prevent regressions. A button should not weigh more than 2–3 KB gzipped.

A component library is a product that needs continuous maintenance. Plan for dependency updates, deprecation of obsolete components, and migrations when framework versions change. Automate everything you can: Dependabot for dependencies, CI for tests and publishing, and alerts for size regressions.

Assign clear ownership: each component should have a responsible team or individual. When nobody owns a component, nobody maintains it.