One thing the documentation lacks is an explicit explanation of why recipes all need to be in the same directory (with the exception of core recipes). We really need to add that, since it's a significant difference from the way modules and themes work and trips people up if they don't understand the background or rationale behind the decision.
Draft
## Recipe location
Except for core recipes (located at `core/recipes`), all recipes on a given site must be in a single directory. This requirement is a key design feature of the recipe system and distinguishes it from, for example, the way that Drupal extensions (modules, themes) are managed and recognized on the file system.
Why?
A key reason is that recipes are ephemeral. They're not part of an architecture and so don't need to be carefully calibrated and balanced to interact with other elements. Instead, they're applied once, possibly reapplied, but they don't live on the site. There's no need, for example, for the complex set of overrides that apply in the extension case, where a contrib module overrides core one of the same name, only to be overridden in turn by a site-specific version.
Plus, Composer. It just makes sense to rely on it as a source of truth. Most Drupal site owners will never have to worry about where to put recipes. Composer will handle everything as needed.
If in doubt about where recipes are installed, look for the `installer-paths` section of your root `composer.json` file. If you used `drupal/recommended-project` to spin up your site, that line might look like:
```json
"recipes/{$name}": ["type:drupal-recipe"]
```
Meaning that, if other package types like modules and themes are installed to some subdirectory of `web`, composer will install recipes to a `recipes` directory one up from the web root. That's where any other recipes you might want to add will go too.
### How do you add your own custom recipes?
The first question should be, do you really need to? Again, it's important not to be distracted by a potentially misleading analogy with extensions. While there are indeed use cases for installing a custom module or theme on a given site, given recipes are something you apply once and are done with, a site-specific recipe that you want to keep around is pretty much a contradiction in terms.
That said, there will indeed be use cases for custom recipes. For example, there might be a set of recipes that you want to build out and use on a number of sites but not share with the world. You can maintain these in any of a number of ways:
* Commit your recipe to version control and add it to an internal Composer package. There are [several repository types that Composer supports](https://getcomposer.org/doc/05-repositories.md) which can accommodate this use case.
* Put your recipe wherever you like and then symlink it into the recipes directory.
* Commit your recipe directly to the recipes directory.
### What about dev environments and testing?
If you're developing recipes, you may have specific needs when it comes to linking in a recipe. For example, if you're using [DDEV Drupal Contrib](https://github.com/ddev/ddev-drupal-contrib), you may need to [change the symlink location](https://github.com/ddev/ddev-drupal-contrib?tab=readme-ov-file#changing-...).
Issue fork distributions_recipes-3539469
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
Comments
Comment #2
star-szrI could really use even a short explanation for this, because I'm confused.
From my understanding the intended setup is to configure composer to add recipes to /recipes. This means /recipes will need to be ignored by git. So what about custom recipes? Where should those go? One option that would align with other conventions would be to split /recipes into /recipes/contrib and /recipes/custom, but that would of course not be in the same directory. Is there an intended development workflow for custom recipes?
Comment #3
phenaproximaThat's a good question and it deserves an explanation.
The thing about a recipe, in general, is that you're not supposed to keep them around the way you do with modules and themes. The unpacking plugin underscores this point. You should require a recipe, apply it, and then just delete it.
Think of it like a real-life recipe for making food; once you've made the food, you don't need the recipe anymore.
So, "custom recipes" are not really a thing the way custom modules and themes are. A "custom recipe" has no purpose; just make the desired changes to your site, then export config.
If you have special recipes you're creating for internal purposes, that you want to reuse within a codebase, you could add them to Git. That would make sense and would not be a bad practice at all. Or, if you wanted to reuse those recipes in multiple codebases without distributing them to the world, you could make them Composer packages that you serve from some kind of internal repository (there are several repository types that Composer supports which can accommodate this use case).
Another thing some people do is use recipes as a way to deploy content from local to production. It's hacky, and the default content system is not designed for it so it's a bit of a "I hereby void my warranty" situation, but if you really need to, you could create a special one-off recipe for that which you commit to Git in the
recipesdirectory.So, to summarize:
In light of all that, there's no real reason to gitignore the recipes directory.
I hope that helps, and makes sense. At least, this was the intention in the way the recipe system is designed.
Comment #4
star-szrThat's really helpful context, thank you @phenaproxima!
Comment #6
nedjoRoughing in some verbiage in the issue summary for review.
Comment #7
thejimbirch commented