Pour installer les dépendances d'un seul package dans un projet avec workspaces npm sur macOS, exécutez npm install --workspace="packages/web" depuis la racine du projet, en remplaçant packages/web par le chemin du workspace ou le nom de son package. Vous pouvez également vous déplacer dans le répertoire de ce workspace et exécuter npm install. Ces commandes sélectionnent un workspace au sein du projet npm ; elles ne créent pas de répertoire d'installation distinct et ne garantissent pas que seuls les fichiers de ce package seront modifiés.

Vérifier que le projet est un workspace npm

Un workspace npm est un répertoire de package listé dans le package.json racine sous workspaces. Par exemple, un dépôt peut contenir un package.json racine et un packages/web/package.json, avec "packages/*" figurant dans la liste des workspaces de la racine. npm utilise cette configuration pour reconnaître et lier les packages locaux. Si le dossier n'est pas configuré comme un workspace, --workspace ne pourra pas le cibler en tant que tel. Consultez la documentation des workspaces de npm.

Dans le Terminal, rendez-vous à la racine du dépôt. Sur macOS, mettez entre guillemets les chemins contenant des espaces afin que le shell traite le chemin comme un seul argument :

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

Ici, packages/web est un exemple de chemin relatif par rapport à la racine du dépôt. Vous pouvez utiliser à la place le nom de package d'un workspace configuré, comme npm install --workspace="@example/web". npm indique dans sa documentation que les noms de workspace, les chemins de répertoires de workspace et les chemins de workspace parents sont des sélecteurs valides. Privilégiez le chemin ou le nom spécifique du package : la sélection d'un répertoire de workspace parent peut sélectionner tous les workspaces situés en dessous de lui. Les options de npm install de npm décrivent ce sélecteur.

Installer les dépendances déclarées du workspace sélectionné

La commande ci-dessus exécute l'installation dans le contexte du workspace sélectionné. Sans nom de package suivant install, npm installe les dépendances déjà déclarées dans les manifestes du projet ; il n'ajoute pas de nouvelle dépendance à packages/web/package.json. La configuration des workspaces de npm exclut par défaut le projet racine lorsqu'un workspace individuel est sélectionné, sauf si include-workspace-root est activé. La référence de configuration de npm détaille ces deux options.

Pour un package que vous souhaitez ajouter, incluez son nom avant le sélecteur de workspace :

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

Cela demande à npm d'ajouter date-fns aux dépendances de ce workspace et de l'installer. Vérifiez ensuite le package.json du workspace pour confirmer que la dépendance a bien été enregistrée à l'endroit prévu. Le guide des workspaces de npm indique ce même modèle pour ajouter une dépendance à un workspace désigné par son nom.

Utiliser directement le répertoire du workspace

Si vous travaillez déjà dans le dossier du package, vous pouvez y exécuter npm install directement plutôt que de spécifier --workspace :

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

npm indique dans sa documentation que l'exécution d'une commande depuis l'intérieur d'un workspace définit implicitement le contexte du workspace et utilise la racine du workspace comme préfixe du projet. Cela peut être pratique dans un onglet de terminal dédié à un seul package. Si vous n'êtes pas certain du package auquel appartient le répertoire actuel, utilisez la commande explicite --workspace depuis la racine connue du dépôt.

Comprendre ce que « un seul workspace » signifie et ne signifie pas

Sélectionner un seul workspace restreint le contexte de travail de la commande ; cela ne garantit pas une arborescence node_modules physiquement séparée. Les workspaces npm sont gérés depuis un projet de premier niveau, et npm peut lier les workspaces locaux dans le répertoire node_modules racine. Les dépendances peuvent être remontées (hoisted) ou partagées lorsque l'arbre des dépendances le permet. L'installation peut donc affecter l'état d'installation partagé et le fichier lockfile du dépôt. Vérifiez les modifications résultantes dans votre outil de contrôle de version, en particulier si vous vous attendiez à ce que seuls les fichiers du package soient modifiés. La documentation d'installation de npm explique le comportement de son arbre de dépendances et la liaison des workspaces.

Si votre objectif est une installation totalement autonome et isolée du monorepo, le sélecteur de workspace n'est pas le mécanisme adéquat. Un workspace fait partie du projet racine configuré ; le cibler ne le transforme pas en dépôt indépendant ou en arborescence d'installation distincte.

Si npm ne reconnaît pas la cible

Vérifiez d'abord que le chemin est correct par rapport à la racine du dépôt et que son package.json existe. Inspectez ensuite le package.json racine et confirmez que ses motifs workspaces incluent bien ce dossier. Si vous utilisez un nom, vérifiez qu'il correspond au champ name du package de ce workspace. Exécutez la commande depuis la racine du dépôt, ou déplacez-vous directement dans le répertoire du workspace visé. Évitez --workspaces lorsque vous ne visez qu'un seul package : l'option au pluriel sélectionne tous les workspaces configurés. La règle pratique est simple : utilisez --workspace="path" depuis la racine lorsque vous souhaitez une cible explicite, et examinez les modifications du manifeste et du dépôt une fois que npm a terminé.

Sources