Gestion des plugins

AppKit inclut une CLI pour gérer les plugins. Toutes les commandes sont accessibles via npx @databricks/appkit plugin.

Convention de manifeste : manifest.json est le format par défaut et recommandé pour les commandes CLI (sync, list, validate). Par sécurité (approche « zero trust »), les manifestes JS (manifest.js/manifest.cjs) sont ignorés, sauf si vous passez l'option --allow-js-manifest, qui exécute le code du plugin et ne doit être utilisée qu'avec des sources de confiance. La commande add-resource se contente de modifier manifest.json directement sur place.

Créer un plugin

Générez l'ossature d'un nouveau plugin de manière interactive ou à l'aide d'options :

# Mode interactif (demande toutes les options)
npx @databricks/appkit plugin create

# Mode non interactif (toutes les options requises sont fournies)
npx @databricks/appkit plugin create \
  --placement in-repo \
  --path plugins/my-plugin \
  --name my-plugin \
  --description "My custom plugin" \
  --resources sql_warehouse \
  --force

En mode interactif, l'assistant vous guide pour définir :

Emplacement : dans votre dépôt (par ex. plugins/my-plugin) ou en tant que paquet autonome
Métadonnées : nom, nom d'affichage, description
Ressources : les ressources Databricks dont le plugin a besoin (SQL Warehouse, Secret, etc.) et le caractère obligatoire ou facultatif de chacune

En mode non interactif, --placement, --path, --name et --description sont obligatoires. Les ressources peuvent être indiquées sous forme de liste séparée par des virgules (--resources sql_warehouse,volume) ou en JSON pour un contrôle complet (--resources-json '[{"type":"sql_warehouse","permission":"CAN_MANAGE"}]'). Pour connaître toutes les options disponibles, exécutez npx @databricks/appkit plugin create --help.

La commande génère l'ossature complète d'un plugin, avec un manifest.json et une classe TypeScript de plugin qui importe directement le manifeste — prête à être enregistrée dans votre application.

Synchroniser les manifestes de plugins

Analysez votre projet à la recherche de plugins et générez appkit.plugins.json :

npx @databricks/appkit plugin sync --write

Cette commande détecte les manifestes de plugins dans les paquets installés et les imports locaux, puis écrit un manifeste consolidé utilisé par l'outillage de déploiement. Les plugins référencés dans votre appel createApp({ plugins: [...] }) sont automatiquement marqués comme requis.

Les paquets Databricks installés et approuvés (par exemple @databricks/appkit) sont autorisés à charger les manifestes JS fournis avec le paquet pendant plugin sync. Pour les autres sources, si vous vous appuyez intentionnellement sur des manifestes JS, activez explicitement cette option :

npx @databricks/appkit plugin sync --write --allow-js-manifest

Utilisez l'option --silent dans les hooks de build pour supprimer la sortie :

{
  "scripts": {
    "sync": "appkit plugin sync --write --silent",
    "predev": "npm run sync",
    "prebuild": "npm run sync"
  }
}

Valider les manifestes

Vérifiez les manifestes de plugins par rapport au schéma JSON :

# Valider manifest.json dans le répertoire courant
npx @databricks/appkit plugin validate

# Valider des fichiers ou répertoires spécifiques
npx @databricks/appkit plugin validate plugins/my-plugin appkit.plugins.json

Le validateur détecte automatiquement si un fichier est un manifeste de plugin ou un manifeste de modèle (à partir de $schema) et signale les erreurs en indiquant des chemins lisibles et les valeurs attendues.

Pour inclure les manifestes JS dans la validation, utilisez --allow-js-manifest.

Lister les plugins

Affichez les plugins enregistrés dans appkit.plugins.json ou analysez un répertoire :

# Depuis appkit.plugins.json (par défaut)
npx @databricks/appkit plugin list

# Analyser un répertoire pour y trouver des dossiers de plugins
npx @databricks/appkit plugin list --dir plugins/

# Analyser un répertoire et inclure les manifestes JS (code de confiance uniquement)
npx @databricks/appkit plugin list --dir plugins/ --allow-js-manifest

# Sortie JSON pour les scripts
npx @databricks/appkit plugin list --json

Ajouter une ressource à un plugin

Ajoutez une nouvelle exigence de ressource au manifeste d'un plugin existant. Nécessite un fichier manifest.json dans le répertoire du plugin (la commande le modifie directement ; elle ne touche pas à manifest.js) :

# Mode interactif
npx @databricks/appkit plugin add-resource
npx @databricks/appkit plugin add-resource --path plugins/my-plugin

# Mode non interactif (--type active le mode par options)
npx @databricks/appkit plugin add-resource --path plugins/my-plugin --type sql_warehouse
npx @databricks/appkit plugin add-resource --path plugins/my-plugin --type volume --no-required --dry-run

En mode non interactif, seul --type est requis — tous les autres champs (permission, clé de ressource, variables d'environnement des champs) prennent par défaut des valeurs pertinentes issues du schéma. Utilisez --dry-run pour prévisualiser le manifeste mis à jour sans l'écrire. Pour connaître toutes les options disponibles, exécutez npx @databricks/appkit plugin add-resource --help.