NPM: gestor de paquetes de Node.js, package.json y scripts npm
NPM, el gestor de paquetes de Node.js: qué es, la estructura y los campos de package.json, los scripts de desarrollo, el control de versiones y su ecosistema de paquetes.
Navegando en el blogver navegación en todos los blogs
Node.js ha estado transformando el desarrollo web desde su lanzamiento en 2009, impulsado por una comunidad vibrante y un gran ecosistema de paquetes. Uno de los pilares fundamentales detrás del éxito de Node.js es npm (Node Package Manager), la herramienta que facilita el compartir e intercambiar código entre desarrolladores.
NPM no solo es esencial para construir aplicaciones JavaScript, sino que también ha convertido en un componente integral del flujo de trabajo de los desarrolladores. Este artículo te guiará a través de lo básico y avanzado de npm, desde su instalación hasta la creación y publicación de tus propios paquetes, ese mismo ecosistema que sostiene herramientas como Graphify o el Vault CMS de Astro.
NPM, o “Node Package Manager,” es el administrador de paquetes predeterminado para Node.js. Es conocido por sus alias creativos como “Ninja Pumpkin Mutants” o “Nonprofit Pizza Makers.” Su principal función es facilitar la distribución y gestión de bibliotecas y herramientas JavaScript.
La estructura básica de NPM consta de dos partes principales:
- CLI (Interfaz de Línea de Comandos): Herramienta que permite a los desarrolladores publicar, descargar y gestionar paquetes.
- Repositorio En Línea: Almacena e intercambia paquetes de JavaScript.
Visualmente, el repositorio npmjs.com funciona como un mercado donde los desarrolladores pueden compartir sus proyectos como “bienes” que son luego comprados por otros miembros de la comunidad.
Cada proyecto JavaScript, ya sea para Node.js o navegadores, puede ser tratado como un paquete npm con su propio archivo package.json. Este archivo es fundamental para describir el proyecto y sus dependencias.
Un ejemplo básico de package.json podría verse así:
En la práctica: proyectos como el Vault CMS con Astro o herramientas como Graphify se instalan y gestionan íntegramente con npm, y sus dependencias son las que permiten funcionalidades como la búsqueda con Pagefind o la generación de tarjetas OG.
En conclusión, dominar npm es la puerta de entrada al ecosistema JavaScript que sostiene proyectos como el Vault CMS, herramientas como Graphify y cualquier desarrollo moderno con Astro.
Nota:
npm run <script>ejecuta cualquier script definido en la sección"scripts"delpackage.json. Todos los scripts aquí listados son locales (se ejecutan dentro del proyecto markeup) y pueden combinarse con banderas (--yes,--check-deploy,--watch, etc.) según la necesidad.
Lanza el servidor de desarrollo de Astro (astro dev). Ideal para trabajar en los posts mientras ves el resultado en tiempo real.
Ejecuta el script que procesa y optimiza todas las imágenes del proyecto (node scripts/js/process-images.js).
Modo watch: vuelve a procesar imágenes automáticamente cada vez que se modifica alguna fuente.
Sincroniza las imágenes locales con la carpeta pública (public/img/).
Aplica la sincronización de imágenes (procesa y copia).
Aplica sincronización incluyendo también los archivos de origen (útil cuando se añaden nuevas imágenes).
Genera subconjuntos de fuentes (por ejemplo, solo los pesos y caracteres necesarios) usando un script Python.
Crea tarjetas Open Graph para redes sociales (node scripts/mjs/og-cards.mjs).
Fuerza la regeneración de las tarjetas Open Graph (útil cuando cambian metadatos).
Pipeline completo de construcción: valida audio, procesa imágenes, genera OG, hace el build de Astro, crea el índice de búsqueda y aplica el “stamp”.
Sólo el build de Astro (astro build). Se usa cuando se quiere recompilar sin los pasos auxiliares.
Genera el índice de búsqueda con Pagefind (solo en español) y actualiza la versión del stamp.
Aplica el “stamp” de versión al build (marca temporal o número de versión).
Inicia el servidor de previsualización de Astro (astro preview).
Ejecuta el script bash scripts/sh/publish.sh, que valida, hace build y despliega a Cloudflare Pages.
Publica el sitio con la opción --yes (no pide confirmación). Equivalente a publish pero automatizado.
Sólo verifica el estado de despliegue sin volver a publicar (útil para auditorías).
Controla el servicio autopublish (launchd + watchexec) que vigila src/content/posts/ —solo el contenido publicable— y publica automáticamente, como mucho una vez cada dos minutos (MARKEUP_MIN_INTERVAL).
Exporta el contenido del blog a otro formato (por ejemplo, JSON o Markdown plano).
Ejecuta los tests unitarios/integración con Vitest una sola vez.
Modo watch de Vitest: vuelve a ejecutar los tests al detectar cambios.
Pruebas de accesibilidad (WCAG) sobre el sitio generado.
Valida que el frontmatter de cada post cumpla con la especificación (22 campos, de los que 4 son duros, descripción 140-200 caracteres, slug único, categoría válida, etc.). El SEO (title 50-75, description 140-200) lo mide npm run validate:seo.
Comprueba que todas las imágenes referenciadas existen y son válidas.
Verifica los metadatos de compartición (Open Graph, Twitter Card, etc.).
Detecta colisiones de slug o alias no permitidos.
Linter de la Regla de Oro: avisa de los wikilinks de párrafo sin alias descriptivo (con --strict los bloquea) y de la sintaxis rota, que siempre bloquea.
Enriquecer los wikilinks (añadir backlinks, crear notas huérfanas) – modo dry-run para revisar antes de aplicar.
Aplica los cambios de enriquecimiento de wikilinks (sin modo dry-run).
Herramienta de búsqueda rápida para desarrollo (consulta los posts localmente).
Ejecuta la CLI general del proyecto (markeup_tools).
Crea un nuevo post (orquesta el pipeline completo mediante la skill markeup-post-creator).
Crea un borrador de post (sin publicar, útil para bosquejar).
Audita la salud del vault (frontmatter, wikilinks, slugs, etc.).
Genera estadísticas resumidas del vault (número de posts, tags, etc.).
Regenera el índice del vault (vault-index.md).
Corrige tags mal formados (mayúsculas, espacios, inconsistencias).
Busca notas dentro del vault (por contenido o frontmatter).
Analiza los backlinks (qué notas enlazan a la actual).
Sugiere notas relacionadas con la nota actual (basado en tags y wikilinks).
Detecta notas huérfanas (sin wikilinks entrantes) y las registra en el backlog.
Interactúa con el agente Hermes (por ejemplo, para usar sus habilidades).
Consulta el estado de Ollama (modelos locales).
Conecta el entorno de Syncthing (para la sincronización automática).
Script que realiza commit automático después de validar y enriquecer notas.
Conecta/usa la CLI de Hermes (integración con el agente IA).
(Alias) para conectar Syncthing.
Comprime archivos de audio (optimiza bitrate, elimina silencio, etc.).
Modo watch para comprimir audio en tiempo real.
Fuerza la compresión de todos los archivos de audio, sobrescribiendo los originales.
Compresión manteniendo los archivos originales (no los sobrescribe).
Ejecuta una comprobación dry-run sin modificar nada.
Formatea todos los archivos fuente (*.astro, *.ts, *.js, *.mjs, *.css, *.json).
Sólo verifica el formato (no modifica).
Linter ESLint sobre scripts/ y src/lib/.
Configura los hooks de husky (ejecutado antes de git commit).
El gate único npm run verify:content —validate:frontmatter, validate:seo, validate:slugs, validate:wikilinks, validate:books y validate:media— más validate:icons.
Siempre ejecuta primero npm run deploy:check para asegurarte de que no haya errores pendientes.
npm run autopublish activa el servicio que publica automáticamente cuando editas en el móvil; npm run autopublish -- disable lo apaga temporalmente.
La mayoría de los comandos bajo tools:* son invocaciones a la skill markeup-cli-tools; son la forma “oficial” de crear, auditar, buscar, etc., dentro del vault.
Con este catálogo tienes todos los comandos npm que puedes usar en el proyecto markeup. Si necesitas ejecutar alguno en concreto, solo escribe npm run <nombre-del-script> en la terminal.
NPM: El Administrador de Paquetes para Node.js
Explora las ramas del artículo