Core functionality for Gatsby Recipes
$ npm install gatsby-recipes
Gatsby Recipes is framework for automating common Gatsby tasks. Recipes are MDX files which, when run by our interpreter, perform common actions like installing NPM packages, installing plugins, creating pages, etc.
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
Recipes is a new rapidly developing feature. To use it, upgrade your global gatsby-cli package to the latest.
npm install -g gatsby-cli@latest
To confirm that this worked, run gatsby --help
in your terminal. The output should show the recipes command.
Now you can test out recipes! Start with a recipe for installing Emotion by following these steps:
gatsby new try-emotion https://github.com/gatsbyjs/gatsby-starter-hello-world
cd try-emotion
emotion
recipe with this command:gatsby recipes emotion
You can see a list of other recipes to run by running gatsby recipes
Here's how you would write the gatsby recipes emotion
recipe you just ran:
# Setup Gatsby with Emotion
[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.
<!-- use three dashes to separate steps of the recipe -->
---
Install necessary NPM packages
<!-- refer to the API in this doc to see what APIs are available, like `NPMPackage` -->
<NPMPackage name="gatsby-plugin-emotion" />
<NPMPackage name="@emotion/core" />
<NPMPackage name="@emotion/styled" />
---
Install the Emotion plugin in gatsby-config.js
<GatsbyPlugin name="gatsby-plugin-emotion" />
---
Sweet, now it's ready to go.
Let's also write out an example page you can use to play
with Emotion.
<File
path="src/pages/emotion-example.js"
content="https://gist.githubusercontent.com/KyleAMathews/323bacd551df46e8e7b6146cbf827d0b/raw/5c60f168f30c505cff1ff2433e69dabe27ae9738/sample-emotion.js"
/>
---
Read more about Emotion on the official Emotion docs site:
https://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.
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:
gatsby recipes ./my-cool-recipe.mdx
To run a remote recipe, copy the path to the recipe and run it e.g.
gatsby recipes https://example.com/sweet-recipe.mdx
<GatsbyPlugin>
Installs a Gatsby Plugin in the site's gatsby-config.js
.
<GatsbyPlugin
name="gatsby-source-filesystem"
key="src/pages"
options={{
name: `src pages directory`,
path: `src/pages`,
}}
/>
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.<GatsbyShadowFile>
<GatsbyShadowFile theme="gatsby-theme-blog" path="src/components/seo.js" />
node_modules/gatsby-theme-blog/src/components/seo.js
<NPMPackage>
<NPMPackage name="lodash" version="latest" />
production
. Other options include development
<NPMScript>
<NPMScript name="test" command="jest" />
<File>
<File
path="test.md"
content="https://raw.githubusercontent.com/KyleAMathews/test-recipes/master/gatsby-recipe-jest.mdx"
/>
package.json
is)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>
<Directory path="test" />
package.json
is)The Gatsby recipes codebase consists of the core framework, code for each resource, and the MDX source.
First follow the instructions on setting up a local Gatsby dev environment.
If you want to fix a bug in a resource or extend it in some way, typically you'll be working against the tests for that resource.
In your terminal, start a jest watch process against the resource you're working on e.g. for GatsbyPlugin:
GATSBY_RECIPES_NO_COLOR=true jest --testPathPattern "src/.*plugin.test" --watch
You can create test recipes that you run in a test site. You'll need to use gatsby-dev-cli
for this..
One note, as you'll be testing changes to the Gatsby CLI — instead of running the global gatsby-cli package (i.e. what you'd
run by typing gatsby
, you'll want to run the version copied over by gatsby-dev-cli
by running ./node_modules/.bin/gatsby
.
When debugging the CLI, you may run into errors without stacktraces. In order to work around that, you can use the node inspector:
DEBUG=true node --inspect-brk ./node_modules/.bin/gatsby recipes ./test.mdx
Then, open up Chrome and click the node icon in dev tools.
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.
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:
# Recipes
---
a step
<File src="something.txt" content="something" />
But this won't
# Recipes
---
a step
<File src="something.txt" content="something" />
If you’d like to write a recipe, there are a few great places to get an idea:
mdx
file. https://www.gatsbyjs.org/docs/recipes/© 2010 - cnpmjs.org x YWFE | Home | YWFE