«npm WARN requires a peer»: cómo corregir y entender la esencia del error

Introducción: ¿por qué npm te grita?

¿Alguna vez has ejecutado npm install y has visto algo como esto?

npm WARN ts-patch@3.2.1 requires a peer of typescript@>=4.0 but none is installed. You must install peer dependencies yourself.

¿Te suena? Si es así, no estás solo. Esta pregunta en Stack Overflow ha acumulado miles de visitas y decenas de comentarios de desarrolladores que, como tú, solo querían instalar un paquete y terminaron con un dolor de cabeza. Hoy analizaremos qué son las peer dependencies, por qué npm insiste tanto en que las instales y cómo trabajar correctamente con ellas en proyectos TypeScript. Y sí, esto no será documentación aburrida, sino un análisis vivo con ejemplos de código.

¡Allá vamos!

¿Qué son las peer dependencies y para qué sirven?

Imagina que estás armando un rompecabezas. Tienes la imagen principal (tu proyecto) y varias piezas (paquetes). Algunas piezas encajan perfectamente entre sí, pero solo si usas el marco correcto. En el mundo de npm, ese «marco» es una peer dependency.

Una peer dependency (o «dependencia par») es un requisito de un paquete de que una determinada biblioteca debe estar instalada en el proyecto, pero el paquete mismo no la instalará. ¿Por qué? Porque esa biblioteca ya debería estar en tu proyecto, y el paquete simplemente «se lleva bien» con ella, sin crear duplicados.

Por ejemplo, el paquete ts-patch (una herramienta popular para TypeScript) requiere que typescript esté instalado en el proyecto. Pero ts-patch no instala TypeScript por sí mismo; asume que ya lo has agregado. Si TypeScript no está, npm muestra esa advertencia.

¿Por qué es importante para proyectos TypeScript?

TypeScript no es solo un lenguaje, es un ecosistema. Muchos paquetes (por ejemplo, @types/react, ts-loader, eslint-plugin-typescript) funcionan sobre TypeScript. Si tienes instalada la versión 5.0 de TypeScript y el paquete requiere 4.0+, todo está bien. Pero si TypeScript no está instalado, empiezan los problemas.

Aquí tienes un ejemplo real de la vida. Supongamos que escribes un pequeño script en TypeScript y usas ts-patch para transformar el código. Ejecutas:

npm install ts-patch --save-dev

Y obtienes:

npm WARN ts-patch@3.2.1 requires a peer of typescript@>=4.0 but none is installed.\nYou must install peer dependencies yourself.

¿Qué hacer? ¿Entrar en pánico? No. Simplemente instala TypeScript:

npm install typescript --save-dev

Problema resuelto. Pero, ¿y si ya tienes TypeScript, pero de otra versión? Aquí empieza lo interesante.

Comparación de enfoques: cómo instalar peer dependencies

Existen varias formas de solucionar este error. Vamos a compararlas usando un proyecto TypeScript como ejemplo.

Enfoque 1: Instalación manual (clásico)

La forma más simple y confiable es leer la advertencia e instalar manualmente el paquete necesario. Ves que se requiere typescript@>=4.0 y lo agregas:

npm install typescript@^4.0 --save-dev

Ventajas:

\n
• Control total sobre la versión.
\n
• Sin sorpresas ocultas.
\n

Desventajas:

\n
• Hay que leer atentamente los mensajes de npm.
\n
• Si hay muchos paquetes, el proceso se vuelve tedioso.
\n

Este enfoque es ideal para proyectos pequeños, donde sabes exactamente qué dependencias necesitas.

Enfoque 2: Instalación automática con npx o plugins

Algunas herramientas, como npm-check o install-peerdeps, pueden instalar automáticamente todas las peer dependencies de un paquete específico. Instala la utilidad globalmente:

npm install -g install-peerdeps