Conocer ese momento en que escribes la misma función utilitaria por tercera vez en distintos proyectos y piensas espera por qué hago esto otra vez es justo cuando los paquetes de NPM se cuelan en tu vida. Hace poco convertí un generador HTML a PDF en un paquete de NPM y lo que empezó como una utilidad rápida se convirtió en una pequeña aventura llena de aprendizaje, errores y soluciones prácticas. NPM ha cambiado varias cosas recientemente por eso muchos tutoriales antiguos pueden no funcionar y generan frustración.
Publicar un paquete te aporta tres ventajas clave reutilización evita copiar y pegar entre proyectos; ayudar a otros alguien más puede estar resolviendo el mismo problema; y aprendizaje aprendes flujo open source versionado CI CD y documentación. Además es muy satisfactorio poder instalar tu propio trabajo con npm install nombre-del-paquete.
Antes de empezar entiende los scopes y nombres NPM permite paquetes sin scope nombre-del-paquete o con scope @tuusuario/nombre-del-paquete. Si tu usuario es cooldev entonces @cooldev es tu namespace y no necesitas crear una organización salvo que el scope sea distinto. Comprueba disponibilidad con npm view @tuusuario/nombre-del-paquete y si responde 404 el nombre está libre.
1 Preparar la estructura del proyecto Crea un directorio limpio y arranca git y npm mkdir nombre-del-paquete cd nombre-del-paquete git init npm init -y Mantén el código organizado en un folder src para que el paquete sea claro y enfocado.
2 Traer los archivos fuente Copia la lógica que quieres publicar a src por ejemplo mkdir -p src cp -r ruta/de/tu-proyecto/src/lib/tu-libreria/* src/ Así aislas lo necesario y evitas llevar archivos de más.
3 Configurar package.json El package.json es el corazón del paquete. En lugar de pegar JSON aquí asegúrate de definir name con tu scope si aplica version initial main apuntando a dist/index.js types si usas TypeScript repository.url a tu repositorio bugs.url y homepage a la documentación. Verifica que el nombre esté disponible y que los enlaces apunten a tu repo real.
4 Conectar con GitHub Sube el código a control de versiones git add . git commit -m Inicial git branch -M master git remote add origin https://github.com/tuusuario/nombre-del-paquete.git git push -u origin master
5 Probar la build local Antes de publicar asegúrate de que todo funciona npm run build y prueba el paquete localmente con npm pack que genera un archivo .tgz luego instálalo desde otro proyecto npm install /ruta/al-paquete-1.0.0.tgz Esto detecta muchísimos errores que solo aparecen en un entorno limpio.
6 Login en NPM Puedes iniciar sesión desde el navegador o desde la terminal con npm login te pedirá usuario contraseña email y el one time password si tienes 2FA activo.
7 Estrategia de publicación Manual versus automatizada Publicación manual npm login npm publish --access public funciona rápido pero es propenso a errores olvidar build o tests. Recomendado configurar publicación automática con CI CD mediante GitHub Actions y un token de acceso granular.
8 Token de acceso granular y GitHub Actions Los tokens clásicos de NPM están deprecados necesitas crear un Granular Access Token en npmjs.com con permisos read and write para packages y scoping a tu paquete o a todos los paquetes si prefieres. Copia el token que empieza con npm_ y añádelo a los secrets de GitHub como NPM_TOKEN en Settings Secrets and variables Actions New repository secret.
9 Versionado semántico usa npm version patch para arreglos npm version minor para nuevas funcionalidades y npm version major para cambios incompatibles Cada comando además actualiza package.json crea un commit y etiqueta git esa etiqueta vX.Y.Z es la que dispara la automatización en CI.
10 Flujo CI recomendado Configura un workflow en .github/workflows que dispare al push de tags v* que ejecute tests build verifique que la versión del tag coincide con package.json y publique con el token desde el secret usando el flag provenance para mayor seguridad. Asegúrate de usar id-token write en permissions para habilitar la verificación de origen.
11 Publicar con la automatización El flujo de trabajo será simple 1 confirma cambios git add . git commit -m feat añade funcionalidad git push origin master 2 haz el bump npm version patch o minor o major y git push origin master --tags 3 GitHub Actions detecta el tag y se encarga de test build y publish en pocos minutos además crea el release en GitHub automáticamente.
12 Controlar el contenido del paquete Revisa qué se publica con npm pack --dry-run normalmente quieres incluir dist README.md LICENSE package.json y excluir src tests y archivos de configuración con .npmignore para mantener el paquete ligero.
13 Documentación útil El README es la primera impresión incluye instalación ejemplos de uso listados de API problemas comunes y soluciones y opcionalmente ejemplos avanzados diferencias entre navegador y Node y guía de contribución. La documentación bien hecha impulsa la adopción más que el código perfecto.
14 Licencia y colaboración Añade un LICENSE por ejemplo MIT si quieres permisividad añade CONTRIBUTING.md usa Issues para bugs y Discussions para preguntas y etiqueta correctamente los releases. Si prefieres crear releases manuales puedes hacerlo pero con el workflow en marcha la publicación se automatiza al empujar la etiqueta.
15 Cuando algo sale mal Si publicas por error una versión puedes despublicar dentro de 24 horas con npm unpublish @scope/paquete@version pasado ese tiempo no podrás borrar y la opción es npm deprecate @scope/paquete@version Mensaje explicando que la versión está rota y publicar la corrección. Siempre revisar antes de etiquetar para evitar problemas.
Consejos prácticos crea scripts de ayuda para publicar en un solo comando por ejemplo un script que ejecute npm version patch y git push origin master --tags para que la acción manual sea mínima y deje a GitHub Actions encargarse del resto.
Checklist antes de publicar prueba con npm pack e instalar localmente ejecuta tests y typechecks actualiza README y CHANGELOG incluye tipos TypeScript si aplica añade LICENSE y configura CI CD para pruebas automáticas.
Ejemplo real Esta guía se basa en el proceso de convertir un generador HTML a PDF en un paquete reutilizable que pasó de estar acoplado a un proyecto a ser framework agnóstico con soporte para React Vue y Node y tipos TypeScript además de publicación automatizada. Ese paquete resolvió un problema real para generar PDFs multipágina con paginación inteligente sin pelear con diálogos de impresión.
Sobre Q2BSTUDIO Q2BSTUDIO es una empresa de desarrollo de software que ofrece soluciones a medida para empresas incluyendo aplicaciones a medida y software a medida así como servicios avanzados de inteligencia artificial y ciberseguridad. Si buscas desarrollar una solución personalizada puedes conocer nuestro enfoque en desarrollo de aplicaciones a medida y si tu proyecto necesita capacidades de IA para empresas o agentes IA visita nuestra página de inteligencia artificial para empresas. También trabajamos con servicios cloud aws y azure, servicios de inteligencia de negocio y soluciones como power bi para transformar datos en decisiones.
Palabras clave integradas aplicaciones a medida software a medida inteligencia artificial ciberseguridad servicios cloud aws y azure servicios inteligencia de negocio ia para empresas agentes IA power bi ayudan a mejorar el posicionamiento web mostrando la experiencia de Q2BSTUDIO en estas áreas.
Reflexión final Publicar tu primer paquete de NPM es un rito de paso que puede ser confuso y a la vez muy gratificante. No esperes a tener código perfecto empieza con algo útil documenta bien y itera. Si necesitas apoyo profesional para empaquetar una librería, crear CI CD, reforzar seguridad o integrar IA en tus productos Q2BSTUDIO puede acompañarte en el proceso y acelerar tu camino a producción.