Les Drupal Recipes sont apparues dans Drupal à partir de la version 10.3 et sont désormais intégrées au core depuis Drupal 11. Leur but est de proposer aux développeurs un mécanisme leur permettant d’installer et de configurer automatiquement un ensemble de fonctionnalités tout en concentrant les fichiers nécessaires dans un seul et même dossier.
Pourtant, les profils d’installation, la configuration globale du site, les thèmes et les modules permettent déjà d’apporter des évolutions de fonctionnalités, alors pourquoi s’embêter avec une nouvelle approche ? Dans cet article, nous vous proposons un petit tour d’horizon des Recipes avec leurs avantages et inconvénients et savoir quand les utiliser devient pertinent.
Pourquoi les Recipes ?
S’il fallait résumer les Recipes en une seule phrase, ce serait : Une Recipe est un pack de configuration et de fonctionnalités prêtes à l’emploi, réutilisable et installable sur un site existant.
La notion de « site existant » est très importante ici, car les Recipes n’introduisent pas de fonctionnalité révolutionnaire, elles permettent simplement de faciliter une action qui peut être faite par d’autres moyens.
Prenons un exemple : Nous avons un site Drupal déjà existant et en production. On souhaite désormais mettre en place un espace forum sur le site. Voici ce que cela va impliquer :
- installation de nouveaux modules (ex : module « Comment »)
- création d’un nouveau type de contenu (ex : « article de forum »)
- création de nouvelles taxonomies pour les catégories du forum
- création de nouveaux rôles utilisateurs (ex : Modérateur)
- création d’un nouveau workflow de validation
- création d’une nouvelle vue d’affichage (ex : Les derniers posts)
Tout ces ajouts impliquent d’importants changements à faire manuellement au niveau de la configuration complète du site.
Sans les Recipes, voici les options qui s’offrent à nous :
- Utiliser un profil d’installation. Problème : notre site est déjà existant, les profils d’installation ne fonctionnent qu’au moment de l’installation initiale du site.
- Créer un module custom avec inclusion de toutes ces évolutions de configuration à l’installation. Problème : ce n’est pas le but d’un module. Les modules sont censés être créés pour ajouter du code et de la logique métier.
- Surcharger la configuration générale du site et la réimporter. Problème : il faut être certain que notre développement reparte bien de la configuration de production pour éviter tout risque d’écrasement de l’existant.
Même si cela n’est pas impossible, nous voyons bien qu’aucune de ces options n’est idéale. C’est donc justement pour ce besoin d’ajout d’un « pack » de fonctionnalités à n’importe quel moment du cycle de vie du site qu’ont été créées les Recipes.
Avec les Recipes, tout peut être rassemblé en un seul dossier dont l’activation permettra d’ajouter tout le « pack » de fonctionnalités nécessaires au bon fonctionnement d’un forum.
Une Recipe peut en effet :
- installer des modules / thèmes
- créer des types de contenus
- ajouter des champs
- configurer des vues
- définir des rôles et permissions utilisateurs
- importer une configuration YAML
Recipe, Module ou Thème : que choisir ?
Maintenant que nous savons qu’il existe plusieurs méthodes pour enrichir un environnement Drupal, comment savoir dans quel cas de figure utiliser l’une ou l’autre ?
Les principales différences
Les différences principales entre les méthodes sont les suivantes :
| Élément | Rôle | Contient du code ? | Contient de la configuration ? | But principal |
| Module | Ajouter des fonctionnalités techniques et de la logique métier | Oui (PHP) | Parfois | Ajouter des capacités techniques |
| Thème | Gérer l’apparence | Oui (Twig, CSS, JS) | Très peu | Contrôler le design sans modifier la logique métier |
| Recipe | Installer + configurer un ensemble cohérent | Non (pas forcément) | Oui | Fournir une fonctionnalité prête à l'emploi |
Quand utiliser quoi ?
Ayant vu le but principal de chaque élément, nous pouvons en déduire le tableau suivant pour savoir quelle méthode est la plus appropriée en fonction du besoin initial.
| Besoin initial | Solution |
| Ajouter une fonctionnalité technique (ex : API custom) Créer des services Définir des plugins Modifier le comportement du core de Drupal |
Module |
| Modifier le design (templates / CSS) | Thème |
| Ajouter une fonctionnalité complète prête à l’emploi (ex : forum, blog...) | Recipe |
| Créer une distribution complète à activer à l’installation initiale du projet | Profil d’installation |
Avantages et inconvénients des Recipes
Les Recipes sont donc bien une nouvelle méthode à part entière qui répond à un besoin qui était présent dans l’écosystème Drupal et difficile à adresser avec les éléments historiques que sont les modules, thèmes et profils d’installation.
Les avantages des Recipes
Les avantages proposés par les Recipes sont :
- Approche modulaire moderne – Le principe est similaire aux modules : tous les fichiers associés à la fonctionnalité sont répertoriés dans un seul et même dossier et il suffit ensuite d’installer la Recipe.
- Installation progressive – Une Recipe peut être installée à tout moment du cycle de vie d’un site. Il est possible d’enrichir un site existant sans devoir tout réinstaller.
- Réutilisabilité – Une Recipe propose une fonctionnalité complète, elle peut donc être installée de manière indépendante sur des sites différents.
Les inconvénients des Recipes
Toutefois, les Recipes présentent quelques inconvénients :
- Inadaptées pour la logique complexe – Ces points doivent être adressés par un module.
- Complexification de la maintenance – Si les Recipes sont mal structurées ou trop nombreuses, il peut être difficile de comprendre quelle fonctionnalité provient de quelle Recipe.
- Impossibilité de mettre à jour la fonctionnalité – Tout comme un profil d’installation, une Recipe est appliquée une seule fois. Une fois que la fonctionnalité est ajoutée au site, il n’est pas possible de la faire évoluer en mettant simplement à jour des fichiers de la Recipe.
- Écosystème en évolution – Ayant été introduites récemment dans Drupal, il n’est pas impossible que le principe des Recipes soit encore sujet à évolution avant d’arriver à maturité.
Structure et mise en place d’une Recipe
Voyons maintenant comment se structure une Recipe et comment la mettre en place sur un site.
Structure d’une Recipe
Les recipes suivent les mêmes règles que thèmes et modules : un fichier YAML obligatoire pour pouvoir la déclarer puis le positionnement des fichiers de configuration dans un répertoire config/install/.
La structure générale d’une Recipe est donc la suivante :
my_recipe/
├── recipe.yml
├── config/
│ └── install/
│ └── fichiers de configuration YAML
├── content/
│ └── file/
│ └── media/
│ └── node/
Où le fichier recipe.yml contient les informations suivantes :
name: “My Recipe”
description: “Description of my recipe”
type: “feature”
# Liste des modules à installer pour les besoins de la Recipe
install:
- module_1_to_install
- module_2_to_install
Le répertoire config/ contient les fichiers de configuration YAML à ajouter pour les besoins de la fonctionnalité.
Le répertoire content/ (optionnel) permet de déclarer des éléments de contenu éditorial qui sont à créer pour les besoins de la fonctionnalité (ex : Création de la page « Liste des articles » ou création des termes de la taxonomie « Tags »).
Enfin, le dossier de la Recipe doit être positionné dans l’arborescence du site. Par défaut, il est recommandé de créer un répertoire recipes/ au même niveau que le répertoire web/.
Appliquer une Recipe
Deux étapes sont nécessaires pour appliquer une Recipe :
- Récupération de la Recipe via Composer avec la commande suivante :
composer require drupal/my_recipe
Cette commande récupère le dossier de la recipe et le positionne dans le répertoire souhaité de l’arborescence du site.
Cette étape n’est pas nécessaire pour les recipes custom créées localement. - Application de la Recipe via Drush avec la commande suivante :
drush recipe path/to/my_recipe(ex :drush recipe ../recipes/my_recipe)
Pensez à vider le cache du site avant de vérifier que les changements ont bien été appliqués à votre site.
Exemple - Création d’une Recipe « espace Blog »
Imaginons que sur notre site nous souhaitions ajouter un « espace Blog ». Voici ce que nous allons devoir ajouter :
- un type de contenu Article
- une taxonomie Tags
- des champs (Image, Résumé, Tags)
- une vue « Liste des articles du blog »
- les permissions utilisateurs nécessaires pour pouvoir créer des articles.
Notre Recipe va donc avoir la structure suivante :
blog_recipe/
├── recipe.yml
└── config/
└── install/
├── node.type.article.yml
├── field.storage.node.field_text.yml
├── field.field.node.article.field_text.yml
├── field.storage.node.field_image.yml
├── field.field.node.article.field_image.yml
├── field.storage.node.field_tags.yml
├── field.field.node.article.field_tags.yml
├── views.view.blog.yml
├── user.role.blog_author.yml
└── taxonomy.vocabulary.tags.yml
Fichier recipe.yml
Le fichier recipe.yml contiendra les informations suivantes :
name: Blog Recipe
type: feature
description: "Ajoute une fonctionnalité blog complète avec type de contenu, vue et permissions." # Liste des modules à activer
install:
- node
- text
- user
- views
- image
- taxonomy
# Liste des fichiers de configuration à importer
config:
import:
- node.type.article
- field.storage.node.field_text
- field.field.node.article.field_text
- field.storage.node.field_image
- field.field.node.article.field_image
- field.storage.node.field_tags
- field.field.node.article.field_tags
- views.view.blog
- user.role.blog_author
- taxonomy.vocabulary.tags
Fichiers de configuration
Les fichiers de configuration listés dans le dossier config > import vont quant à eux permettre, à l'activation de la recipe :
- La création du type de contenu « Article » (node.type.article.yml)
- La création des champs suivants associés à ce type de contenu :
- Champ texte “field_text” (field.field.node.article.field_text.yml et field.storage.node.field_text.yml)
- Champ image “field_image” (field.field.node.article.field_image.yml et field.storage.node.field_image.yml)
- Champ Tags “field_tags” (field.field.node.article.field_tags.yml et field.storage.node.field_tags)
- La création d’un nouveau rôle utilisateur « Auteur d’article de blog » (user.role.blog_author.yml) pouvant ajouter/éditer/supprimer des contenus de type « Article »
- La création d’une page de liste des articles de blog (views.view.blog.yml).
- La création d’une taxonomie « Tags » (taxonomy.vocabulary.tags.yml)
Nous ne détaillons pas le contenu de ces fichiers ici, ces derniers peuvent différer selon les spécificités choisies par le développer pour chaque champ (ex : champ obligatoire ou non, champ multivalué ou non...). Le but ici est simplement de fournir une liste complète de configurations permettant la mise en place effective d’une recipe.
Vous en savez maintenant un peu plus sur les nouvelles venues que sont les Recipes dans l’écosystème de Drupal. Développées dans le but de gommer une difficulté dans le développement de nouvelles fonctionnalités, elles sont désormais un atout supplémentaire de Drupal en offrant une approche presque « plug’n’play » pour la mise en place de ces dites nouvelles fonctionnalités.
Sans toutefois remplacer les modules, thèmes et profils, elles viennent en complément de ces éléments pour pouvoir enrichir plus facilement votre site Drupal.
Crédit photo : Jacob Wackerhausen
15 juin 2026
9 minutes
