Cómo construir una librería de componentes web

La arquitectura determina cómo se organizan, construyen y distribuyen los componentes. Las dos aproximaciones principales son monorepo (todos los componentes en un solo repositorio con paquetes independientes) y single-package (un único paquete npm con todos los componentes).

El monorepo es la opción más escalable para equipos grandes. Herramientas como Turborepo, Nx o Lerna permiten gestionar dependencias entre paquetes, ejecutar builds incrementales y publicar versiones independientes. El single-package es más sencillo de mantener cuando el equipo es pequeño y la librería tiene menos de 30-40 componentes.

La elección de tecnología depende del ecosistema de tu organización. Si todos tus productos usan React, construir la librería en React es la decisión más pragmática. Si tienes productos en múltiples frameworks, Web Components o una capa de abstracción como Mitosis merecen consideración.

Web Components ofrecen interoperabilidad nativa con cualquier framework, pero su ecosistema de testing y herramientas aún no es tan maduro como el de React. Lit (de Google) es el framework más popular para construir Web Components con una DX moderna. En la práctica, muchas organizaciones optan por React y proporcionan wrappers para otros frameworks cuando es necesario.

El versionado semántico (semver) es imprescindible. Los consumidores de tu librería necesitan saber si una actualización es segura (patch), añade funcionalidad (minor) o rompe la API (major). Usa herramientas como Changesets o semantic-release para automatizar la generación de changelogs y la publicación a npm.

Publica en un registro npm privado si la librería es interna, o en npm público si es open source. Configura CI/CD para que cada merge a main genere automáticamente una nueva versión basada en los changesets acumulados. Esto elimina el proceso manual y reduce errores.

Los componentes de interfaz requieren una estrategia de testing específica que combine tests unitarios, tests de interacción y tests visuales. No basta con testear la lógica: necesitas verificar que el componente se renderiza correctamente y que las interacciones del usuario funcionan como se espera.

Storybook se ha convertido en el estándar para documentar y desarrollar componentes de forma aislada. Cada componente tiene una o más "stories" que muestran sus variantes, estados y casos de uso. Los addons de Storybook permiten añadir tablas de props, controles interactivos, checks de accesibilidad y documentación en MDX.

Una buena práctica es escribir las stories durante el desarrollo del componente, no después. Esto fuerza a pensar en la API del componente desde la perspectiva del consumidor y detecta problemas de diseño antes de que lleguen a producción.

Una librería de componentes que infla el bundle de las apps que la consumen genera rechazo inmediato. Configura el build para que soporte tree shaking: publica módulos ES (ESM), marca el paquete como sideEffects: false en package.json, y evita importaciones barrel que impiden la eliminación de código no usado.

Mide el tamaño de cada componente con herramientas como bundlephobia o size-limit. Establece un presupuesto de tamaño por componente y monitorízalo en CI para evitar regresiones. Un botón no debería pesar más de 2-3 KB gzipped.

Una librería de componentes es un producto que necesita mantenimiento continuo. Planifica actualizaciones de dependencias, deprecaciones de componentes obsoletos, y migraciones cuando las versiones de framework cambian. Automatiza todo lo posible: dependabot para dependencias, CI para tests y publicación, y alertas para regresiones de tamaño.

Asigna ownership claro: cada componente debe tener un equipo o persona responsable. Cuando nadie es dueño de un componente, nadie lo mantiene.