The Gatsby ecosystem is prosperous with plugins and themes, which I love, but sometimes it becomes a problem when trying to assemble all the pieces to achieve your goal.
For a long time, proper documentation was the solution, but it is hard to keep up to date and copy-pasting commands into your terminal without understanding what they do. It becomes a tedious process.
Wouldn't it be nice if you could make the setup instructions more interactive? Where people can read through it and set up their projects at the same time.
Enter: Gatsbyjs Recipes
Gatsbyjs Recipes are run from the CLI and automate common tasks like creating pages and layouts, installing and setting up plugins, adding a blog to a site, setting up Typescript, and many more.With the release of this new feature, Gatsby has created 11 official recipes that you can explore, including ThemeUI, Sass, Cypress, animated page transitions, and persistent layout components.
What is a Gatsby recipe?
Recipes are written in MDX—a combination of Markdown and React components—readable by both humans and machines. (Other "infrastructure as code" automation, like AWS CloudFormation, use kinda-sorta legible YAML templates that favor the machines).
MDX is a great choice here because it makes Gatsby Recipes instructions and explanations easily readable for humans while using React components syntax to declare to Gatsby Recipes the desired state of the world.
Set up Gatsby to use Recipes
To be able to use recipes, you need to install the latest gatsby-cli yarn global add gatsby-cli@latest. Also, make sure to upgrade your project to use the latest gatsby by running the command yarn upgrade --latest.
To test if everything is working as expected, run gatsby recipes, and you should see a list of the official recipes.
Install NPM packages Using a Gatsby Recipe
To create a recipe, we need first to create an MDX file. You can create it anywhere. It doesn't need to be part of a Gatsby project.Let's take setting up tailwindcss with Gatsby as an example.Create a file called tailwindcss.mdx
# Setup Gatsby with tailwindcss
[Tailwindcss](https://tailwindcss.com/) Tailwind CSS is a highly customizable, low-level CSS framework that gives you all of the building blocks you need to build bespoke designs without any annoying opinionated styles you have to fight to override.
--------
Install npm packages
<NPMPackage name="tailwindcss"/>
We started with a Head and some text to explain what the recipe does and using --- we mark the beginning of a new Step.Using the NPMPackage block, we tell Gatsby that it's time to install a dependency.
Add a Gatsby Plugin using a Gatsbyjs Recipe
To add a gatsby plugin using a recipe, you need to use both the NPMPackage block with the GatsbyPlugin block.Our tailwindcss.mdx file looks like this.
# Setup Gatsby with tailwind
[Tailwindcss](https://tailwindcss.com/) Tailwind CSS is a highly customizable, low-level CSS framework that gives you all of the building blocks you need to build bespoke designs without any annoying opinionated styles you have to fight to override.
--------
Install npm packages
<NPMPackage name="tailwindcss"/>
--------
Add a Gatsby Plugin
<NPMPackage name="gatsby-plugin-postcss" />
<GatsbyPlugin name="gatsby-plugin-postcss" />
Add Files using a Gatsby Recipe.
You can also create files in your Gatsby project using recipes.In my case, I need to create 3 files:postcss.config.js to pass some configuration to postcsstailwind.css to import the tailwindcss componentsusingtailwind.js, a gatsby page to test if everything is workingUsing the File block, you can specify the path, where you want to create the file, and the content, which is usually a link to a gist with some text content.
Our tailwindcss.mdx file looks like this now.
# Setup Gatsby with tailwind
[Tailwindcss](https://tailwindcss.com/) Tailwind CSS is a highly customizable, low-level CSS framework that gives you all of the building blocks you need to build bespoke designs without any annoying opinionated styles you have to fight to override.
--------
Install npm packages
<NPMPackage name="tailwindcss"/>
--------
Add a Gatsby Plugin
<NPMPackage name="gatsby-plugin-postcss" />
<GatsbyPlugin name="gatsby-plugin-postcss" />
--------
Add some files
<File path="postcss.config.js" content="https://raw.githubusercontent.com/Khaledgarbaya/gatsby-tailwindcss-recipe/master/postcss.config.js"/>
<File
path="tailwind.config.js"
content="https://raw.githubusercontent.com/Khaledgarbaya/gatsby-tailwindcss-recipe/master/tailwind.config.js"
/>
<File
path="src/styles/tailwind.css"
content="https://raw.githubusercontent.com/Khaledgarbaya/gatsby-tailwindcss-recipe/master/src/styles/tailwind.css"
/>
<File
path="src/pages/usingtailwind.js"
content="https://raw.githubusercontent.com/Khaledgarbaya/gatsby-tailwindcss-recipe/master/src/pages/tailwind.js"
/>
--------
Done
Where to go from here
Make sure to check out the official blog post by Gatsby and visit the Umbrella issue if you want to contribute
Top comments (0)