This is the Hydrogen Cookbook, a collection of example recipes to showcase specific scenarios and usecases for Hydrogen projects.
A recipe is a reproducible sequence of steps meant to be applied to the skeleton template.
Each recipe is located in the cookbook's recipes folder and is structured with a specific set of conventions. This is how a recipe folder is organized:
recipe.yaml: the JSON file containig the whole recipe definition, in a machine-readable format.ingredients/: a folder containing new files that the recipe introduces. They will be copied as-is to the skeleton template.patches/: a folder containing patches to be applied to existing files in the skeleton template. The file ↔ patch mappings are defined in therecipe.yamlfile under theingredientskey.README.md: the human-readable Markdown render of the recipe, based off of therecipe.yamlfile.
The cookbook comes with a set of commands for creating and managing recipes. All commands are managed by the main cookbook.ts script, which can be invoked from this folder with npm run cookbook.
cookbook.ts <command>
Commands:
cookbook.ts generate Generate a recipe from the skeleton's changes
cookbook.ts render Render a recipe to a given format
cookbook.ts apply Apply a recipe to the current project
cookbook.ts validate Validate a recipe
cookbook.ts regenerate Regenerate a recipe
cookbook.ts update Update a recipe
Options:
--version Show version number [boolean]
--help Show help [boolean]
apply takes a given recipe and applies its steps against the skeleton template.
cookbook.ts apply
Apply a recipe to the current project
Options:
--version Show version number [boolean]
--help Show help [boolean]
--recipe The name of the recipe to apply [string] [required]
npm run cookbook -- apply --recipe my-recipegenerate will build a recipe folder based on the current changes made to the skeleton template, effectively snapshotting its state into a reproducible recipe.
The workflow for creating a new recipe is as follows:
- Make the desired changes to the skeleton template
- (Optional) Mark relevant portions of the code with
@descriptioncomments describing what the changes are doing - Run the
generatecommand with the recipe name - (Optional) Adjust the
recipe.yamloutput as desired, filling in potential missing information (e.g. the recipe title and description)
cookbook.ts generate
Generate a recipe from the skeleton's changes
Options:
--version Show version number [boolean]
--help Show help [boolean]
--recipe The name of the recipe to generate
[string] [required]
--onlyFiles Only generate the files for the recipe, not the
recipe.yaml file. [boolean]
--referenceBranch The reference branch to use for the recipe
[string] [default: "origin/main"]
npm run cookbook -- generate --recipe my-recipevalidate makes sure that a given recipe is valid.
When running it, validate will:
- Make sure the recipe's JSON file is well-formed
- Make sure the ingredients are consistent
- Apply the recipe
- Install the recipe dependencies
- Typecheck the template
- Build the template
If any of these steps fails, the command will terminate with a non-zero exit status.
If no recipe name is provided, all recipes will be validated.
cookbook.ts validate
Validate a recipe
Options:
--version Show version number [boolean]
--help Show help [boolean]
--recipe The name of the recipe to validate. If not provided,
all recipes will be validated. [string]
npm run cookbook -- validate --recipe my-reciperender takes a recipe and produces a Markdown-based readable version from it, with variants based on the chosen format: github, for GH-flavored syntax, and shopify.dev for the shopify.dev variant.
cookbook.ts render
Render a recipe to a given format
Options:
--version Show version number [boolean]
--help Show help [boolean]
--recipe The name of the recipe to render [string] [required]
--format The format to render the recipe in
[string] [required] [choices: "github", "shopify.dev"]
npm run cookbook -- render --recipe my-recipe --format githubregenerate will apply in sequence: apply, generate, and render.
If no recipe name is provided, all recipes will be regenerated.
This command provides a convenient shorthand to refresh all recipes, particularly useful when cookbook scripts have been modified or enhanced in how they represent output files.
By applying changes across all existing recipes at once, it ensures that every recipe follows the latest implementation of the recipe format.
cookbook.ts regenerate
Regenerate a recipe
Options:
--version Show version number [boolean]
--help Show help [boolean]
--recipe The name of the recipe to regenerate. If not provided, all
recipes will be regenerated. [string]
--onlyFiles Only generate the files for the recipe, not the recipe.yaml
file. [boolean]
--format The format to render the recipe in
[string] [required] [choices: "github", "shopify.dev"]
--referenceBranch The reference branch to use for the recipe
[string] [default: "origin/main"]
npm run cookbook -- regenerate --recipe my-recipe --format githubupdate will try to update the given recipe to match the HEAD of the main branch and remain applicable.
In case of conflicting changes, update will prompt the user to resolve them, reconciling the recipe and saving the changes.
cookbook.ts update
Update a recipe
Options:
--version Show version number [boolean]
--help Show help [boolean]
--recipe The name of the recipe to update [string] [required]
--referenceBranch The branch to update the recipe from
[string] [default: "origin/main"]
npm run cookbook -- update --recipe my-recipeschema will regenerate the JSON schema for the recipe manifest file off of the Zod schema definition.
cookbook.ts schema
Render the recipe JSON schema out of the Recipe type.
Options:
--version Show version number [boolean]
--help Show help [boolean]
npm run cookbook -- schema