Dépendances des plugins

Une dépendance de plugin est un autre plugin sur lequel votre plugin s’appuie, par exemple celui dont il appelle le serveur MCP ou la compétence. Chaque dépendance suit la dernière version que sa place de marché fournit, sauf si vous déclarez une contrainte de version, une plage de version sémantique telle que ^2.0 ou ~2.1.0 que vous avez testée. Cette page s’adresse aux auteurs de plugins qui déclarent des dépendances dans plugin.json et aux responsables de la place de marché qui balisent les versions.

Ces cas sont couverts sur d’autres pages :

Installation d’un plugin qui a des dépendances : voir Gérer les plugins installés
Lecture d’une erreur de dépendance : voir Erreurs de dépendance
Déclaration des packages npm et Bun dont le code de votre plugin a besoin : voir Dépendances des packages Node.js

Pour ajouter une contrainte, commencez par Déclarer une dépendance avec une contrainte de version. Si vous maintenez un plugin dont d’autres dépendent, balisez vos versions pour que leurs contraintes puissent se résoudre.

Déclarer les dépendances

Sans contrainte de version, une dépendance se déplace vers chaque nouvelle version que sa place de marché publie la prochaine fois que les utilisateurs mettent à jour. Si cette version renomme un outil MCP que votre plugin appelle, votre plugin se casse pour tous ceux qui mettent à jour. Avec une contrainte telle que ~2.1.0 sur une dépendance provenant d’une source sauvegardée par git, les utilisateurs qui ont votre plugin installé continuent à recevoir les correctifs 2.1.x de la dépendance et ne passent jamais à 2.2. Pour mettre à niveau selon votre propre calendrier, testez contre une version plus récente, puis publiez une nouvelle version de votre plugin avec une contrainte plus large.

Déclarer une dépendance avec une contrainte de version

Listez les dépendances dans le tableau dependencies du fichier .claude-plugin/plugin.json de votre plugin. Le manifeste suivant déclare une dépendance sans version et une dépendance avec contrainte :

.claude-plugin/plugin.json

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Une entrée peut être une chaîne : le nom du plugin seul, tel que "audit-logger" dans ce manifeste, ou "name@marketplace" pour le résoudre dans une autre place de marché. Avec une simple chaîne, votre plugin dépend de la version que la place de marché de ce plugin fournit. Pour définir une contrainte de version, utilisez un objet avec ces champs, chacun étant une chaîne :

Champ	Description
`name`	Le nom du plugin de dépendance, tel qu’il apparaît dans son entrée de place de marché. Claude Code le recherche dans la même place de marché que le plugin déclarant, sauf si vous définissez `marketplace`. Obligatoire.
`version`	Une plage de version sémantique telle que `~2.1.0`, `^2.0`, `>=1.4`, ou `=2.1.0`. La dépendance s’installe à la balise git la plus élevée qui satisfait cette plage, donc le responsable de la dépendance doit baliser les versions.
`marketplace`	Une place de marché différente pour résoudre `name` dedans. Une liste d’autorisation contrôle les dépendances inter-places de marché, décrites dans Dépendre d’un plugin d’une autre place de marché.

Une plage ne correspond pas aux versions de pré-version telles que 2.0.0-beta.1 sauf si vous acceptez avec un suffixe de pré-version tel que ^2.0.0-0.

Regrouper les plugins pour une équipe

Pour permettre aux ingénieurs d’installer un ensemble curé de plugins avec une seule commande, publiez un plugin dont le manifeste contient un name et un tableau dependencies. Un manifeste de plugin n’a besoin que de name, c’est donc un plugin valide, et l’installer installe chaque dépendance. Par exemple, une équipe de plateforme peut publier des bundles spécifiques aux rôles dans une place de marché interne afin que les ingénieurs exécutent une seule claude plugin install au lieu d’installer chaque plugin séparément :

.claude-plugin/plugin.json

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

Pour ajouter un plugin à l’ensemble standard ultérieurement, publiez une nouvelle version backend-standard avec la dépendance supplémentaire. Lorsque la place de marché ne met pas à jour automatiquement par défaut, les ingénieurs activent soit la mise à jour automatique pour la place de marché, soit mettent à jour manuellement :

