Publicar en npm y versionado semántico

Antes de publicar, ejecute siempre npm publish --dry-run. Esto simula la publicación sin subir nada realmente y le muestra exactamente qué archivos se incluirían, sus tamaños y el contenido del tarball del paquete. Permite detectar errores comunes, como incluir accidentalmente archivos de origen u omitir el directorio dist.

Controle lo que se publica mediante el campo files de package.json: "files": ["dist", "README.md"]. Este enfoque de lista blanca es más seguro que .npmignore (que funciona como una lista negra y puede exponer archivos confidenciales si olvida añadirlos). Incluya siempre dist, las declaraciones de tipos y la documentación. No incluya nunca src, tests ni node_modules.

Los paquetes de npm siguen el versionado semántico (semver): MAJOR.MINOR.PATCH. Incremente MAJOR cuando haya cambios incompatibles (eliminar props o cambiar firmas de la API). Incremente MINOR para nuevas funcionalidades compatibles con versiones anteriores (nuevos componentes o nuevas props opcionales). Incremente PATCH para correcciones de errores compatibles con versiones anteriores. La versión 0.x.x se considera preestable: cualquier elemento puede sufrir cambios incompatibles.

Los identificadores de versión preliminar indican que una versión aún no está lista para producción: 1.0.0-alpha.1 para compilaciones experimentales iniciales, 1.0.0-beta.2 para versiones con todas las funcionalidades, pero que aún pueden contener errores, y 1.0.0-rc.1 (candidato a versión final) para versiones listas para las pruebas finales. Publique las versiones preliminares con npm publish --tag beta para que no se conviertan en la instalación predeterminada.

Changesets es la herramienta estándar para gestionar el versionado de paquetes y los registros de cambios en bibliotecas de componentes. Flujo de trabajo: los colaboradores ejecutan yarn changeset add para registrar qué ha cambiado y el tipo de cambio (major/minor/patch). CI ejecuta yarn changeset version para actualizar las versiones de los paquetes. La publicación ejecuta yarn changeset publish para subirlos a npm.

Changesets genera y mantiene automáticamente CHANGELOG.md a partir de los archivos de changeset confirmados por los colaboradores. Cada entrada incluye el número de versión, la fecha de publicación y las descripciones de los cambios. Así se crea un historial legible de cada versión sin tener que mantener manualmente el registro de cambios.

semantic-release es una herramienta de versionado totalmente automatizada que determina la siguiente versión a partir de mensajes de commit convencionales (feat: → minor, fix: → patch, BREAKING CHANGE: → major). Actualiza la versión, genera el registro de cambios y publica en npm; todo se activa mediante CI al fusionar cambios en main. No requiere gestionar versiones manualmente.

Los paquetes sin ámbito (my-component) son siempre públicos. Los paquetes con ámbito (@myorg/my-component) tienen acceso restringido (privado) de forma predeterminada; publíquelos como públicos con npm publish --access public. Los paquetes restringidos requieren una cuenta de pago de npm o una organización. Confirme la configuración de acceso antes de realizar su primera publicación.

La provenance de npm vincula su paquete publicado con su commit específico de git de forma verificable. Actívela con npm publish --provenance en GitHub Actions. Los consumidores pueden comprobar que el paquete instalado se compiló a partir del commit exacto del código fuente que aparece en la página del registro de npm. Esto mejora considerablemente la seguridad de la cadena de suministro.

Cuando una versión contiene un error crítico o un cambio incompatible, retírela: npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4". npm muestra una advertencia de retirada a cualquiera que instale esa versión. Esto no elimina la versión (npm no borra de forma predeterminada las versiones publicadas), sino que avisa a los usuarios para que actualicen.

Los paquetes con ámbito usan el formato @scope/package-name. El ámbito suele ser su nombre de usuario de npm o el nombre de su organización. Los paquetes con ámbito dejan claro quién mantiene el paquete y evitan conflictos de nombres con los paquetes sin ámbito. Use paquetes con ámbito para paquetes privados y para paquetes de código abierto asociados con su organización.

Según el versionado semántico, ¿cuándo debe incrementarse el número de versión MAJOR?

Use npm publish --dry-run para obtener una vista previa y el campo files para controlar lo que se publica. Versionado semántico: MAJOR para cambios incompatibles, MINOR para nuevas funcionalidades y PATCH para correcciones. Las versiones preliminares usan las etiquetas -alpha/-beta/-rc. Changesets automatiza el versionado y la generación de CHANGELOG en bibliotecas colaborativas. semantic-release automatiza el proceso a partir de commits convencionales. Active --provenance para mejorar la seguridad de la cadena de suministro. Retire las versiones con errores mediante npm deprecate.