Para alinear una dependencia entre paquetes npm en una Mac, primero compare los rangos de versiones en el package.json de cada espacio de trabajo, decida qué rango de versión común se adapta a cada paquete, luego actualice cada espacio de trabajo afectado y regenere el lockfile raíz. Los espacios de trabajo de npm pueden apuntar a paquetes desde la raíz del repositorio, pero no proporcionan un comando integrado que analice cada manifiesto y haga idénticas las versiones de las dependencias automáticamente.

1. Verifique que el repositorio use espacios de trabajo de npm

En Terminal, diríjase a la raíz del repositorio e inspeccione su configuración:

cd "/path/to/your/repository"
npm --version
npm pkg get workspaces

El package.json raíz debe definir las rutas de los espacios de trabajo, y cada paquete debe tener su propio package.json. La función de espacios de trabajo (workspaces) de npm vincula esos paquetes locales durante la instalación y permite que los comandos apunten a uno o más espacios de trabajo por nombre o ruta. Si npm pkg get workspaces no devuelve nada, confirme el gestor de paquetes y el diseño del repositorio antes de usar comandos de espacios de trabajo de npm. npm Workspaces

2. Compare las declaraciones de dependencias

Busque en los manifiestos bajo seguimiento la dependencia que desea alinear. Por ejemplo, en Terminal de macOS puede usar grep sin instalar ninguna herramienta adicional:

grep -n '"typescript"' package.json packages/*/package.json

Reemplace typescript con el nombre de la dependencia. Esta es una comprobación rápida de texto, por lo que debe revisar las secciones coincidentes en cada manifiesto para ver si el paquete se encuentra bajo dependencies, devDependencies, peerDependencies u optionalDependencies. Esos campos describen diferentes funciones; no mueva una dependencia entre ellos solo para hacer coincidir las cadenas de versión. Para un inventario más completo, inspeccione el manifiesto de cada espacio de trabajo en su editor o use el comando de listado con reconocimiento de espacios de trabajo de npm:

npm ls typescript --workspaces --depth=0

Los rangos de los manifiestos y el árbol instalado responden a preguntas diferentes: el primero muestra lo que permite cada paquete, mientras que npm ls informa el estado de las dependencias instaladas. El lockfile de npm registra las versiones resueltas, pero no reemplaza los rangos aceptables declarados en cada package.json. npm ls package-lock.json and npm install

3. Elija una política de versiones compatible

Elija una versión que satisfaga los requisitos de los consumidores y la política de soporte del repositorio. Un rango de versiones compartido significa que los paquetes expresan el mismo conjunto permitido; no garantiza que todas las copias anidadas o transitivas se resuelvan en una única copia instalada. Verifique los requisitos de dependencias de pares (peer dependencies) y las notas de la versión en busca de cambios que rompan la compatibilidad antes de mover paquetes a través de una versión principal (major). Si los consumidores necesitan un rango de compatibilidad más amplio, alinearse a la misma cadena exacta puede ser inapropiado; en su lugar, acuerde una política de rango equivalente.

Por ejemplo, para fijar una herramienta de desarrollo en la misma versión exacta en dos espacios de trabajo llamados web y api, ejecute esto desde la raíz:

npm install --save-dev --save-exact typescript@5.8.3 --workspace=web --workspace=api

Utilice la versión que su proyecto haya seleccionado; 5.8.3 aquí es solo un ejemplo. El comando de instalación de npm acepta selectores de espacio de trabajo y guarda el paquete en el manifiesto de cada paquete seleccionado. --save-exact escribe una versión exacta en lugar del operador de rango habitual de npm. Para una dependencia de tiempo de ejecución, use la categoría de guardado adecuada, como --save-prod, en lugar de --save-dev. npm install

Repita con selectores de espacio de trabajo adicionales o ejecute el comando para cada espacio de trabajo. No asuma que una instalación a nivel de raíz actualiza el manifiesto de cada paquete: apunte explícitamente a los paquetes cuyas declaraciones deben cambiar. El paquete raíz también se puede incluir deliberadamente con --include-workspace-root cuando deba declarar la misma dependencia.

4. Reinstale, inspeccione el diff y verifique

Después de actualizar las declaraciones, ejecute la instalación en la raíz del repositorio para que npm concilie el árbol de espacios de trabajo y el lockfile:

npm install
npm ls typescript --workspaces --depth=0
git diff -- package.json package-lock.json packages/*/package.json

Verifique que cada manifiesto previsto tenga la declaración acordada y que el cambio en el lockfile sea el esperado. Ejecute los scripts de compilación o prueba pertinentes del repositorio; npm ls por sí solo no garantiza que el código funcione con la versión seleccionada. Confirme en git (commit) el package-lock.json raíz cuando el proyecto le haga seguimiento, para que las instalaciones del equipo puedan reproducir el árbol resuelto. npm package-lock documentation

Si npm informa una dependencia no válida o un conflicto de pares (peer conflict), inspeccione el paquete nombrado en el error en lugar de forzar la instalación. Un espacio de trabajo puede requerir un rango compatible diferente, o bien otra dependencia puede imponer un requisito de pares que necesite un plan de actualización deliberado.

Cuándo ayuda npm dedupe

npm dedupe puede simplificar el árbol de dependencias instaladas moviendo las dependencias compatibles a un nivel superior para que los paquetes puedan compartirlas. No reescribe los rangos de dependencias directas en package.json, por lo que no puede alinear declaraciones por sí solo. Utilícelo solo después de comprobar que los rangos son compatibles y, a continuación, revise el diff del lockfile resultante. npm dedupe

El cierre confiable es una política deliberada expresada en el manifiesto de cada espacio de trabajo relevante, un lockfile regenerado y la verificación de los paquetes afectados. Eso brinda a los mantenedores un registro claro de lo que se alineó y deja visibles las restricciones incompatibles para una decisión por separado.

Fuentes