Activer la mise à jour automatique pour la place de marché : la prochaine mise à jour automatique déplace le bundle vers la nouvelle version et installe toutes les dépendances qu’il ajoute.
Mettre à jour manuellement : exécutez claude plugin update backend-standard dans un shell, puis /reload-plugins dans une session ouverte pour installer les dépendances nouvellement ajoutées.

Pour les étapes côté ingénieur, voir Garder les plugins à jour. Pour déployer un bundle à tous les membres d’une organisation, un administrateur l’ajoute à enabledPlugins dans les paramètres gérés. Voir Pré-installer et exiger des plugins.

Dépendre d’un plugin d’une autre place de marché

Par défaut, Claude Code n’installe pas une dépendance d’une place de marché différente de celle du plugin déclarant, sauf si l’utilisateur a déjà cette dépendance installée et activée au même niveau. Cette valeur par défaut empêche une place de marché d’installer silencieusement des plugins d’une source que l’utilisateur n’a pas examinée. Pour autoriser l’installation, ajoutez le nom de la place de marché cible à allowCrossMarketplaceDependenciesOn dans le marketplace.json de la place de marché racine. La place de marché racine est celle qui héberge le plugin que l’utilisateur installe. Seule la liste d’autorisation de la place de marché racine s’applique. Le marketplace.json suivant permet à deploy-kit de dépendre d’un plugin de your-shared-marketplace :

.claude-plugin/marketplace.json

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "allowCrossMarketplaceDependenciesOn": ["your-shared-marketplace"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "your-shared-marketplace" }
      ]
    }
  ]
}

Si allowCrossMarketplaceDependenciesOn est manquant ou n’inclut pas la place de marché cible, Claude Code n’installe pas la dépendance. Lorsque la dépendance est déclarée dans l’entrée de la place de marché, l’installation elle-même est refusée avec un message qui commence par

Dependency "audit-logger@your-shared-marketplace" (required by deploy-kit@your-marketplace) is in marketplace "your-shared-marketplace", which is not in the allowlist

et nomme le champ à définir. Lorsqu’elle est déclarée dans plugin.json, l’installation se termine sans la dépendance et votre plugin échoue alors à charger. La vérification de la liste d’autorisation ne s’applique pas à une dépendance qui est déjà activée. Si un utilisateur installe d’abord audit-logger de your-shared-marketplace lui-même, au même niveau, deploy-kit s’installe alors sans aucune modification de la liste d’autorisation.

Tester un plugin et sa dépendance localement

Si vous développez un plugin et le plugin dont il dépend en même temps, démarrez Claude Code à partir de votre shell et chargez les deux avec --plugin-dir :

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

La copie locale de la dépendance satisfait l’entrée de dépendance de votre plugin, vous n’avez donc pas besoin d’installer la dépendance à partir de sa place de marché.

Pas de version nécessaire : le plugin.json local n’a pas besoin non plus d’une version, car une contrainte de version n’est pas vérifiée par rapport à une copie locale.
Entrées qui nomment une place de marché : une entrée qui nomme une place de marché correspond également à la copie locale sur Claude Code v2.1.242 ou ultérieur.

Jusqu’à ce que vous installiez la dépendance à partir de sa place de marché, votre plugin cesse de charger chaque fois que la copie locale est désactivée ou absente :

Vous avez désactivé la copie locale : votre plugin est désactivé au prochain chargement de plugin, avec une erreur qui se termine par is disabled — enable it or remove the dependency. Lorsque l’erreur nomme la dépendance comme <name>@inline, cet identifiant fait référence à la copie --plugin-dir.
Vous avez démarré une session sans le drapeau --plugin-dir de la dépendance : l’erreur signale que la dépendance n’est pas installée. Passez le drapeau à nouveau, ou installez la dépendance à partir de sa place de marché.

Lorsque les deux plugins se trouvent dans un dossier parent, vous pouvez passer ce dossier à --plugin-dir une seule fois. Si le dossier n’est pas lui-même un plugin, Claude Code charge chaque dossier enfant qui a un .claude-plugin/plugin.json. Nécessite Claude Code v2.1.265 ou ultérieur.

Publier un plugin dont d’autres dépendent

Si vous maintenez un plugin dont d’autres plugins dépendent avec une contrainte de version, balisez ses versions pour que ces contraintes puissent se résoudre. Une contrainte se résout par rapport aux balises git du référentiel qui héberge le plugin. Balisez le référentiel vers lequel la source du plugin du plugin dans marketplace.json pointe :

