¿Cuál es la diferencia entre npm update y npm-check-updates (ncu)?

El comando estándar npm update respeta los rangos de versiones definidos en tu package.json según semver (^ y ~), por lo que solo instala versiones menores o parches que no rompan compatibilidad. En cambio, npm-check-updates (ncu) consulta todo el registro de npm para encontrar todas las versiones nuevas disponibles (incluyendo versiones mayores con cambios incompatibles) y actualiza tu package.json directamente.

¿Cómo actualizo solo versiones menores y parches sin cambios mayores incompatibles?

Puedes ejecutar 'ncu --target minor -u' o 'ncu --target patch -u'. Esto le indica a npm-check-updates que actualice tus paquetes a la versión menor o parche más reciente compatible, ignorando por completo las versiones mayores con cambios que puedan romper tu código.

¿npm-check-updates soporta monorepos y workspaces?

Sí. Puedes ejecutar 'ncu --workspaces' (o 'ncu -ws') desde la raíz de tu monorepo. Inspecciona y actualiza de forma recursiva las dependencias en todos los paquetes del workspace en npm, pnpm y yarn.

¿Funciona ncu con otros gestores de paquetes como pnpm, yarn y bun?

Sí. npm-check-updates detecta tu gestor de paquetes de forma automática o te permite indicarlo con la opción '--packageManager' (por ejemplo, 'ncu --packageManager pnpm' o 'ncu --packageManager bun').

Cómo actualizar dependencias de NPM fácilmente con npm-check-updates (ncu)

Mantener las dependencias de un proyecto al día es una de esas tareas de mantenimiento de rutina que pueden volverse frustrantes muy rápido. Cuando trabajo en varias aplicaciones, abrir el package.json para verificar manualmente decenas de librerías contra el registro de npm resulta tedioso, propenso a errores y consume demasiado tiempo.

El comando integrado npm outdated te ayuda a ver qué paquetes se quedaron atrás, pero no modifica tu package.json para llevarlos a las últimas versiones mayores de forma automática.

Por eso uso npm-check-updates (a menudo abreviado como ncu). Ofrece una forma rápida, visual y segura de revisar, filtrar y actualizar dependencias en npm, pnpm, yarn y bun.

En esta guía te mostraré cómo instalar y usar ncu, cómo aprovechar el modo interactivo, cómo filtrar actualizaciones por objetivos de semver y cómo gestionar workspaces en monorepos sin riesgos.

Empecemos ejecutando nuestro primer análisis.

1. Comprobar actualizaciones con `ncu` 🔍

Ni siquiera necesitas instalar npm-check-updates de forma global para probarlo. Puedes ejecutarlo directamente con npx en cualquier carpeta de tu proyecto:

npx npm-check-updates

Si prefieres tener el comando global disponible en cualquier lugar de tu máquina, instálalo con:

npm install -g npm-check-updates

Al ejecutar ncu en un proyecto con dependencias desactualizadas, la herramienta analiza tu package.json y muestra un resumen con código de colores:

$ ncu
Checking /Users/danyparedes/project/package.json
[====================] 14/14 100%
 
 @types/node           ^20.10.0  →   ^22.13.0     (minor / major)
 next                  ^14.2.0   →   ^15.2.0      (major)
 react                 ^18.3.1   →   ^19.0.0      (major)
 tailwindcss            ^3.4.0   →    ^4.0.0      (major)
 zod                   ^3.22.4   →   ^3.24.1      (patch)
 
Run ncu -u to upgrade package.json

Significado de los colores

Verde: Versiones de tipo parche seguras (por ejemplo, ^3.22.0 → ^3.22.4).
Cian / Amarillo: Actualizaciones menores con nuevas funciones (por ejemplo, ^20.10.0 → ^20.14.0).
Rojo: Cambios mayores incompatibles que requieren pruebas (por ejemplo, ^18.0.0 → ^19.0.0).

Ahora que sabemos qué paquetes necesitan actualizarse, veamos cómo guardar esos cambios directamente en nuestro package.json.

2. Actualizar el `package.json` e instalar dependencias 🚀

Ejecutar ncu a secas solo muestra las diferencias: no modifica tus archivos.

Para escribir las nuevas versiones directamente en tu package.json, usa la opción -u (upgrade):

# 1. Actualizar las versiones en package.json
ncu -u
 
# 2. Instalar las nuevas dependencias
npm install

Consejo práctico: Puedes combinar la revisión, escritura e instalación en un solo paso usando ncu -i o encadenándolo con tu gestor de paquetes preferido:

# Para pnpm
ncu -u && pnpm install
 
# Para Bun
ncu -u && bun install
 
# Para Yarn
ncu -u && yarn install

Actualizar todo de golpe puede introducir cambios que rompan tu proyecto. Veamos cómo controlar qué niveles de semver actualizar.

3. Actualizaciones seguras por objetivo (solo parches y versiones menores) 🛡️

Cuando preparas un despliegue a producción o un hotfix, normalmente buscas corregir errores y añadir funciones menores sin arriesgarte a que cambie la API de tus librerías. npm-check-updates te permite definir el nivel de semver que quieres como objetivo usando --target:

