Para instalar dependencias de un paquete en un proyecto con espacios de trabajo de npm en macOS, ejecute npm install --workspace="packages/web" desde la raíz del proyecto, sustituyendo packages/web por la ruta del espacio de trabajo o el nombre de su paquete. También puede cambiar a ese directorio del espacio de trabajo y ejecutar npm install. Estos comandos seleccionan un espacio de trabajo en el proyecto de npm; no crean un directorio de instalación independiente ni garantizan que solo cambien los archivos de ese paquete.

Compruebe que el proyecto sea un espacio de trabajo de npm

Un espacio de trabajo (workspace) de npm es un directorio de paquete listado en el package.json de la raíz bajo workspaces. Por ejemplo, un repositorio puede contener un package.json en la raíz y un packages/web/package.json, con "packages/*" en la lista de workspaces de la raíz. npm utiliza esa configuración para reconocer y vincular los paquetes locales. Si la carpeta no está configurada como un espacio de trabajo, --workspace no podrá apuntar a ella como tal. Consulte la documentación de workspaces de npm.

En Terminal, vaya a la raíz del repositorio. En macOS, ponga entre comillas las rutas que contengan espacios para que la shell trate la ruta como un único argumento:

cd "$HOME/Projects/sample monorepo"
npm install --workspace="packages/web"

Aquí, packages/web es un ejemplo de ruta relativa a la raíz del repositorio. En su lugar, puede utilizar el nombre de paquete de un espacio de trabajo configurado, como npm install --workspace="@example/web". npm documenta nombres de espacios de trabajo, rutas de directorios de espacios de trabajo y rutas de espacios de trabajo principales como selectores válidos. Se recomienda utilizar la ruta o el nombre específico del paquete: seleccionar el directorio de un espacio de trabajo superior puede seleccionar todos los espacios de trabajo que contiene. Las opciones de npm install de npm describen el selector.

Instalar las dependencias declaradas del espacio de trabajo seleccionado

El comando anterior ejecuta la instalación en el contexto del espacio de trabajo seleccionado. Si no hay ningún nombre de paquete a continuación de install, npm instala las dependencias que ya están declaradas en los manifiestos del proyecto; no añade una nueva dependencia a packages/web/package.json. La configuración de workspaces de npm excluye por defecto el proyecto raíz cuando se selecciona un espacio de trabajo individual, a menos que include-workspace-root esté habilitado. La referencia de configuración de npm documenta ambas opciones.

Para un paquete que desee añadir, incluya su nombre antes del selector de espacio de trabajo:

npm install date-fns --workspace="packages/web"

Esto le indica a npm que añada date-fns a las dependencias de ese espacio de trabajo y lo instale. Revise el package.json del espacio de trabajo después para confirmar que la dependencia se registró donde se deseaba. La guía de workspaces de npm ofrece el mismo patrón para añadir una dependencia a un espacio de trabajo nombrado.

Usar el directorio del espacio de trabajo en su lugar

Si ya está trabajando en la carpeta del paquete, puede ejecutar npm install allí en lugar de especificar --workspace:

cd "$HOME/Projects/sample monorepo/packages/web"
npm install

npm documenta que ejecutar un comando desde dentro de un espacio de trabajo establece implícitamente el contexto del espacio de trabajo y utiliza la raíz de este como prefijo del proyecto. Esto puede resultar cómodo en una pestaña de la terminal dedicada a un único paquete. Si no está seguro de a qué paquete pertenece el directorio actual, utilice el comando explícito --workspace desde la raíz conocida del repositorio.

Comprender qué implica y qué no implica «un espacio de trabajo»

Seleccionar un espacio de trabajo limita el contexto del espacio de trabajo para el comando; no garantiza un árbol de node_modules físicamente separado. Los espacios de trabajo de npm se gestionan desde un proyecto de nivel superior, y npm puede vincular espacios de trabajo locales dentro del directorio raíz node_modules. Las dependencias pueden ser elevadas (hoisted) o compartidas cuando el árbol de dependencias lo permite. Por lo tanto, la instalación puede afectar al estado de instalación compartido del repositorio y al archivo lockfile. Revise los cambios resultantes en el control de versiones, especialmente si esperaba una modificación únicamente en el sistema de archivos de ese paquete. La documentación de instalación de npm explica el comportamiento de su árbol de dependencias y la vinculación de espacios de trabajo.

Si su objetivo es una instalación completamente autónoma y aislada del monorrepositorio, un selector de espacio de trabajo no es el mecanismo para ello. Un espacio de trabajo forma parte del proyecto raíz configurado; apuntar a él no lo convierte en un repositorio ni en un árbol de instalación independiente.

Si npm no reconoce el destino

Primero verifique que la ruta sea correcta en relación con la raíz del repositorio y que su package.json exista. Luego, inspeccione el package.json raíz y confirme que sus patrones de workspaces incluyan esa carpeta. Si utiliza un nombre, confirme que coincida con el campo name del paquete del espacio de trabajo. Ejecute el comando desde la raíz del repositorio o desplácese directamente al directorio del espacio de trabajo deseado. Evite --workspaces cuando desee un solo paquete: la opción en plural selecciona todos los espacios de trabajo configurados. La regla práctica es sencilla: utilice --workspace="path" desde la raíz cuando desee un destino explícito, y verifique el manifiesto y los cambios en el repositorio una vez que npm termine.

Fuentes