Source github, url, ou git-subdir : le référentiel du plugin lui-même, donc l’auteur du plugin crée les balises
Chemin relatif tel que ./plugins/secrets-vault : le référentiel de la place de marché, donc le responsable de la place de marché crée les balises

Créer une balise de version

Balisez chaque version comme <plugin-name>--v<version>, où <version> correspond au champ version dans le plugin.json de ce commit. Le préfixe plugin-name permet à un référentiel de place de marché d’héberger plusieurs plugins avec des historiques de version indépendants. Créez la balise à partir du répertoire du plugin, avec une télécommande origin configurée pour recevoir la balise poussée, en utilisant claude plugin tag :

claude plugin tag --push

La commande construit le nom de la balise à partir du manifeste du plugin. Avant de créer la balise, elle exécute ces vérifications :

Valide le plugin
Vérifie que plugin.json et l’entrée de la place de marché s’accordent sur la version, lorsque le répertoire du plugin se trouve dans un checkout de place de marché
Nécessite un arbre de travail propre sous le répertoire du plugin
Refuse si la balise existe déjà

Une exécution réussie imprime Created tag secrets-vault--v2.1.0. Avec --push, elle imprime également Pushed to origin. Sans --push, elle imprime la commande git push à exécuter vous-même. Passez --dry-run pour voir le plan sans rien créer. La référence claude plugin tag liste les drapeaux restants. Vous pouvez également exécuter git tag secrets-vault--v2.1.0 directement, tant que vous gardez la version dans plugin.json et dans l’entrée de la place de marché synchronisées vous-même.

Contraindre une dépendance qui a une source non-git

La résolution basée sur les balises s’applique uniquement aux sources sauvegardées par git. Pour une dépendance avec une source de plugin npm, archive, ou command plugin source, la contrainte ne contrôle pas quelle version est récupérée. Elle est toujours vérifiée lorsque le plugin charge, et le plugin dépendant est désactivé si la version installée ne la satisfait pas. Pour les sources npm, archive, et command, la version vérifiée est la version dans le plugin.json de la dépendance. Définissez-en une là avant de contraindre cette dépendance, car un plugin.json qui ne définit pas de version ne satisfait aucune contrainte. Claude Code n’installe jamais une dépendance avec une source command lui-même, donc les utilisateurs l’installent d’abord. Il n’exécute jamais non plus le headersHelper d’une dépendance, donc les utilisateurs installent également une dépendance dont l’entrée de la place de marché en définit une avant d’installer votre plugin. En plus de claude plugin install, ces opérations installent également toute dépendance déclarée manquante, et les limites command et headersHelper s’appliquent à elles aussi :

/reload-plugins
Mise à jour automatique de la place de marché du plugin dépendant
Réexécution de claude plugin install sur le plugin dépendant
claude plugin marketplace add

Comment les dépendances se comportent pour vos utilisateurs

Ces sections décrivent comment Claude Code résout, vérifie et combine les contraintes que vous déclarez une fois que votre plugin est installé aux côtés d’autres.

Comment une contrainte se résout par rapport aux balises

Lorsqu’un utilisateur installe un plugin qui déclare { "name": "secrets-vault", "version": "~2.1.0" }, la dépendance s’installe à partir de la balise secrets-vault--v la plus élevée qui satisfait ~2.1.0 sur le référentiel qui héberge secrets-vault. Lorsqu’aucune balise ne satisfait la plage, l’installation échoue ou utilise la copie actuelle de la place de marché :

Plugin avec son propre référentiel : l’installation échoue avec un message contenant Dependency "secrets-vault@your-marketplace" has no git tag satisfying.
Plugin référencé par un chemin relatif : l’installation utilise la copie actuelle de la place de marché à la place, et la contrainte est vérifiée lorsque le plugin charge. Si cette copie est en dehors de la plage, le plugin dépendant reste désactivé et claude plugin list affiche Requires "secrets-vault@your-marketplace" ~2.1.0, installed 3.0.0.

Pour un plugin que la place de marché référence par un chemin relatif, une place de marché que vous avez ajoutée comme chemin de dossier local résout également les contraintes par rapport aux balises git de ce dossier, lorsque le dossier est un référentiel git. Cela nécessite Claude Code v2.1.196 ou ultérieur. Un dossier local qui n’est pas un référentiel git n’a pas de balises, donc Claude Code installe la dépendance à partir du contenu actuel du dossier à la place.

