Drupal's ongoing evolution has seen many innovations, with the latest being the introduction of Recipes with the “Recipes Initiative” in Drupal 10.3. Recipes, now part of the core of Drupal, represent a significant shift in how developers can automate the setup and configuration of Drupal sites. A Recipe explores the idea of “composibility” which will enable people to compose a Drupal website as per the need or at least a solid foundation.

In this article, we’ll discuss Recipes in detail - what they are, why they’re fantastic, and how you can use them to create a perfectly crafted site. Get ready to cook up a storm with a foolproof recipe for Drupal success!

But we already have Distributions!

The concept of pre-configured packages is not new to Drupal. It was first introduced in Drupal 5 as Drupal distributions that include the Drupal core, along with additional modules, themes, and configurations aimed at serving a specific use case or industry. This concept made it easier for developers to quickly set up Drupal for specific applications like intranets, e-commerce sites, or government portals without starting from scratch.

However, Drupal distributions offer a convenient way to get started with pre-configured setups, but they come with some drawbacks:

  • Limited Flexibility: Predefined features and tightly integrated modules make customization difficult.
  • Maintenance Complexity: Updating distributions can be challenging due to custom configurations, leading to potential compatibility issues.
  • Dependency on Maintainers: Some distributions may be poorly maintained or abandoned, causing risks to security and updates.
  • Performance Overhead: Unnecessary bundled modules can slow down the site and introduce vulnerabilities.
  • Niche Focus: Distributions are often tailored to specific use cases, making it difficult to adapt if your needs change.

Drupal Recipes solves problems with distributions by offering more modularity. Instead of coupling everything together, Recipes let you add only the specific features you need, avoiding the bloat of unnecessary modules.

A Recipe in action

To illustrate, imagine I need to set up an Event feature. For this, I will apply (Recipes are not installed but rather applied) an “Events Content-Type” Recipe which will set an Event content type with necessary attributes & fields, and configure views, metatags & paths for the Event contents. This will give me a solid foundational starting point to implement the feature where 70-80% of the basic setup and configurations are done by Recipes and on top of it I can make customizations to configure other settings as per my requirements. However, once applied, I am no longer dependent on the Recipe package anymore and it can be safely removed from my project keeping all the configured setup intact.

Benefits of Drupal Recipes

  • Modular Setup: Recipes allow for specific features or configurations to be added individually at any point in a project timeline. 
  • Combine Multiple Recipes: Recipes can be easily combined or modified to fit specific use cases. This allows for a more customizable site-building experience, making it easier to adapt to changing requirements.
  • No Lock-in: Unlike distributions, which are often tightly integrated, recipes give you more freedom to swap out or upgrade parts of your setup without being tied to a rigid structure.
  • Composable: As mentioned above you can combine multiple recipes which means you can also compose Recipes with other recipes easily. If you want Event registration but also Commerce capabilities, you can easily create a new recipe that will apply the Event and Commerce recipes to be set up.

What Recipes can do

  • Install Modules and Themes: Recipes can automatically install necessary modules and themes.
  • Apply Configurations: Recipes can apply both default and selective configurations provided by modules.
  • Update Configurations: Recipes can update module configurations to fit your site's needs through' config actions'.
  • Composable and Reusable: Recipes can be composed of other Recipes, making them highly modular and reusable across different projects.

What Recipes cannot do

  • Custom Code or Hooks: Recipes do not include custom PHP code, hooks, or API integrations.
  • Module-Like Functionality: Unlike modules, Recipes cannot contain custom plugins, forms, or other typical Drupal module structures.
  • Persistent Locking: Recipes do not persist after application; they set up the initial state and can be safely removed.

Want to take full advantage of Drupal Recipes? Schedule a consultation with our experts and discover how our Drupal development services can help boost your site's growth!

How to create and use a Recipe

To get started, it is recommended that a new custom repository is created for the recipe. This will ensure that the recipe is version-controlled & managed efficiently to be used on other projects. 

At the bare minimum, a recipe will require a “recipe.yml” file as the required file which will define the meta information like name, and description along with installations of modules/themes & configuration installations/updates.

Apart from the “recipe.yml” a Recipe can also have the below optional items.

  • The “config” directory holds the configuration entity yml files which will be installed when the Recipe is applied.
  • The “content” directory holds the content entity yml files which will be created after the Recipe is applied.
  • A “composer.json” file that allows the discoverability of Recipes via Composer. It will define any dependencies the Recipe might have on other modules or themes.
  • A “README.md” can also be included to give a brief description of the Recipe which will allow users to better evaluate.

