A guide to Gatsby recipes

In this article, we will be looking at an automated version of Gatsby recipes, a tool used to automate site-building tasks into a single command.

What are Gatsby recipes?

In the official Gatsby documentation, recipes offer a medium between watching full-length tutorials and crawling the docs.

Recipes were created for developers to be able to do things like adding a specific package or plugin to your Gatsby project without the pain of doing a full tutorial just to figure out one task. Before the automation of this process, the documentation offered a list of valuable information on handling quick tasks.

Automating Gatsby recipes

With the last few advancements in Gatsby, such as incremental builds — which is available on Gatsby Cloud, Gatsby released a canary version of recipes built with MDX and React. The MDX component turns a list of steps into files which, when run by an interpreter, perform common actions like installing NPM packages, installing plugins, and creating pages. Anything can be a recipe as processes are designed to be extensible which allows recipes to automate more things.

The option of using MDX to write recipes allows for more understandable syntax. This aids in the process of porting a recipe from the list of recipes in the documentation to a single command as well as any tutorials in the future.

Prerequisite

To use the gatsby recipes Gatsby requires a few settings:

• Upgrade your global gatsby-cli package to the latest by running npm install -g gatsby-cli@latest in the terminal. To confirm that this worked, run gatsby --help in your terminal. The output should show the recipes command.

Gatsby recipes originally shipped with eleven recipes out of the box. These include recipes for adding TypeScript, ThemeUI, Sass, Cypress, and setting up useful techniques like animated page transitions, and persistent layout components.

Since it is encouraged to add more recipes to the list from the original launch, the available recipes list has increased.

Let us take a look at how to create our own recipe.

Creating your own recipe

The idea for recipes is to allow Gatsby users to automate processes on their own, to this effect a few MDX components exist so that this can be possible and can be done in a GitHub gist or with an MDX file locally.

Gatsby offers a few components that are used to create custom recipes. Some of these components accept some props, you can see this list of components in this issue on GitHub.

In this article, we will be making use of three of these components, <GatsbyPlugin/>, <NPMPackage /> and <File />:

• Gatsby-plugin component (<GatsbyPlugin/>) is used to install a Gatsby plugin in the site’s gatsby-config.js. It accepts a name which is the name of the plugin, a list of options which are plugin declaration to specify processes, and a key prop used to distinguish between multiple plugin instance

Note: JavaScript code is not yet supported in options. Right now, it is strings only while this feature is experimental.

• NPM-package component (<NPMPackage/>) is used to install packages in the list of commands. It takes a prop of name which is the name of the package(s) to install
• File component (<File/>) is used to add example files to show implementation of the packages and plugins installed. It takes a prop of content that points to the file directory

An example of a recipe

With the information you have gotten from the previous section you can proceed to creating a recipe of your own. In this example, we will be looking at creating a recipe to add gatsby-image to a project.

The image below shows what the final product looks like on a GitHub gist:

If you take a look at the Gatsby documentation for adding gatsby image to a project you will notice that the steps require you to install the following npm packages: gatsby-image, gatsby-transformer-sharp, and gatsby-plugin-sharp.

You may need to include gatsby-transformer-sharp and gatsby-plugin-sharp depending on the gatsby starter you used.

After installing these packages you will also need to make sure they are installed and included in your gatsby-config.

You automate the first two processes in a recipe by doing this:

---

Install necessary NPM packages

<NPMPackage name="gatsby-image" />
<NPMPackage name="gatsby-transformer-sharp" />
<NPMPackage name="gatsby-plugin-sharp" />
<NPMPackage name="gatsby-source-filesystem" />

---

Use three dashes to separate steps of the recipe.

You will use the <GatsbyPlugin /> component to add the plugin into the gatsby-config.js file. Seeing as gatsby-source-filesystem accepts keys and options as props we will include it like this:

Install the gatsby-source-filesystem plugin in gatsby-config.js replace path with ${__dirname}/src/data/:<GatsbyPlugin
  name="gatsby-source-filesystem"
  key="src/pages"
  options={{
    name: `src pages directory`,
    path: `src/images`,
  }}
/>

<GatsbyPlugin name="gatsby-plugin-sharp" />
<GatsbyPlugin name="gatsby-transformer-sharp" />

<GatsbyPlugin> doesn’t support adding options with JavaScript yet so you can leave a note in the step.

The next step in the documentation is suggested and it involves adding an example file. You can do this by using the <File/> component:

<File
content="https://gist.githubusercontent.com/Ekwuno/5fd77d9a58dd4305eb9e470b884190a3/raw/d7d6c4afc4411d72974b46137c83eb7131aba8b6/index.js"
path="src/pages/index.js"
/>

To link the example file to the main file In the GitHub gist we can do this by using the URL of the raw file and linking this in the content props.

We can call this file index.js :

import React from "react"
import { graphql } from "gatsby"
import Img from "gatsby-image"

export default ({ data }) => (
  <div>
    <h1>Hello gatsby-image</h1>
    <Img fixed={data.file.childImageSharp.fixed} />
  </div>
)

export const query = graphql`
  query {
    file(relativePath: { eq: "blog/avatars/Image.jpeg" }) {
      childImageSharp {
        # Specify the image processing specifications right in the query.
        # Makes it trivial to update as your page's design changes.
        fixed(width: 125, height: 125) {
          ...GatsbyImageSharpFixed
        }
      }
    }
  }
`

Here is a link to a final product of the gist.

Conclusion

In this blog post, you have seen what a Gatsby recipe is and how you can create your own. The importance of automating the process comes from the need to make our lives as developers easier. As this feature unfolds (it is currently experimental) I am positive that the process of creating custom recipes will become easier. The possibilities of building with Gatsby are endless. Happy coding 😄.

---

Over 200k developers use LogRocket to create better digital experiences

Learn more →

---