Creating Your Own Recipe

Drupal recipes provide a standardized way to package and apply sets of modules, configurations, and permissions as reusable, composable units. This guide explains how to create a custom recipe that builds on Varbase to add project-specific functionality.

Recipe Structure

A Drupal recipe is a directory containing a recipe.yml file and optionally a config/ directory with configuration files. The basic structure is:

my_custom_recipe/
  recipe.yml
  config/
    module_name.config_name.yml
    another_module.another_config.yml

Creating the recipe.yml File

The recipe.yml file is the core of every recipe. It defines the recipe's metadata, dependencies, modules, configuration actions, and permissions.

Basic Structure

name: 'My Custom Recipe'
description: 'A custom recipe that adds project-specific functionality to a Varbase site.'
type: 'Site'

Defining Dependencies

Dependencies declare other recipes that must be applied before this recipe:

recipes:
  - varbase_content_base
  - varbase_media_base
  - easy_email_express

When your recipe is applied, all dependency recipes are applied first in the order listed.

Installing Modules

Specify modules that should be installed by the recipe:

install:
  - my_custom_module
  - views_bulk_operations
  - entity_browser

Configuration Actions

Config actions allow you to modify existing configuration or create new configuration:

config:
  actions:
    node.type.custom_page:
      createIfNotExists:
        type: custom_page
        name: 'Custom Page'
        description: 'A custom page content type for this project.'
        help: ''
        new_revision: true
        preview_mode: 1
        display_submitted: true

    user.role.custom_editor:
      createIfNotExists:
        id: custom_editor
        label: 'Custom Editor'
        weight: 5
        is_admin: false

Setting Permissions

Grant permissions to specific roles:

config:
  actions:
    user.role.custom_editor:
      grantPermissions:
        - 'create custom_page content'
        - 'edit own custom_page content'
        - 'delete own custom_page content'
        - 'view own unpublished content'

    user.role.content_editor:
      grantPermissions:
        - 'create custom_page content'
        - 'edit any custom_page content'
        - 'delete any custom_page content'

Including Configuration Files

To include full configuration files, place them in the config/ directory within your recipe. These files follow the same naming convention as Drupal configuration exports:

my_custom_recipe/
  recipe.yml
  config/
    node.type.custom_page.yml
    field.storage.node.field_custom_field.yml
    field.field.node.custom_page.field_custom_field.yml
    core.entity_view_display.node.custom_page.default.yml
    core.entity_form_display.node.custom_page.default.yml

Each configuration file contains the full YAML configuration for that config item. You can export existing configuration using Drush:

drush config:export --destination=/tmp/config

Then copy the relevant files to your recipe's config/ directory.

Complete Example

Here is a complete example of a custom recipe that adds a "Project" content type:

name: 'My Project Content Type'
description: 'Adds a Project content type with custom fields and permissions.'
type: 'Content type'

recipes:
  - varbase_content_base
  - varbase_media_base

install:
  - text
  - datetime
  - link
  - image

config:
  actions:
    user.role.content_editor:
      grantPermissions:
        - 'create project content'
        - 'edit any project content'
        - 'delete any project content'

    user.role.authenticated:
      grantPermissions:
        - 'view published project content'

With the corresponding configuration files in the config/ directory defining the content type, fields, view displays, and form displays.

Applying Your Recipe

To apply your custom recipe using Drush:

For Recipes in the Project Directory

Place your recipe in the recipes/ folder of your Varbase project, next to the Varbase recipes, then apply it:

ddev drush recipe ../recipes/my_custom_recipe

For Recipes Installed via Composer

If your recipe is published as a Composer package of type drupal-recipe, require it and Drupal core's Recipe Unpack plugin will unpack it into the recipes/ folder, adding its dependencies to your project's composer.json. Then apply it:

ddev composer require my-vendor/my_custom_recipe
ddev drush recipe ../recipes/my_custom_recipe

Publishing Your Recipe

To make your recipe available to others:

1. Create a project on Drupal.org.

2. Publish the recipe as a Composer package.

3. Others can then install it via Composer and apply it with Drush.

Best Practices

1. Keep recipes focused: Each recipe should address a single area of functionality. Compose larger configurations from multiple smaller recipes.

2. Declare dependencies explicitly: List all recipe dependencies so that applying your recipe automatically satisfies all requirements.

3. Use config actions over raw config: Prefer createIfNotExists and grantPermissions config actions over raw configuration files when possible, as they are more resilient to existing site state.

4. Test recipe application: Test your recipe on a clean Varbase installation to ensure it applies without errors.

5. Document your recipe: Include a clear description and any special instructions in the recipe.yml file.