So, the folder structure of a Recipe can look like this:

  • recipe_name
           ◦ recipe.yml
           ◦ config
               ▪ node.type.event.yml
           ◦ content
               ▪ node
                   • 43940d31-0106-46b4-ba32-39e511eb1f4a.yml
           ◦ composer.json
           ◦ README.md

Dissecting the recipe.yml file

A “recipe.yml” at minimal consists of “name” & “description” keys. Apart from that, it can include three different keys:

  • Install packages with the “install” key which will specify the modules and/or themes to be installed when the Recipe is applied. If not already installed, Drupal will proceed to install each of the modules & themes specified in the list.
install:
  - address
  - datetime_range
  - media
  - media_library
  - geolocation_address
  - geolocation_leaflet
  - layout_builder
  - metatag
  - pathauto
  - paragraphs
  - smart_date
  • Configuration related task under “config” key. 
    This allows you to “import” configurations from a module in two ways

    • Import all the configurations from a module with the “*” wildcard. This will import all the base configurations & optional configurations from a module.
    • Import selective configuration from a module by specifying the list of configurations to be imported.

config:
  import:
    media: "*"
    node:
      - views.view.content

When you want to update any active configuration which is being imported or any existing once, “action” comes into play which will allow you to update those configurations

config:
  actions:
    metatag.settings:
      simple_config_update:
        entity_type_groups.node.event:
          - basic
          - advanced
    workflows.workflow.editorial:
      addNodeTypes:
        - event
  • Dependency on other recipes can be included under the “recipes” key which specifies the list of Recipes to be applied prior applying the current Recipe.
recipes:
  - core/recipes/image_media_type
  - core/recipes/editorial_workflow

Applying a Recipe

Until reaching Phase 2 and a user interface (UI) for easier application, recipes are currently applied using Drupal core's PHP script. It can be executed with the following command in the CLI Drupal root:

php core/scripts/drupal recipe recipes/recipe_name

After applying the recipe, it's also necessary to clear the caches to ensure the changes take effect.

Applying a hosted Recipe

If you Recipe has a “composer.json” file then it can be hosted on Packagist.org to make it discoverable and included in any project. However, to download the recipe in a “recipes” directory there are few changes which are required to be made in the project’s “composer.json” file

composer require oomphinc/composer-installers-extender:2.0.1

Update “installer-types” & “installer-paths” keys in the “composer.json”

"installer-types": ["drupal-recipe"], 
"installer-paths": {
  "web/recipes/{$name}": [ "type:drupal-recipe" ]
}

When you request Composer for a recipe, it will automatically place it in your project's “recipes” directory, similar to how it handles modules or themes.

Once this is setup, you then you can use composer to require the package as usual.
For this example, I am using a sample recipe which set ups an Event content type along with other configurations updates.  https://github.com/malabya/event_content_type/

composer require imalabya/event_content_type

Once downloaded this can be applied with the Drupal core scripts

php core/scripts/drupal recipe recipes/event_content_type

Once the recipe is applied this will create an Event content type and enable Editirial workflow for the Event content type with default core configurations. This will also create 2 default contents for the Event content type to get started.

Unpacking Recipes

Even though Recipes do not lock in your site and can be safely replaced or removed once applied, you would want to maintain the dependencies in your project. When you request a Recipe, it will download all the dependencies mentioned in the Recipe’s “composer.json” file, but these dependencies are not copied/unpacked over into the project’s “composer.json” which will make it difficult to maintain or upgrade those dependencies.

For this, use the composer plugin Drupal Recipe Unpack Composer Plugin to your project’s “composer.json” which allows the extraction of a packages dependencies into the project root composer and lock files for the sole purpose of implementation within Drupal recipes.

Once the plugin is installed you can run the below command to unpack the dependencies

composer unpack [organization/package-name]

Final thoughts

Recipes in Drupal 11 represent a powerful new tool for site builders and developers. They offer flexibility, modularity, and ease of maintenance that surpass traditional installation profiles and distributions. When it comes to creating a new Drupal site or adding new features, Recipes provides a streamlined, efficient way of managing the configuration.

As Recipes continues to evolve, they promise to make Drupal site development more agile and responsive to changing needs, ultimately making Drupal a more accessible and powerful platform for all users. So do you want to cook from scratch or use Drupal Recipes? Your choice!

Want to know how Drupal Recipes can enhance your project? Reach out to us to learn more about our Drupal development services and get started on your next big idea!

Contact us

LET'S DISCUSS YOUR IDEAS. 
WE'D LOVE TO HEAR FROM YOU.

CONTACT US SUBMIT RFP