Recipes, Site Templates and the future of Drupal distributions

The session was a technical deep-dive, sitting alongside the broader strategic overviews that others gave at the conference - Pam Barone covered site templates from the perspective of Drupal CMS in her keynote, and Murray Woodman covered what it takes to build a template for the site template marketplace. I get to go deeper on the mechanics.

The problem with distributions

If you've built or maintained a Drupal distribution before, you probably have opinions about it. Strong ones.

A distribution (or "distro") bundles together Drupal core, contributed and sometimes custom modules, an install profile, a theme, and opinionated configuration. It's a complete package. The trouble is, once you choose one, you're largely stuck with it for the life of the project. You're inheriting the software, the bugs, the governance model, and the community politics that come along with it.

The fundamental issue is config lock-in. The install profile owns a chunk of your site's configuration, and the moment your requirements start to diverge from what the distro provides, upgrades become reconciliation exercises.

Here's a concrete example. Say you're using a distribution that provides an article content type. Your site needs a read time field on that content type, so you add it. You also add a few custom views and tweak some form displays. Then the distro releases a new version that also modifies the article content type. Now you've got a conflict - their config versus yours. It's like a git merge, except instead of code it's configuration, and the stakes are a running production site.

It gets messier with modules. You've already integrated the Scheduled Transitions module to control when content gets published. The new version of the distro adds the same capability using a different module. Now you've got two competing solutions for the same problem, and untangling them is a project in its own right.

The underlying question this raises is: what if features didn't have to be tied to a profile at all? What if they could be applied to existing sites, stacked on top of each other, and - once applied - just become yours to do with as you please?

That's the problem recipes are designed to solve.

What recipes actually are

A recipe is a set of instructions that does three things: installs modules, applies configuration, and then gets out of the way. There are no hooks, no plugins, no services. It has no ongoing knowledge of what else is on the site. Once applied, it's gone.

This is fundamentally different from an install profile, which remains part of your site and continues to assert ownership over configuration. A recipe hands you the config and walks away.

Drupal core already ships with a set of recipes that effectively replace the standard install profile. Three of them illustrate how composability works in practice.

The tags taxonomy recipe installs the Taxonomy module and creates a tags vocabulary. That's it.

The article content type recipe installs the Node module and creates an article content type with a body field - but no tags field yet.

The article tags recipe depends on both of the above. When applied, it first applies those two recipes, then adds the tags field to the article content type.

Each recipe has a recipe.yml file at its core. Here's an abbreviated version of what the article content type recipe looks like:

name: 'Article (Content Type)'
description: 'Provides an article content type.'
type: 'Content type'

install:
  - image
  - node
  - path

config:
  strict:
    - field.storage.node.field_image
  actions:
    node.type.article:
      createIfNotExists:
        type: article
        name: Article
    node.article.default.default:
      setComponent:
        name: body
        # ...

A couple of things worth understanding here. The strict key controls whether a recipe insists on owning that piece of config. Setting strict: true for the image field storage means the recipe will assert its version of that config. Setting it to false (the default) means: if that config already exists on the site, use it - don't override it.

The actions key is where things get interesting. Config actions let you modify configuration that may or may not already exist. createIfNotExists is exactly what it sounds like: create this content type if there isn't one already, but if there is, just continue. This is what allows recipes to be safely applied to existing sites, not just fresh installs.

You apply a recipe via Drush:

ddev drush recipe path/to/recipe --verbose

The verbose flag is worth using while you're learning - it shows you exactly which recipes are being applied and in what order.

Site templates: recipes at scale

A site template is, technically speaking, just a recipe. There's no special format, no different file structure. You still have a recipe.yml file that looks exactly the same. The difference is scope - a site template is the whole site, not just a feature.

Site templates are meant to be a starting point, not an ongoing relationship. You install one, it sets up everything, and from that point on the site is yours. There's no upgrade path in the traditional sense.

There are two ways to build one.

The manual approach

