Gatsby Recipes

Recipes is an “infrastructure as code” system that lets users automatically manage and provision the technology stack for their Gatsby site/app through code rather than manual processes.

It’s powered by React & MDX and a useful analogy is “React Native for Infrastructure”.

Recipes also provides a read/write API for Desktop/Admin to build lowcode tooling on top of Gatsby & integrated services.

It's designed to be extensible so new capabilities can be added which allow Recipes to automate more things.

We chose MDX to allow for a literate programming style of writing recipes which enables us to port our dozens of recipes from https://www.gatsbyjs.org/docs/recipes/ as well as in the future, entire tutorials.

Read more about Recipes on the launch blog post

There's an umbrella issue for testing / using Recipes during its incubation stage. Follow the issue for updates! https://github.com/gatsbyjs/gatsby/issues/22991

Get set up for running Recipes

Recipes is a new rapidly developing feature. To use it, upgrade your global gatsby-cli package to the latest.

1npm install -g gatsby-cli@latest

To confirm that this worked, run gatsby --help in your terminal. The output should show the recipes command.

Running an example recipe

Now you can test out recipes! Start with a recipe for installing Emotion by following these steps:

1. Create a new Hello World Gatsby site:

1gatsby new try-emotion https://github.com/gatsbyjs/gatsby-starter-hello-world

1. Go to the project directory you created:

1cd try-emotion

1. Now you can run the emotion recipe with this command:

1gatsby recipes emotion

You can see a list of other recipes to run by running gatsby recipes

Developing Recipes

An example MDX recipe

Here's how you would write the gatsby recipes emotion recipe you just ran:

1# Setup Gatsby with Emotion
2
3[Emotion](https://emotion.sh/) is a powerful CSS-in-JS library that supports both inline CSS styles and styled components. You can use each styling feature individually or together in the same file.
4
5<!-- use three dashes to separate steps of the recipe -->
6
7---
8
9Install necessary NPM packages
10
11<!-- refer to the API in this doc to see what APIs are available, like `NPMPackage` -->
12
13<NPMPackage name="gatsby-plugin-emotion" />
14<NPMPackage name="@emotion/react" />
15<NPMPackage name="@emotion/styled" />
16
17---
18
19Install the Emotion plugin in gatsby-config.js
20
21<GatsbyPlugin name="gatsby-plugin-emotion" />
22
23---
24
25Sweet, now it's ready to go.
26
27Let's also write out an example page you can use to play
28with Emotion.
29
30<File
31  path="src/pages/emotion-example.js"
32  content="https://gist.githubusercontent.com/KyleAMathews/323bacd551df46e8e7b6146cbf827d0b/raw/5c60f168f30c505cff1ff2433e69dabe27ae9738/sample-emotion.js"
33/>
34
35---
36
37Read more about Emotion on the official Emotion docs site:
38
39https://emotion.sh/docs/introduction

You can browse the source of the official recipes. The recipes umbrella issue also has a number of recipes posted by community members.

How to run recipes

You can run built-in recipes, ones you write locally, and ones people have posted online.

To run a local recipe, make sure to start the path to the recipe with a period like:

1gatsby recipes ./my-cool-recipe.mdx

To run a remote recipe, copy the path to the recipe and run it e.g.

1gatsby recipes https://example.com/sweet-recipe.mdx

External learning resources

• A free 6 min eggheadio collection by Khaled Garbaya

Recipe API

<GatsbyPlugin>

Installs a Gatsby Plugin in the site's gatsby-config.js.

1<GatsbyPlugin
2  name="gatsby-source-filesystem"
3  key="src/pages"
4  options={{
5    name: `src pages directory`,
6    path: `src/pages`,
7  }}
8/>

props

• name: name of the plugin
• options: object with options to be added to the plugin declaration in gatsby-config.js. JavaScript code is not yet supported in options e.g. process.env.API_TOKEN. This is being worked on. For now only simple values like strings and numbers are supported.
• key: string used to distinguish between multiple plugin instances
• isLocal: boolean that indicates this is a local plugin. This lets recipes know it shouldn't require an NPMPackage with the plugin name to be installed as well.

<GatsbyShadowFile>

1<GatsbyShadowFile theme="gatsby-theme-blog" path="src/components/seo.js" />

props

• theme: the name of the theme (or plugin) which provides the file you'd like to shadow
• path: the path to the file within the theme. E.g. the example file above lives at node_modules/gatsby-theme-blog/src/components/seo.js

<NPMPackage>

1<NPMPackage name="lodash" version="latest" />

props

• name: name of the package to install
• version: defaults to latest
• dependencyType: defaults to production. Other options include development

<NPMPackageJson>

1<NPMPackageJson
2  name="lint-staged"
3  value={{
4     "src/**/*.js": [
5      "jest --findRelatedTests"
6    ],
7  }}
8/>

props

• name: name of the property to add to the package.json
• value: the value assigned to the property. can be an object or a string.

<NPMScript>

1<NPMScript name="test" command="jest" />

props

• name: name of the command
• command: the command that's run when the script is called

<File>

1<File
2  path="test.md"
3  content="https://raw.githubusercontent.com/KyleAMathews/test-recipes/master/gatsby-recipe-jest.mdx"
4/>

props

• path: path to the file that should be created. The path is local to the root of the Node.js project (where the package.json is)
• content: URL to the content that should be written to the path. Eventually we'll support directly putting content here after some fixes to MDX.

Note that this content is stored in a GitHub gist. When linking to a gist you'll want to click on the "Raw" button and copy the URL from that page.

<Directory>

1<Directory path="test" />

props

• path: path to the directory that should be created. The path is local to the root of the Node.js project (where the package.json is)

How to set up your development environment to work on Gatsby Recipes core

The Gatsby recipes codebase consists of the core framework, code for each resource, and the MDX source.

Official recipes

MDX source for the official recipes lives at https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-recipes/recipes.

We welcome PRs for new recipes and fixes/improvements to existing recipes.

When you add a new recipe, please also add it to the recipes list at https://github.com/gatsbyjs/gatsby/blob/05151c006974b7636b00f0cd608fac89ddaa1c08/packages/gatsby-recipes/src/cli.js#L60.

FAQ / common issues

Q) My recipe is combining steps instead of running them separately!

We use the --- break syntax from Markdown to separate steps.

One quirk with it is for it to work, it must have an empty line above it.

So this will work:

1# Recipes
2
3---
4
5a step
6
7<File src="something.txt" content="something" />

But this won't

1# Recipes
2---
3
4a step
5
6<File src="something.txt" content="something" />

Q) What kind of recipe should I write?

If you’d like to write a recipe, there are a few great places to get an idea:

• Think of a task that took you more time than other tasks in the last Gatsby site you built. Is there a way to automate any part of that task?
• Look at this list of recipes in the Gatsby docs. Many of these can be partially or fully automated through creating a recipe mdx file. https://www.gatsbyjs.org/docs/recipes/
• community members have posted a number of recipes in the recipes umbrella issue. You can browse their ideas to find inspiration for new recipes to write.