Confirmer la version résolue

Pour confirmer quelle version une contrainte s’est résolue, exécutez claude plugin list dans votre shell. Une dépendance résolue par balise affiche sa version avec un suffixe de commit de 12 caractères, tel que 2.1.0-8713c5b11005. Les vérifications de contrainte utilisent la version de la balise plutôt que la version dans plugin.json, même si plugin.json à ce commit est en retard. Si vous forcez le déplacement d’une balise vers un commit différent, la prochaine installation récupère le contenu de ce commit au lieu de réutiliser une copie en cache obsolète. Voir Versions et mises à jour pour savoir comment la version d’un plugin devient sa clé de cache.

Combiner les contraintes de plusieurs plugins

Lorsque plusieurs plugins installés contraignent la même dépendance, la dépendance se résout à la version la plus élevée qui satisfait toutes leurs plages. Les combinaisons courantes se résolvent comme ceci :

Plugin A nécessite	Plugin B nécessite	Résultat
`^2.0`	`>=2.1`	Une installation à la balise `2.x` la plus élevée à ou au-dessus de `2.1.0`. Les deux plugins se chargent.
`~2.1`	`~3.0`	L’installation du plugin B échoue avec un message `has conflicting version requirements`. Le plugin A et la dépendance restent comme ils étaient.
`=2.1.0`	aucun	La dépendance reste à `2.1.0`. La mise à jour automatique ignore les versions plus récentes tant que le plugin A est installé.

La mise à jour automatique récupère une dépendance contrainte à la balise git la plus élevée qui satisfait la plage de chaque plugin installé, plutôt qu’à la dernière version de la place de marché. Si les plages des plugins installés ne se chevauchent pas, la mise à jour automatique laisse cette dépendance à sa version actuelle, et l’onglet Erreurs de /plugin affiche une entrée nommant le plugin contraignant. S’ils se chevauchent mais qu’aucune balise ne tombe dans la plage, la mise à jour automatique récupère la copie actuelle de la place de marché et ignore la mise à jour lorsque la version de cette copie tombe en dehors de la plage de tout plugin installé. Lorsqu’un utilisateur désinstalle le dernier plugin qui contraint une dépendance, la dépendance n’est plus contrainte à une plage de version et reprend le suivi de son entrée de place de marché à la prochaine mise à jour.

Voir aussi

claude plugin prune : supprimer les dépendances auto-installées dont aucun plugin n’a plus besoin
Héberger une place de marché : canaux de version et recommandation d’autres plugins

Plugins

Utiliser les plugins

Créer des plugins

Exécuter une marketplace

Gérer les plugins de votre organisation

Dépannage

Référence

Déclarer les dépendances

Déclarer une dépendance avec une contrainte de version

Regrouper les plugins pour une équipe

Dépendre d’un plugin d’une autre place de marché

Tester un plugin et sa dépendance localement

Publier un plugin dont d’autres dépendent

Créer une balise de version

Contraindre une dépendance qui a une source non-git

Comment les dépendances se comportent pour vos utilisateurs

Comment une contrainte se résout par rapport aux balises

Confirmer la version résolue

Combiner les contraintes de plusieurs plugins

Voir aussi

​Déclarer les dépendances

​Déclarer une dépendance avec une contrainte de version

​Regrouper les plugins pour une équipe

​Dépendre d’un plugin d’une autre place de marché

​Tester un plugin et sa dépendance localement

​Publier un plugin dont d’autres dépendent

​Créer une balise de version

​Contraindre une dépendance qui a une source non-git

​Comment les dépendances se comportent pour vos utilisateurs

​Comment une contrainte se résout par rapport aux balises

​Confirmer la version résolue

​Combiner les contraintes de plusieurs plugins

​Voir aussi

Déclarer les dépendances

Déclarer une dépendance avec une contrainte de version

Regrouper les plugins pour une équipe

Dépendre d’un plugin d’une autre place de marché

Tester un plugin et sa dépendance localement

Publier un plugin dont d’autres dépendent

Créer une balise de version

Contraindre une dépendance qui a une source non-git

Comment les dépendances se comportent pour vos utilisateurs

Comment une contrainte se résout par rapport aux balises

Confirmer la version résolue

Combiner les contraintes de plusieurs plugins

Voir aussi