Guía de Comandos Esenciales de npm para Gestión de Paquetes

Conceptos Fundamentales de npm

npm (Node Package Manager) es el gestor de paquetes predeterminado para Node.js y representa el registro de softwrae más grande del mundo.

Archivos Principales del Proyecto

package.json: Archivo de configuración del proyecto. Contiene metadatos, scripts y la lista de dependencias.
package-lock.json: Bloquea las versiones exactas de las dependencias para garantizar instalaciones reproducibles.
node_modules/: Directorio donde se almacenan los paquetes instalados.
.npmrc: Archivo de configuración personal de npm para ajustes como fuentes de registro o proxy.

Inicialización de un Proyecto

Para crear un nuevo archivo de configuración de proyecto, se pueden utilizar los siguientes comendos:

# Creación interactiva (recomendado para definir cada campo)
npm init

# Creación rápida con valores por defecto
npm init --yes
# o la abreviatura
npm init -y

Para establecer valores predeterminados como autor o licencia, se configuran en npm:

npm config set init-author-name "Tu Nombre"
npm config set init-author-email "tu@email.com"
npm config set init-license "MIT"

Instalación de Paquetes

La instalación de paquetes se realiza con el comando install (o su alias i). Las dependencias se clasifican según su propósito.

# Instalar todas las dependencias listadas en package.json
npm install

# Añadir un paquete como dependencia de producción
npm install nombre-del-paquete

# Añadir un paquete como dependencia de desarrollo
npm install nombre-del-paquete --save-dev

# Instalar un paquete de forma global
npm install nombre-del-paquete -g

# Instalar una versión específica de un paquete
npm install nombre-del-paquete@2.1.0

# Instalar la última versión disponible
npm install nombre-del-paquete@latest

Tipos de Dependencias

Dependencia de producción (dependencies): Paquetes necesarios para la ejecución de la aplicación. Se instalan con npm install <pkg>.
Dependencia de desarrollo (devDependencies): Herramientas para desarrollo, pruebas o compilación (ej. linters, test runners). Se instalan con npm install <pkg> --save-dev.
Dependencia opcional (optionalDependencies): Paquetes que no causan error si su instalación falla. Se instalan con npm install <pkg> --save-optional.

Actualización y Eliminación de Paquetes

Eliminación

# Eliminar un paquete local y su entrada en package.json
npm uninstall nombre-del-paquete

# Eliminar un paquete de desarrollo
npm uninstall nombre-del-paquete --save-dev

# Eliminar un paquete instalado globalmente
npm uninstall -g nombre-del-paquete

Actualización

# Mostrar paquetes con actualizaciones disponibles
npm outdated

# Actualizar todos los paquetes según los rangos de versión en package.json
npm update

# Actualizar un paquete específico
npm update nombre-del-paquete

npm update respeta el rango de versiones definido en package.json (ej. "lodash": "^4.17.0" solo actualiza dentro de la versión 4.x). Para forzar la actualización a la última versión principle, se debe instalar explícitamente:

npm install nombre-del-paquete@latest

Ejecución de Scripts

Los scripts definidos en package.json se ejecutan con npm run. Algunos nombres de script comunes (start, test, restart, stop) son accesibles directamente.

{
  "scripts": {
    "iniciar": "node servidor.js",
    "desarrollo": "nodemon servidor.js",
    "compilar": "webpack --mode production",
    "pruebas": "jest --coverage",
    "formatear": "prettier --write ."
  }
}

# Ejecutar un script personalizado
npm run desarrollo

# Ejecutar el script 'start'
npm iniciar

# Pasar argumentos adicionales al script
npm run compilar -- --verbose

# Ejecutar scripts pre y post automáticamente
# Ejemplo: preiniciar se ejecuta antes de 'iniciar', postiniciar después.

Para ejecutar varios scripts en paralelo, se puede usar el carácter & o herramientas como npm-run-all.

Consulta de Información

# Listar paquetes instalados localmente (solo primer nivel)
npm list --depth=0

# Listar paquetes instalados globalmente
npm list -g --depth=0

# Ver información detallada de un paquete en el registro
npm view nombre-del-paquete

# Ver la última versión de un paquete
npm view nombre-del-paquete version

# Buscar paquetes por palabra clave
npm search palabras-clave

# Abrir la documentación de un paquete en el navegador
npm docs nombre-del-paquete

Publicación y Mantenimiento de Paquetes

Publicación

# Iniciar sesión en la cuenta de npm
npm login

# Publicar el paquete (requiere incrementar versión previamente)
npm publish

# Publicar una versión de pre-lanzamiento (ej. beta)
npm publish --tag beta

# Declarar una versión como obsoleta (mantiene el paquete)
npm deprecate nombre-del-paquete@1.0.0 "Esta versión está obsoleta, usa la 2.0.0"

Control de Versiones Semántico (SemVer)

El comando npm version incrementa automáticamente la versión en package.json siguiendo las reglas de SemVer:

# Incremento de parche (1.0.0 -> 1.0.1): Correcciones de bugs
npm version patch

# Incremento menor (1.0.0 -> 1.1.0): Nuevas funcionalidades compatibles
npm version minor

# Incremento mayor (1.0.0 -> 2.0.0): Cambios incompatibles
npm version major

Solución de Problemas Comunes

Velocidad de Instalación

Si la instalación es lenta, se puede configurar una fuente de registro más cercana:

# Usar un espejo (ej. China) temporalmente
npm install nombre-del-paquete --registry=https://registry.npmmirror.com

# Configurar el espejo de forma permanente
npm config set registry https://registry.npmmirror.com

Errores de Permisos (EACCES)

Para instalar paquetes globales sin usar sudo, es recomendable cambiar el directorio de instalación global de npm:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# Añadir ~/.npm-global/bin al PATH del sistema en el archivo de perfil (.bashrc, .zshrc)
export PATH=~/.npm-global/bin:$PATH

Dependencias Corruptas

Para limpiar completamente el entorno de paquetes:

# Eliminar el directorio de módulos y el archivo de bloqueo
rm -rf node_modules package-lock.json

# Limpiar la caché de npm
npm cache clean --force

# Reinstalar todo desde cero
npm install

Conflictos en package-lock.json

En caso de conflictos en control de versiones, se puede optar por regenerar el archivo:

# Aceptar la versión remota del archivo lock
git checkout --theirs package-lock.json
npm install

# o eliminarlo y dejar que npm lo regenere
rm package-lock.json
npm install

Etiquetas: npm Node.js package.json gestión de paquetes JavaScript

Publicado el 7-7 04:26

Friki Work