Diff de package.json: comparar manifiestos npm online
Pega el package.json antiguo a la izquierda, el nuevo a la derecha, y ve exactamente qué dependencias, scripts y engines cambiaron. Se ejecuta en tu navegador, nada se sube.
Qué es esta herramienta de diff de package.json
Una herramienta gratuita que se ejecuta en el navegador para comparar dos archivos npm package.json lado a lado. Pega el manifiesto antiguo a la izquierda, el nuevo a la derecha, y las diferencias se resaltan carácter a carácter. El texto nunca sale de tu máquina, lo cual importa cuando el manifiesto pertenece a un repositorio privado o a un producto sin lanzar.
Está pensada para ese momento en que llega una PR de Renovate o Dependabot y necesitas saber qué cambió de verdad más allá de los bumps de versión. ¿Alguien coló una edición de script? ¿El campo engines pasó de Node 18 a Node 20? ¿Se ajustó una peerDependency? La vista de diff de GitHub responde parte de esto, pero pegar dos manifiestos en una vista limpia de dos paneles es más rápido cuando estás revisando varias PRs seguidas o comparando ramas que aún no se han subido.
Por debajo es el mismo diff con conocimiento de JSON que mueve nuestra página compare-json, con marco y texto afinados para flujos de npm y yarn. Ambos manifiestos se parsean como JSON y se imprimen con formato antes de correr el diff, así las diferencias cosméticas de espacios no contaminan el resaltado. Si necesitas un diff de texto crudo para un formato de manifiesto que no sea JSON, nuestra herramienta compare-text lo cubre, y compare-yaml maneja pnpm-lock.yaml.
Cómo funciona el diff en realidad
Cada panel se parsea como JSON. Si el parseo tiene éxito, el manifiesto se reformatea con sangría consistente de dos espacios y se preserva el orden de las claves tal como están escritas. Si el parseo falla (una coma de más, una llave faltante, un copia-pega que agarró pocos caracteres) la herramienta cae a modo texto plano y te dice qué línea se rompió. Una vez que ambos lados son JSON válido, el diff corre carácter a carácter, luego una pasada de limpieza semántica reagrupa los cambios en bloques legibles, así un bump de versión de ^18.2.0 a ^19.0.0 se lee como una edición, no nueve ediciones de carácter.
Las inserciones en el panel derecho aparecen en verde; las eliminaciones en el panel izquierdo aparecen en rojo. Los dos paneles tienen scroll sincronizado, así que cuando encuentras un cambio en el fondo de devDependencies en un lado, el otro salta a la misma clave. Como el diff es a nivel de texto tras el formateo, ve los cambios estructurales como los lee una persona: una dependencia eliminada desaparece como línea, un rango semver cambiado se resalta dentro del valor, un script nuevo encaja en el bloque scripts en la posición donde lo pusiste.
Lo que la herramienta deliberadamente no hace: no es un resolutor de dependencias. No te dirá qué paquetes transitivos arrastra un bump de rango caret, si un peer está satisfecho, o si la versión nueva introduce un aviso de seguridad. Para eso, ejecuta npm install seguido de npm audit en local, o usa npm con un servicio que entienda lockfiles como Snyk o las alertas de Dependabot de GitHub. Esta página te dice qué dice el texto del manifiesto. El trabajo de resolución pertenece a tu gestor de paquetes.
Cómo hacer un diff de package.json en tres pasos
Dos paneles de texto, un diff. Sin flags de CLI, sin paso de instalación, sin formato de patch que leer.
- 1
Pega el manifiesto antiguo a la izquierda
Copia la versión previa de package.json desde tu editor, desde git show main:package.json, o de un compañero. Pega en el panel izquierdo. La herramienta lo parseará como JSON y lo formateará; si el JSON es inválido, el editor mostrará el error de parseo para que arregles el fragmento antes de hacer el diff.
- 2
Pega el manifiesto nuevo a la derecha
Haz lo mismo con la versión actualizada. Si estás revisando una PR de Renovate o Dependabot, la fuente más fácil es el archivo crudo de la rama de la PR. Ambos archivos se formatean con sangría consistente, así que las ediciones cosméticas de espacios no aparecerán como cambios falsos en el diff.
- 3
Lee las diferencias resaltadas
Las eliminaciones aparecen como tachados rojos a la izquierda; las inserciones aparecen en verde a la derecha. Escanea primero los bloques de dependencias, luego revisa la sección scripts buscando ediciones de comandos, después los campos engines y peerDependencies. Los bumps de versión dentro de un solo valor resaltan los caracteres cambiados, así puedes distinguir un bump de patch de uno mayor de un vistazo.
Cuándo un diff de package.json es la decisión correcta
Revisar una PR de Renovate o Dependabot
Un bot abre quince PRs en una mañana. La mayoría son rutina, pero una coló un cambio de script, o una peerDependency apretada, o un bump de engines que rompe tu imagen de CI. El título de la PR dice "chore(deps): bump foo from 4.1.0 to 4.2.1" y confías en piloto automático. Pega el package.json antes y después en el diff y puedes verificar en cinco segundos que nada más se movió. Esta es la razón más común por la que los ingenieros JS recurren a un diff de manifiesto.
Comparar dos ramas antes de mergear
Tú y un compañero ambos tocaron package.json en ramas de feature distintas. Git mergeará limpiamente porque las ediciones están en bloques diferentes, pero un merge limpio no significa uno correcto. Pega los manifiestos de las dos ramas en el diff para detectar un script que una rama eliminó, una dependencia que una rama bajó de versión, o un choque donde ambas ramas añadieron el mismo paquete en versiones distintas. Más barato que descubrirlo después de que CI corra npm ci contra el resultado mergeado.
Auditar qué promovió npm install en package-lock.json
Editar package.json es la mitad del cambio. La otra mitad es lo que package-lock.json registra sobre el árbol resuelto. Tras correr npm install, pega el lockfile antiguo junto al nuevo para ver qué paquetes transitivos vinieron en el viaje. Las adiciones sorpresa son comunes cuando un rango caret arrastra un nuevo minor de una dependencia muy anidada. Para inspección de lockfiles crudos nuestra página compare-json maneja mejor los archivos grandes; esta página es mejor para el manifiesto en sí.
Comprobar un downgrade tras una regresión
Sale una release, aparece un bug, haces bisect, y el sospechoso está en algún sitio del árbol de dependencias. Pega el package.json de la última release buena junto al actual. Descarta mentalmente los bloques sin cambios y enfócate en los rangos de versión resaltados. La solución suele ser bajar de versión una librería al pin de la última build verde. Una vez que encuentres al sospechoso, fíjalo con una versión exacta (sin caret, sin tilde) hasta que se resuelva el problema upstream.
Comparar tu manifiesto local con el de un compañero
Dos ingenieros, un merge complicado, dos archivos package.json distintos al final del rebase. El lockfile está aún más confundido. Pega los dos manifiestos lado a lado para ver qué claves discrepan, luego resuélvelas deliberadamente en lugar de aceptar el resultado de git merge -X theirs sin leerlo. Esta también es la herramienta correcta cuando incorporas a un nuevo contribuyente cuyo npm install trae un árbol distinto al tuyo y sospechas una deriva del manifiesto.
Revisión pre-publish del package.json de una librería
Antes de correr npm publish en una librería, los campos del manifiesto que importan son distintos a los de una app: main, module, types, exports, files, peerDependencies, engines. Haz diff del manifiesto a punto de publicarse contra el último publicado. Una entrada de peerDependencies eliminada, una condición de exports cambiada, o un rango de engines apretado pueden romper a los consumidores de formas que npm mismo no te avisará. La documentación de packages de Node.js es la referencia para entender qué significan esos campos.
Campos de package.json que vale la pena conocer
Los campos que aparecen en diffs reales de package.json y qué significan. Vale la pena escanearlos antes de aprobar una PR de Renovate o mergear dos ramas que ambas tocaron el manifiesto.
| Topic | What this tool does |
|---|
| dependencies vs devDependencies vs peerDependencies | dependencies se distribuyen con tu paquete y las instala cualquiera que lo consuma. devDependencies solo se instalan cuando ejecutas npm install en la raíz del proyecto, nunca para los consumidores aguas abajo. peerDependencies son paquetes que tu librería espera que provea el host (típicamente React, el framework de tests, el bundler) y npm 7+ los instalará automáticamente salvo que entren en conflicto. Mover un paquete entre estos bloques cambia quién paga el coste de instalación. |
|---|
| Rangos semver caret (^) vs tilde (~) | El caret ^1.2.3 permite cualquier versión hasta pero sin incluir 2.0.0; este es el predeterminado de npm y el rango común más amplio. El tilde ~1.2.3 permite solo patches, hasta pero sin incluir 1.3.0. 1.2.x es lo mismo que tilde. * significa cualquier versión (no uses esto en producción). latest se resuelve en el momento de la instalación y produce builds no reproducibles, así que evítalo. |
|---|
| Pin exacto (sin prefijo de rango) | Escribir "react": "18.2.0" sin caret ni tilde fija esa versión exacta. Combinado con un lockfile, esto te da la instalación más reproducible al coste de no recibir parches de seguridad automáticamente. Algunos equipos fijan todo; otros confían en la combinación caret más lockfile. No hay una respuesta universalmente correcta, pero el trade-off es builds más deterministas frente a dependencias más desactualizadas. |
|---|
| Determinismo de package-lock.json | package-lock.json registra la versión resuelta exacta de cada paquete en el árbol de dependencias, incluyendo transitivas. npm ci instala desde el lockfile y rehúsa modificarlo; npm install puede actualizarlo si un rango permite una versión más nueva. Para CI, usa siempre npm ci. Para desarrolladores, npm install está bien siempre que commitees el cambio resultante del lockfile. |
|---|
| Campo workspaces para monorepos | El array workspaces le dice a npm que trate los directorios hermanos como paquetes enlazados en un monorepo. npm install en la raíz instala todos los workspaces y crea un único árbol node_modules hoisted. Yarn y pnpm soportan workspaces con sus propias convenciones, y pnpm en particular hoistea menos agresivamente, lo que detecta más bugs de fuga de dependencias en tiempo de instalación. |
|---|
| Campo engines | engines.node declara las versiones de Node.js que tu paquete soporta. Por defecto npm solo avisa cuando el host viola esto; engine-strict=true en .npmrc lo convierte en error duro. Subir el campo engines es un cambio rompedor para consumidores anclados en Node antiguo, y es el tipo de cambio que se esconde dentro de una PR "chore" de Renovate. Lee siempre el diff de engines. |
|---|
| Campo exports para ES modules | El campo exports controla qué rutas pueden importar los consumidores desde tu paquete y qué condiciones (import, require, types, node, browser) resuelven a qué archivos. Añadir o quitar una entrada es un cambio rompedor para el código aguas abajo. La documentación de packages de Node.js cubre las reglas de resolución en detalle; trata cualquier diff de exports como una edición digna de versión mayor a menos que estés añadiendo deliberadamente un punto de entrada nuevo. |
|---|
| Orden de archivos dentro de package.json | No hay un orden forzado para las claves de nivel superior en package.json. Por convención, la mayoría de proyectos empiezan con name, version, description, luego scripts, después dependencias. Dentro de los bloques de dependencias, el orden alfabético por clave es el estándar de facto y la mayoría de gestores de paquetes ordenarán el bloque al guardar. Un diff que muestra entradas reordenadas pero por lo demás idénticas suele ser una diferencia de tooling, no un cambio real. |
|---|
Diff de package.json: preguntas frecuentes
¿En qué se diferencia esto de npm diff o npm-check-updates?
npm diff es un comando integrado de npm que compara dos versiones publicadas de un paquete en el registry, incluyendo sus tarballs y fuentes. npm-check-updates (ncu) reporta qué dependencias en tu manifiesto tienen versiones más nuevas disponibles. Ninguno te muestra la diferencia entre dos archivos package.json arbitrarios que tienes en disco o en dos ramas. Esta herramienta sí. Usa ncu para descubrir qué deberías actualizar, npm diff para ver cambios en el registry entre releases, y esta página para leer tu propio manifiesto antes y después en una vista lado a lado.
¿Audita seguridad o comprueba vulnerabilidades conocidas?
No. Esta página solo hace diff del texto. No consulta el registry de npm, la GitHub Advisory Database, ni ningún servicio de vulnerabilidades. Para auditoría de seguridad, ejecuta npm audit contra un árbol instalado, usa npm audit signatures para verificar la procedencia del paquete, o apóyate en alertas de Snyk, Socket o Dependabot. Esta herramienta es la elección correcta cuando quieres saber qué cambió en el manifiesto. Es la elección equivocada cuando quieres saber si el cambio es seguro de desplegar.
¿Detecta cambios de dependencias transitivas?
No solo desde el manifiesto. package.json solo lista dependencias directas y sus rangos solicitados. El árbol completo resuelto, incluyendo transitivas, vive en package-lock.json (o yarn.lock o pnpm-lock.yaml). Para comparar árboles resueltos, pega ambos lockfiles en un diff. Como los lockfiles son grandes, nuestra página compare-json los maneja mejor que esta. Para pnpm-lock.yaml en particular, usa compare-yaml. Esta página está optimizada para el manifiesto.
¿Cómo comparo dos archivos package-lock.json?
Pega ambos lockfiles en los paneles igual que harías con un manifiesto. La herramienta los parseará como JSON, los formateará y hará diff. Ten en cuenta que los lockfiles pueden llegar a miles de líneas, así que el diff resaltado puede ser largo. Enfócate primero en las entradas packages de nivel superior, luego en los campos version. Para archivos de más de unos cinco mil líneas, nuestra página compare-json encaja mejor porque está montada para manejar payloads grandes de JSON con el mismo motor.
¿Cuál es la diferencia entre los rangos caret (^) y tilde (~)?
Ambos son rangos semver que permiten actualizaciones sin editar manualmente el manifiesto. El caret ^1.2.3 permite cualquier versión que no cambie el dígito no-cero más a la izquierda, así que 1.2.3 hasta 1.999.999 se aceptan, pero 2.0.0 no. El tilde ~1.2.3 es más estricto: solo permite actualizaciones de patch, así que 1.2.3 hasta 1.2.999 se aceptan pero 1.3.0 no. El caret es el predeterminado de npm y el rango más amplio; el tilde es el que usas cuando una librería tiene historial de romper en releases minor.
¿Hay límites de tamaño para lockfiles grandes?
En la práctica sí. El diff corre en tu navegador, así que entradas muy grandes (un lockfile de 20.000 líneas de un monorepo, por ejemplo) pueden ralentizar la página o colgar la pestaña dependiendo de la memoria. Para manifiestos y lockfiles típicos de aplicación de hasta unos pocos miles de líneas por lado, el diff se completa prácticamente al instante. Para archivos más grandes, nuestra página compare-json es el punto de entrada mejor. Si comparas habitualmente lockfiles enormes, considera ejecutar git diff package-lock.json en local y canalizarlo a un pager; ese flujo escala más allá de cualquier herramienta de navegador.
Privacidad y cómo funciona esto
Tus manifiestos nunca salen de tu navegador. El diff, el parseo de JSON, el resaltado y el renderizado corren todos en tu máquina. No subimos el texto, no lo logueamos, ni lo pasamos a ningún servicio de terceros. Esto importa específicamente para código propietario: pegar el package.json de una librería sin lanzar o el lockfile de un repo privado en un servicio cloud puede en sí violar la política de manejo de datos de tu empleador, especialmente cuando el manifiesto nombra paquetes scoped internos, hosts de registry privados, o nombres de productos en desarrollo. Verificar la afirmación es directo. Abre las DevTools del navegador, ve a la pestaña Network, pega ambos manifiestos y observa. No hay peticiones salientes cuando comparas. El mismo modelo de privacidad rige nuestras otras herramientas, incluyendo compare-json, compare-yaml para pnpm-lock.yaml, y git-diff-online para revisión general de código. Para la especificación subyacente, mira la referencia de configuración de Yarn y la documentación de package.json de npm.