If you want full control over the architecture of your template, you build it up from individual recipes. You might create a workflow recipe, a media handling recipe, a content types recipe - small, focused, potentially reusable pieces. Each of those are then referenced in your top-level site template recipe, alongside any additional modules that don't fit neatly into their own recipe, global configuration to tie things together, and a theme.

This approach is more work upfront, but it's the right call if you want to reuse recipes across sites. The individual recipes can be applied independently to existing sites, which makes them more valuable beyond just the template context.

One practical tip from building this way: build and install incrementally. Don't try to write the whole thing and then run it. Install frequently, catch issues early, and add complexity gradually.

Once you're happy with the site, you can add default content using Drush's content:export command, which serialises your nodes, blocks, and other content as YAML files that sit inside the recipe.

The automatic approach

If you don't need the abstraction of individual recipes and just want to get something out the door, there's a faster path. Build your site however you normally would, then install the Drupal CMS helper module. Despite the name, you don't need Drupal CMS to use it - the main thing it provides is the drush site:export command.

Run that command pointing at a directory, and it exports your entire site - config, content, modules, everything - into a recipe structure ready to install. It's a single command that does what would otherwise be a painstaking manual process.

To demonstrate this, I built Kaimami - a New Zealand-flavoured take on the Umami demo install. I installed the Umami profile, made a few adjustments, ran the export, made a couple of extra tweaks, and ended up with a complete site template. Installing it is then just:

drush site:install path/to/recipes/kaimami

Or more specifically, pointing Drush at the recipe path.

A useful tool: dripyard/recipe_builder

If you're starting out and writing recipes by hand, dripyard_recipe_builder is worth knowing about. It's a Drush command that guides you through the process of generating a recipe interactively, which cuts down on the YAML errors and "which key was it again?" friction that comes with building your first few recipes from scratch.

The marketplace and community templates

Once you've built a site template, there are two ways to share it.

The official Drupal Site Template Marketplace launched at DrupalCon Chicago earlier this year with 11 templates. To submit to the marketplace, your template must be built on Drupal CMS, should use Drupal Canvas, must meet accessibility standards, and currently needs to come from a Drupal Certified Partner or a Ripple Maker. That eligibility criteria may broaden over time, but that's the current state.

If you don't meet those requirements - or just don't need them - you can publish your template as a community project on drupal.org, the same way you'd publish a module or theme.

Pam Barone has written a clear breakdown of the distinction between the two pathways: Differentiating marketplace site templates and community site templates.

The honest tradeoffs

Site templates are not a straight replacement for distributions. They make different tradeoffs, and it's worth being clear about what you're giving up.

The biggest one is the upgrade path. With a distribution, there's at least a defined process (however painful) for pulling in upstream changes. With a site template, there isn't one by design. The template is a starting point. Once it's installed, the site evolves independently. If you're an agency running 20 sites built from the same template and the template gets a version 2, those sites don't automatically get the improvements.

This also creates a support and documentation challenge. Two sites built from different versions of the same template can diverge significantly in behaviour and structure. Managing that across a portfolio requires discipline.

The flip side is that this is also the point. You own the site from day one. There's no upstream to fight with when your requirements diverge, no config reconciliation projects, no having to patch around a profile's opinions to get to what you actually need. You traded long-term synchronisation for immediate flexibility.

So are distributions actually dead?

No - but the definition is evolving.

Traditional install profiles still have a place. A university managing dozens of tightly standardised sites across faculties, all needing to stay in sync with a central governance model, is probably not switching to site templates any time soon. The upgrade and synchronisation model of a distribution, painful as it can be, still serves that use case.

But for agencies starting new client sites, site templates are a compelling alternative to the internal starter repo or proprietary distro many of us have accumulated over the years. The ability to kick off a site with a solid, curated foundation - and then own it completely from that point - addresses a real friction point in the current workflow.

And for the marketplace use case - small businesses, hobbyists, the lower end of the funnel that Drupal CMS is deliberately targeting - site templates are genuinely the right tool. The composability and the clean handoff model are exactly what that audience needs.

Recipes and site templates don't kill distributions. They just make it possible to get most of the benefits without most of the pain.