Core functionality for Gatsby Recipes
$ npm install 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
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
<NPMPackageJson>
<NPMPackageJson
name="lint-staged"
value={{
"src/**/*.js": [
"jest --findRelatedTests"
],
}}
/>
<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.
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