Pour vérifier ce qu'un package de workspace npm partagé livrera réellement, exécutez ses tests depuis le monorepo, empaquetez le workspace, puis installez cette archive tarball dans un répertoire consommateur temporaire et distinct sur votre Mac. Cela permet de détecter les problèmes masqués par le lien symbolique (symlink) de workspace local de npm, tels que des fichiers compilés manquants ou un point d'entrée de package incorrect. Cela ne publie rien sur un registre.

1. Exécuter les propres tests du package depuis la racine du workspace

Ouvrez le Terminal et placez-vous à la racine du monorepo — le répertoire contenant le fichier package.json racine. Vérifiez que le package apparaît dans la configuration workspaces racine et qu'il possède son propre package.json. npm installe les workspaces configurés sous forme de liens dans le répertoire node_modules racine, ce qui permet à une exécution de test à cet endroit de résoudre le code source dynamique du workspace. L'option de workspace vous permet de cibler un package par son nom déclaré ou son répertoire. npm Workspaces

Exécutez le script de test du package en utilisant son nom de workspace, en remplaçant par le nom issu de son package.json :

npm run test --workspace=@acme/math

Si le package utilise un nom de script différent, utilisez ce nom. S'il ne possède aucun script de test, cette commande ne peut pas tester son comportement ; exécutez les vérifications réellement définies par le projet, telles que ses scripts de build ou de lint. Évitez de vous fier uniquement à une commande de test située au niveau de la racine : les commandes npm telles que test s'exécutent sur la racine, à moins que vous ne sélectionniez un workspace. npm Workspaces

2. Examiner et créer l'archive tarball du package

Un test local de workspace ne prouve pas que les fichiers nécessaires aux consommateurs sont inclus dans le package. Prévisualisez d'abord le contenu du package du workspace sélectionné depuis la racine du monorepo :

npm pack --workspace=@acme/math --dry-run

Examinez la liste des fichiers pour vérifier le point d'entrée du package, les fichiers de sortie compilés, les déclarations de types et tout autre fichier promis par le package. Les paramètres de npm relatifs à files, .npmignore et .gitignore ont une incidence sur le contenu ; package.json, ainsi que les fichiers README et de licence, font partie de ceux que npm inclut par défaut. Vérifiez que main ou exports pointe vers des fichiers qui seront présents dans l'archive. npm pack, package.json files and entry points

Lorsque la liste semble correcte, créez une véritable archive tarball dans un répertoire temporaire. Les commandes suivantes utilisent la syntaxe de guillemets compatible avec le shell par défaut de macOS (zsh) et conservent l'artefact en dehors de votre dépôt :

scratch="$(mktemp -d "${TMPDIR:-/tmp}/workspace-package-check.XXXXXX")"
npm pack --workspace=@acme/math --pack-destination="$scratch"

--dry-run indique uniquement ce que npm empaqueterait ; il ne crée pas l'archive. La deuxième commande en crée bien une, mais ne la met pas en ligne. La documentation de npm décrit npm pack comme une commande qui génère une archive tarball et prend en charge le sélecteur de workspace. npm pack

3. Installer l'archive dans un dossier consommateur propre

Trouvez le chemin de l'archive tarball, créez un répertoire consommateur séparé et installez-y l'archive. Cet exemple part du principe qu'une seule archive tarball a été empaquetée dans le répertoire temporaire :

tarball="$(find "$scratch" -maxdepth 1 -name '*.tgz' -print -quit)"
consumer="$scratch/consumer"
mkdir -p "$consumer"
cd "$consumer"
npm init -y
npm install "$tarball"

L'installation d'un fichier .tgz permet de tester l'artefact empaqueté. L'installation d'un dossier de workspace ou l'utilisation de la dépendance liée du monorepo peut se comporter différemment. npm install

Testez à présent le package via son point d'entrée public. Utilisez le nom réel du package et une petite vérification cliente adaptée à son API — par exemple, effectuez un require ou un import de celui-ci, puis appelez une fonction exportée représentative. Exécutez cette vérification depuis le répertoire consommateur, où le package est résolu à partir du répertoire node_modules nouvellement installé. Si le projet publie des fichiers compilés, vérifiez que le build a été exécuté avant l'empaquetage ; sinon, des fichiers pourraient manquer dans l'archive même si les tests de la phase de développement ont réussi.

4. Diagnostiquer les échecs avant la publication

Si l'installation échoue, vérifiez que l'archive contient un package.json avec un name et une version, puis inspectez sa liste de fichiers et confirmez que les points d'entrée configurés existent bien dans le tarball. Si l'importation échoue, comparez le format de module du consommateur avec les paramètres type, main et exports du package. Un package peut réussir les tests du workspace et échouer ici, car ces tests peuvent charger les fichiers sources directement ou résoudre des dépendances non déclarées depuis le monorepo.

Si une dépendance est un autre workspace non publié, testez également la configuration de publication prévue. Un consommateur qui installe une archive tarball ne recevra pas automatiquement le code source du workspace frère via le lien du monorepo. Assurez-vous que les packages frères sont publiés/disponibles dans des versions compatibles, ou utilisez une configuration délibérément intégrée (bundled) ou installable. Cette procédure vérifie un package empaqueté localement dans l'environnement Mac/Node actuel ; elle ne permet pas de garantir le comportement sur toutes les versions de Node, tous les systèmes d'exploitation ou toutes les configurations de registre.

L'objectif final est d'obtenir un test de workspace réussi, une liste de fichiers de package plausible et une vérification consommatrice qui installe et utilise l'archive tarball depuis l'extérieur du monorepo. Conservez le répertoire temporaire si vous avez besoin de l'inspecter, ou supprimez-le avec rm -rf "$scratch" après avoir confirmé que la variable fait toujours référence au chemin temporaire généré.

Sources