Assistance complète pour le développement Vendure, générée à partir de la documentation officielle (docs.vendure.io).
Déclencher ce skill pour :
- Construction d'applications e-commerce headless avec Node.js/TypeScript
- Travail avec les APIs GraphQL pour produits, commandes ou gestion clients
- Implémentation d'intégrations de paiement (Stripe, handlers personnalisés)
- Création de plugins personnalisés ou extension des fonctionnalités Vendure
- Configuration de workflows de commande et machines à états
- Développement d'extensions Dashboard avec React
- Configuration de boutiques multi-devises ou multi-canaux
- Débogage de code Vendure ou résolution de problèmes e-commerce
- Apprentissage des bonnes pratiques Vendure pour le développement TypeScript
Concepts fondamentaux de l'architecture Vendure :
- Order State Machine - Workflow personnalisable (AddingItems → Delivered) via OrderProcess avec interceptors
- Custom Fields - Ajouter des propriétés aux entités via VendureConfig, extension automatique du schema GraphQL, support des relations et 10+ types de champs
- Plugins - Extensibilité via décorateur @VendurePlugin, hooks de cycle de vie, pattern InjectableStrategy pour comportement pluggable
Ce skill est organisé en 3 sections principales pour une navigation optimale :
| Fichier | Lignes | Contenu | Quand consulter |
|---|
getting-started.md
| 619 | Installation, création projet, premiers pas | Démarrer un projet |
developer-guide.md
| 5,247 | Architecture, API Layer, Middleware, NestJS | Comprendre l'architecture |
core-concepts.md
| 1,502 | Collections, Money, Assets, Taxes, Payment | Concepts fondamentaux |
extending-the-dashboard.md
| 2,362 | Extensions React, routes, pages personnalisées | Personnaliser l'admin |
how-to.md
| 2,880 | Custom fields, paiements, shipping calculators | Tutoriels spécifiques |
storefront.md
| 1,618 | Next.js, Remix, connexion API, starters | Créer un storefront |
deployment.md
| 1,145 | Docker, production, sécurité, HardenPlugin | Déployer en production |
user-guide.md
| 473 | Utilisation Dashboard pour administrateurs | Former les utilisateurs |
migrating-from-v1.md
| 302 | Breaking changes, guide de migration v1→v2 | Migration de version |
Commandes grep utiles :
grep -n "OrderProcess" references/Guides/developer-guide.md
grep -n "Custom Fields" references/Guides/how-to.md
grep -n "Collections" references/Guides/core-concepts.md
| Fichier | Lignes | Contenu | Quand consulter |
|---|
typescript-api.md
| 21,561 | TOUT : Classes, interfaces, strategies, services | Recherche API TypeScript |
admin-ui-api.md
| 5,712 | API Angular (deprecated), composants legacy | Maintenir code Angular |
core-plugins.md
| 4,527 | EmailPlugin, AssetServerPlugin, HardenPlugin, etc. | Configurer plugins officiels |
dashboard.md
| 3,585 | React hooks, composants Dashboard, extensions | Développer extensions React |
graphql-api.md
| 4,078 | Shop API, Admin API, queries, mutations | Requêtes GraphQL |
reference.md
| 35 | Index/overview de la section | Vue d'ensemble |
Fichier clé : typescript-api.md
- Contient TOUTES les interfaces et classes Vendure.
Commandes grep utiles :
grep -n "^# " references/reference/typescript-api.md | head -50 # Liste des sections
grep -n "PaymentMethodHandler" references/reference/typescript-api.md
grep -n "OrderService" references/reference/typescript-api.md
grep -n "useDetailPage" references/reference/dashboard.md
NOUVELLE SECTION - Composants UI pour extensions Dashboard
| Fichier | Lignes | Composants | Quand consulter |
|---|
ui.md
| 1,315 | 42 composants : Button, Dialog, Card, Badge, Popover, Tabs... | Éléments UI de base |
form-inputs.md
| 1,082 | 11 composants : TextInput, SelectInput, CheckboxInput, DatePicker... | Formulaires |
layout.md
| 862 | DetailPage, ListPage, PageLayout, TabsLayout | Structure de pages |
framework.md
| 516 | DataTable, AssetGallery, PaginationControls | Affichage de données |
VENDURE_UI_COMPONENTS_BASE.md
| 724 | Documentation de base des composants | Référence rapide |
Import standard :
import { Button, Card, Dialog, Badge } from "@vendure/dashboard";
import { TextInput, SelectInput } from "@vendure/dashboard";
import { DetailPage, ListPage } from "@vendure/dashboard";
Commandes grep utiles :
grep -A 20 "^## Button" references/UI/ui.md
grep -A 30 "TextInput" references/UI/form-inputs.md
grep -n "DetailPage" references/UI/layout.md
- Démarrer →
references/Guides/getting-started.md
- Comprendre →
references/Guides/core-concepts.md
(Money, Collections)
- Construire →
references/Guides/how-to.md
- Explorer → GraphQL Playground à
/shop-api
- Rechercher API →
references/reference/typescript-api.md
- Créer plugins →
references/Guides/developer-guide.md
- Paiements →
references/reference/core-plugins.md
(StripePlugin)
- Emails →
references/reference/core-plugins.md
(EmailPlugin)
- Architecture →
references/Guides/developer-guide.md
(API Layer, Middleware)
- Dashboard custom →
references/UI/
+ references/Guides/extending-the-dashboard.md
- Sécurité →
references/Guides/deployment.md
(HardenPlugin, OWASP)
- Performance → State machines, caching, optimisations
| Tâche | Fichier de référence |
|---|
| Démarrer un projet | Guides/getting-started.md
|
| Afficher des prix | Guides/core-concepts.md
|
| Accepter des paiements | reference/core-plugins.md
|
| Envoyer des emails | reference/core-plugins.md
|
| Créer un plugin | Guides/developer-guide.md
|
| Upload de fichiers | Guides/developer-guide.md
|
| Valider commandes | reference/typescript-api.md
|
| Requêtes GraphQL | reference/graphql-api.md
|
| Stocker des prix | Guides/core-concepts.md
|
| Installer Dashboard | Guides/getting-started.md
|
| Créer page Dashboard | UI/layout.md
+ Guides/extending-the-dashboard.md
|
| Composants formulaire | UI/form-inputs.md
|
| DataTable | UI/framework.md
|
# Trouver une classe/interface
grep -rn "PaymentMethodHandler" references/
# Trouver un hook React
grep -rn "useDetailPage" references/reference/
# Trouver un composant UI
grep -n "Button" references/UI/ui.md
# Lister les sections d'un fichier
grep -n "^## " references/reference/typescript-api.md | head -30
references/
├── Guides/ # Tutoriels et guides pratiques
│ ├── getting-started.md
│ ├── developer-guide.md
│ ├── core-concepts.md
│ ├── extending-the-dashboard.md
│ ├── how-to.md
│ ├── storefront.md
│ ├── deployment.md
│ ├── user-guide.md
│ └── migrating-from-v1.md
├── reference/ # Documentation API technique
│ ├── typescript-api.md # ⭐ Le plus important (21k lignes)
│ ├── core-plugins.md
│ ├── dashboard.md
│ ├── graphql-api.md
│ ├── admin-ui-api.md
│ └── reference.md
└── UI/ # Composants Dashboard React
├── ui.md # 42 composants UI
├── form-inputs.md # 11 composants formulaire
├── layout.md # Pages et layouts
├── framework.md # DataTable, etc.
└── VENDURE_UI_COMPONENTS_BASE.md
Scripts utilitaires pour interagir avec les APIs GraphQL de Vendure.
curl
- Requêtes HTTPjq
- Manipulation JSONbash
5+ - Requis pour tableaux associatifs (macOS: brew install bash
)
| Script | Description |
|---|
login.sh
| Authentification et aide aux requêtes curl |
query.sh
| Exécution simplifiée de requêtes GraphQL |
Script d'authentification pour obtenir un token JWT et faciliter les requêtes curl.
| Option | Alias | Description |
|---|
--from-last
| -l
| Utilise last-account.json |
--superadmin
| -s
| Mode superadmin |
--email
| -e
| Email de connexion |
--password
| -p
| Mot de passe |
--env
| -E
| Chemin .env |
--export
| -x
| Affiche exports shell |
--curl-example
| -c
| Exemple curl complet |
--quiet
| -q
| Mode silencieux |
--verbose
| -v
| Mode verbeux |
./login.sh -l # Login avec last-account.json
./login.sh -l -c # Affiche exemple curl complet
./login.sh -l -x # Affiche exports shell
./login.sh -s -E /path/.env # Login superadmin
./login.sh -e [email protected] -p z # Login manuel
./login.sh -l -q # Mode silencieux (scripts)
query.sh
- Requêtes GraphQL simplifiées
| Option | Alias | Description |
|---|
--vars
| -V
| Variables GraphQL JSON (remplace tout) |
--set
| - | Modifier une variable (merge jq) |
--file
| -f
| Fichier .graphql |
--superadmin
| -s
| Mode superadmin |
--env
| -e
| Chemin .env |
--raw
| -r
| Sortie JSON brute |
--data
| -d
| Affiche seulement .data |
--clear-cache
| -c
| Force reconnexion |
--timeout
| -t
| Timeout en secondes |
--history
| -H
| Affiche les 10 dernières requêtes |
--last
| -L
| Ré-exécute la dernière requête |
--replay N
| -R
| Ré-exécute la requête #N de l'historique |
--inspect N
| -I
| Affiche query #N + variables (sans exécuter) |
--save NAME
| -S
| Sauvegarde dans queries/NAME.graphql
|
--shop
| -p
| Utilise /shop-api
au lieu de /admin-api
|
--time
| -T
| Affiche le temps d'exécution |
--diff "OPTS"
| - | Compare 2 exécutions (avant/après OPTS) |
--diff-only
| - | Avec --diff: affiche uniquement les valeurs changées |
--no-fail
| - | Ne pas exit 1 sur erreur GraphQL (continuer malgré les erreurs) |
--dry-run
| - | Affiche la requête sans l'exécuter (pas d'auth) |
--curl
| - | Génère la commande curl équivalente (copier-coller) |
--jq FILTER
| -j
| Appliquer un filtre jq sur le résultat |
--assert EXPR
| -a
| Valider une condition jq (exit 1 si fausse) |
--quiet
| -q
| Mode silencieux (supprime tous les logs stderr) |
--output FILE
| -o
| Écrire le résultat dans un fichier |
--verbose
| -v
| Mode verbeux |
./query.sh '{ me { id } }' # Requête simple
./query.sh -d '{ me { id } }' # Affiche seulement .data
./query.sh -s -e /path/.env '{ administrators { totalItems } }'
./query.sh -c '{ me { id } }' # Force reconnexion
./query.sh -t 60 '{ me { id } }' # Timeout 60s (défaut: 30s)
./query.sh -s -c -d '{ me { id } }' # Combinaison d'alias
# Historique et Replay (50 requêtes max, style Burp Repeater)
./query.sh -H # Affiche les 10 dernières
./query.sh -I 3 # Inspecte query #3 + variables (sans exécuter)
./query.sh -L # Ré-exécute la dernière
./query.sh -L -s # Dernière requête en superadmin
./query.sh -R 3 # Ré-exécute la requête #3
./query.sh -R 3 -s # Requête #3 en superadmin
./query.sh -R 3 --vars '{"take": 5}' # Requête #3 avec variables remplacées
./query.sh -R 3 --shop # Requête #3 sur shop-api
./query.sh -R 3 -T # Requête #3 avec timing
# Modifier des variables avec --set (merge intelligent)
./query.sh -R 3 --set '.take=10' # Modifier une variable
./query.sh -R 3 --set '.take=10 | .skip=20' # Modifier plusieurs (pipe jq)
./query.sh -R 3 --set '.filter.status="active"' # Objet imbriqué
./query.sh -R 3 --set '.take=10' --set '.id="99"' # Multiples --set
# Comparer deux exécutions avec --diff
./query.sh '{ me { id } }' --diff "--superadmin" # vendor vs superadmin
./query.sh -R 3 --diff "--set '.take=20'" # take=10 vs take=20
./query.sh '{ products { totalItems } }' --diff "--shop" # admin vs shop
# Mode compact avec --diff-only (affiche uniquement les chemins JSON modifiés)
./query.sh -R 3 --diff "--set '.take=1'" --diff-only
# Affiche: A .data.products.items[1].name = "Courgette"
# B .data.products.items[1].name = (absent)
# Prévisualiser sans exécuter avec --dry-run (pas d'authentification)
./query.sh '{ products { items { id } } }' --dry-run
./query.sh -R 3 --set '.take=10' --superadmin --dry-run
./query.sh --file queries/get-product.graphql --vars '{"id":"42"}' --shop --dry-run
# Affiche: 📝 Query, 📦 Variables, 🔑 Auth, 🌐 Endpoint + "(non exécuté)"
# Générer une commande curl équivalente (copier-coller)
./query.sh '{ me { id } }' --curl
./query.sh '{ products { items { id } } }' --superadmin --curl
./query.sh -R 3 --vars '{"take": 5}' --shop --curl
# Affiche:
# curl -X POST 'http://localhost:3000/admin-api' \
# -H 'Content-Type: application/json' \
# -H 'Authorization: Bearer eyJ...' \
# -d '{"query":"{ me { id } }","variables":{}}'
# Filtrer les résultats avec --jq
./query.sh '{ products { totalItems } }' --jq '.data.products.totalItems'
# → 42
./query.sh '{ products { items { name } } }' --jq '.data.products.items[].name'
# → Orange Sanguine
# → Courgette Longue verte
./query.sh '{ products { items { id name enabled } } }' \
--jq '.data.products.items[] | select(.enabled == true) | .name'
./query.sh '{ products { items { id } } }' -j '.data.products.items | length'
# → 5
# Valider avec --assert (exit 1 si condition fausse)
./query.sh '{ products { totalItems } }' --assert '.data.products.totalItems > 0'
./query.sh '{ product(id: "1") { id } }' -a '.data.product | type == "object"'
# Workflows conditionnels avec && / ||
./query.sh '{ products { totalItems } }' --assert '.data.products.totalItems > 0' \
&& echo "Catalogue OK" || echo "Catalogue vide!"
# Combiner --assert et --jq (valider puis extraire)
./query.sh '{ products { totalItems } }' \
--assert '.data.products.totalItems > 0' \
--jq '.data.products.totalItems'
# Mode silencieux avec --quiet (capture propre)
TOTAL=$(./query.sh -q '{ products { totalItems } }' -j '.data.products.totalItems')
echo "Total: $TOTAL"
# Écrire dans un fichier avec --output
./query.sh '{ products { items { id name } } }' --output /tmp/products.json
./query.sh '{ orders { items { id } } }' -o /tmp/orders.json
# Automatisation totale : --quiet + --output + --assert + --jq
./query.sh -q '{ products { totalItems } }' \
--assert '.data.products.totalItems > 0' \
--jq '.data.products.totalItems' \
-o /tmp/count.txt
# Sauvegarde
./query.sh -S get-me '{ me { id } }' # Sauvegarde dans queries/get-me.graphql
./query.sh -f queries/get-me.graphql # Charge et exécute
# Requête multi-lignes (guillemets simples)
./query.sh '
query {
products(options: { take: 5 }) {
items { id name }
}
}
'
# Avec variables (utiliser heredoc si la requête contient !)
./query.sh --vars '{"id": "42"}' <<'EOF'
query GetProduct($id: ID!) {
product(id: $id) { name }
}
EOF
# Depuis stdin
echo '{ me { id } }' | ./query.sh
# Shop API (storefront)
./query.sh --shop '{ products { items { id name } } }'
./query.sh --shop '{ activeCustomer { id emailAddress } }'
# Mesure du temps d'exécution
./query.sh -T '{ me { id } }' # Affiche "⏱ 74ms"
./query.sh -s -T '{ administrators { totalItems } }'
./query.sh --shop -T '{ products { items { id } } }'
⚠️ Limitation : Le caractère
!
(ex: ID!
) pose problème en inline à cause
du history expansion bash. Si erreur "Unexpected character", utiliser heredoc
(<<'EOF'
) ou fichier (--file query.graphql
) à la place des guillemets simples.
Le système d'historique et replay permet de déboguer efficacement les requêtes GraphQL :
# 1. Exécuter une requête qui échoue ou retourne des résultats inattendus
./query.sh '{ products(options: { take: 5 }) { items { id name } } }'
# 2. Consulter l'historique pour voir les requêtes récentes
./query.sh -H
# Affiche:
# [1] 14:23:01 { me { id } }...
# [2] 14:25:33 query GetProducts($take: Int)...
# [3] 14:28:45 { collections { items { id }...
# 3. Inspecter une requête AVANT de la rejouer (voir query + variables)
./query.sh -I 2
# ═══════════════════════════════════════════════════════════
# Query #2 (2025-12-30 14:25:33)
# ═══════════════════════════════════════════════════════════
# query GetProducts($take: Int) { products(options: { take: $take }) { ... } }
# ───────────────────────────────────────────────────────────
# Variables: {"take": 5}
# ═══════════════════════════════════════════════════════════
# 4. Rejouer une requête avec modifications
./query.sh -R 2 # Identique
./query.sh -R 2 -s # En superadmin (voir plus de données)
./query.sh -R 2 --vars '{"take": 10}' # Remplacer toutes les variables
./query.sh -R 2 --shop # Sur shop-api au lieu d'admin-api
# 5. Modifier des variables spécifiques avec --set (merge)
./query.sh -R 2 --set '.take=10' # Modifier une seule variable
./query.sh -R 2 --set '.filter.status="pending"' # Modifier un objet imbriqué
./query.sh -R 2 --set '.take=10' --set '.skip=5' # Modifier plusieurs variables
# 6. Comparer les résultats avec --diff
./query.sh -R 2 --diff "--superadmin" # vendor vs superadmin (diff coloré)
./query.sh -R 2 --diff "--set '.take=10'" # take=5 vs take=10
./query.sh -R 2 --diff "--shop" # admin-api vs shop-api
./query.sh -R 2 --diff "--set '.take=1'" --diff-only # Mode compact (chemins JSON)
Cas d'usage typiques :
- Inspecter avant de rejouer : voir la query complète et ses variables avec
-I
- Prévisualiser sans exécuter : utiliser
--dry-run
pour voir query/variables/auth/endpoint sans connexion
- Générer curl : utiliser
--curl
pour obtenir une commande curl copier-coller (Postman, CI/CD, partage)
- Modifier chirurgicalement : utiliser
--set
pour changer une variable sans tout retaper
- Comparer rapidement : utiliser
--diff
pour voir les différences, --diff-only
pour le format compact
- Valider avant d'agir : utiliser
--assert
pour vérifier des conditions (workflows conditionnels)
- Continuer malgré les erreurs : utiliser
--no-fail
pour enchaîner plusieurs requêtes sans interruption
- Extraire et filtrer : utiliser
--jq
pour extraire des valeurs spécifiques
- Capturer proprement : utiliser
--quiet
pour supprimer les logs et capturer uniquement le résultat
- Sauvegarder les résultats : utiliser
--output
pour écrire dans un fichier (JSON propre sans couleurs)
- Modifier des objets imbriqués facilement avec la syntaxe jq
- Basculer entre admin-api et shop-api pour comparer les comportements
- Analyser les erreurs de permission en comparant vendor vs superadmin
last-account.json
: Credentials du dernier compte créé (email, password, vendorId).token-cache.vendor
: Cache des tokens vendeur (30 min).token-cache.superadmin
: Cache des tokens superadmin (30 min).query-history
: Historique des 50 dernières requêtes GraphQLqueries/
: Requêtes GraphQL sauvegardées avec --save
- Ce skill est généré à partir de la documentation officielle Vendure (docs.vendure.io)
- Les exemples de code incluent la détection de langage pour le highlighting
- Toutes les valeurs monétaires sont représentées en entiers (diviser par 100 pour l'affichage)
- GraphQL est l'interface API principale (Shop API pour storefront, Admin API pour gestion)
- Le Dashboard utilise React et TailwindCSS - toujours importer depuis
@vendure/dashboard
Pour rafraîchir ce skill avec une documentation mise à jour :
- Re-scraper la documentation officielle docs.vendure.io
- Réorganiser les fichiers dans la structure Guides/reference/UI
- Mettre à jour les compteurs de lignes dans ce SKILL.md