# Actualizar solo versiones de parche (menor riesgo)
ncu --target patch -u
 
# Actualizar versiones menores y parches (sin cambios mayores incompatibles)
ncu --target minor -u

Comparativa de objetivos soportados

Opción de Target	Comando de ejemplo	Qué se actualiza	Nivel de riesgo
`latest` (por defecto)	`ncu -u`	La versión más alta disponible, incluyendo versiones mayores	Alto (requiere pruebas)
`minor`	`ncu --target minor -u`	La versión menor o parche más alta dentro de la versión mayor actual	Bajo / Medio
`patch`	`ncu --target patch -u`	El parche más reciente para la versión menor actual	Mínimo
`greatest`	`ncu --target greatest -u`	Incluye versiones preliminares o candidatas (`beta`, `canary`)	Experimental

Ahora pasemos a mi funcionalidad favorita: el modo de selección interactivo.

4. Modo interactivo (`--interactive`) 🎯

Si quieres un control granular sobre qué paquetes específicos actualizar, ejecuta ncu en modo interactivo:

ncu --interactive --format group

Esto abre una interfaz en la terminal donde puedes:

Usar las flechas del teclado para moverte.
Presionar la barra espaciadora (Space) para seleccionar o deseleccionar paquetes.
Ver los paquetes agrupados de forma lógica por parche, versión menor y versión mayor.
Presionar Enter para aplicar tu selección.

? Choose which packages to update:
 
Patch (Safe bug fixes)
❯ ◯ zod            ^3.22.0  →  ^3.22.4
 
Minor (New features)
  ◯ @types/node   ^20.10.0  →  ^20.14.0
 
Major (Breaking changes)
  ◯ react          ^18.3.1  →  ^19.0.0
  ◯ next           ^14.2.0  →  ^15.2.0

Este flujo de trabajo te da total claridad antes de aplicar cualquier cambio en tu package.json.

Ahora bien, ¿qué pasa si quieres actualizar todo excepto un par de paquetes concretos? Veamos cómo filtrarlos.

5. Filtrar y excluir paquetes específicos 🎛️

Puedes filtrar nombres de paquetes usando coincidencias de texto, comodines o expresiones regulares.

Actualizar únicamente paquetes específicos (`--filter` / `-f`)

# Actualizar solo dependencias del ecosistema de React
ncu -f "react*" -u
 
# Actualizar solo TypeScript y definiciones de tipos
ncu -f "@types/*,typescript" -u

Excluir paquetes delicados (`--reject` / `-x`)

Si prefieres mantener un paquete sensible en su versión actual, usa --reject:

# Actualizar todo EXCEPTO webpack y jest
ncu -x "webpack,jest" -u

A continuación, veamos cómo gestionar actualizaciones cuando trabajas con monorepos.

6. Soporte para monorepos y workspaces (`--workspaces`) 🏢

Si administras un monorepo con Turborepo, Nx o los workspaces nativos de npm, pnpm o yarn, no hace falta que hagas cd en cada carpeta individual.

Ejecuta ncu con la opción --workspaces (o -ws):

# Revisar todos los paquetes del workspace
ncu --workspaces
 
# Actualizar todos los workspaces de forma interactiva en un solo paso
ncu --workspaces --interactive

Para actualizar también las dependencias de la raíz además de las de los paquetes del workspace:

ncu --workspaces --root -u

Esto ahorra mucho tiempo en proyectos grandes. Ahora veamos cómo automatizar estos comandos en scripts para compartirlos con el resto del equipo.

7. Scripts útiles como atajos en tu `package.json` ⚡

Para que el mantenimiento de dependencias sea muy sencillo para todo tu equipo, te recomiendo agregar scripts dedicados en el package.json raíz:

{
  "scripts": {
    "deps:check": "npx npm-check-updates",
    "deps:safe": "npx npm-check-updates --target minor -u && npm install",
    "deps:interactive": "npx npm-check-updates --interactive --format group"
  }
}

De esta manera, cualquier integrante del equipo puede ejecutar npm run deps:interactive para revisar y actualizar dependencias del proyecto sin tener que memorizar las opciones de la terminal.

Resumen 🛠️

npm-check-updates transforma un proceso de actualización de dependencias potencialmente complicado en un flujo seguro y controlado:

ncu: Escaneo rápido de solo lectura de paquetes desactualizados.
ncu -u: Escribe las versiones más recientes en el package.json.
ncu --target minor -u: Actualiza versiones menores y parches seguros sin introducir cambios incompatibles.
ncu -i --format group: Selector interactivo para revisar las actualizaciones paquete por paquete.
ncu -ws: Actualizaciones con un solo comando para todos los workspaces de un monorepo.

Si quieres más consejos sobre experiencia de desarrollo y herramientas, echa un vistazo a mis artículos sobre Cómo detectar y corregir dependencias circulares en TypeScript y Migración de Next.js de Vercel a GCP Cloud Run.