feat(Gatsby Recipes): Initial release

packages/gatsby-cli/src/create-cli.js

@@ -293,6 +293,19 @@ function buildLocalCommands(cli, isLocalSite) {
       return cmd(args)
     }),
   })
+  cli.command({
+    command: `recipes`,
+    desc: `Run a recipe`,
+    handler: handlerP(
+      getCommandHandler(`recipes`, (args, cmd) => {
+        cmd(args)
+        // Return an empty promise to prevent handlerP from exiting early.
+        // The development server shouldn't ever exit until the user directly
+        // kills it so this is fine.
+        return new Promise(resolve => {})
+      })
+    ),
+  })
 }
 
 function isLocalGatsbySite() {

packages/gatsby/package.json

@@ -15,14 +15,22 @@
     "@babel/parser": "^7.8.8",
     "@babel/polyfill": "^7.8.7",
     "@babel/runtime": "^7.8.7",
+    "@babel/standalone": "^7.9.5",
     "@babel/traverse": "^7.8.6",
     "@hapi/joi": "^15.1.1",
+    "@mdx-js/mdx": "^1.5.8",
+    "@mdx-js/react": "^1.5.8",
+    "@mdx-js/runtime": "^1.5.8",
     "@mikaelkristiansson/domready": "^1.0.10",
     "@pieh/friendly-errors-webpack-plugin": "1.7.0-chalk-2",
     "@pmmmwh/react-refresh-webpack-plugin": "^0.2.0",
     "@reach/router": "^1.3.3",
     "@typescript-eslint/eslint-plugin": "^2.24.0",
     "@typescript-eslint/parser": "^2.24.0",
+    "@xstate/graph": "^1.0.0",
+    "@xstate/test": "^0.3.0",
+    "acorn": "^7.1.1",
+    "acorn-jsx": "^5.2.0",
     "address": "1.1.2",
     "autoprefixer": "^9.7.4",
     "axios": "^0.19.2",
@@ -64,6 +72,7 @@
     "eslint-plugin-react": "^7.19.0",
     "eslint-plugin-react-hooks": "^1.7.0",
     "event-source-polyfill": "^1.0.12",
+    "execa": "^4.0.0",
     "express": "^4.17.1",
     "express-graphql": "^0.9.0",
     "fast-levenshtein": "^2.0.6",
@@ -78,17 +87,29 @@
     "gatsby-plugin-page-creator": "^2.2.1",
     "gatsby-react-router-scroll": "^2.2.1",
     "gatsby-telemetry": "^1.2.3",
+    "git-diff": "^2.0.6",
     "glob": "^7.1.6",
     "got": "8.3.2",
     "graphql": "^14.6.0",
     "graphql-compose": "^6.3.8",
     "graphql-playground-middleware-express": "^1.7.12",
+    "graphql-subscriptions": "^1.1.0",
+    "graphql-type-json": "^0.3.1",
     "hasha": "^5.2.0",
+    "html-tag-names": "^1.1.5",
+    "humanize-list": "^1.0.1",
+    "import-jsx": "^4.0.0",
+    "ink-link": "^1.0.0",
     "invariant": "^2.2.4",
+    "is-blank": "^2.1.0",
+    "is-newline": "^1.0.0",
     "is-relative": "^1.0.0",
     "is-relative-url": "^3.0.0",
+    "is-string": "^1.0.5",
+    "is-url": "^1.2.4",
     "is-wsl": "^2.1.1",
     "jest-worker": "^24.9.0",
+    "joi2gql": "^1.3.1",
     "json-loader": "^0.5.7",
     "json-stringify-safe": "^5.0.1",
     "latest-version": "5.1.0",
@@ -110,6 +131,7 @@
     "p-defer": "^3.0.0",
     "parseurl": "^1.3.3",
     "physical-cpu-count": "^2.0.0",
+    "pkg-dir": "^4.2.0",
     "pnp-webpack-plugin": "^1.6.4",
     "postcss-flexbugs-fixes": "^4.2.0",
     "postcss-loader": "^3.0.0",
@@ -120,21 +142,31 @@
     "react-error-overlay": "^3.0.0",
     "react-hot-loader": "^4.12.20",
     "react-refresh": "^0.7.0",
+    "read-package-tree": "^5.3.1",
     "redux": "^4.0.5",
     "redux-thunk": "^2.3.0",
+    "remark-stringify": "^8.0.0",
     "semver": "^5.7.1",
     "shallow-compare": "^1.2.2",
     "sift": "^5.1.0",
     "signal-exit": "^3.0.2",
+    "simplified-jsx-to-json": "^0.1.0",
+    "single-trailing-newline": "^1.0.0",
     "slugify": "^1.4.0",
     "socket.io": "^2.3.0",
     "stack-trace": "^0.0.10",
     "string-similarity": "^1.2.2",
     "style-loader": "^0.23.1",
+    "style-to-object": "^0.3.0",
+    "subscriptions-transport-ws": "^0.9.16",
+    "svg-tag-names": "^2.0.1",
     "terser-webpack-plugin": "^1.4.3",
     "true-case-path": "^2.2.1",
     "type-of": "^2.0.1",
+    "unist-util-remove": "^2.0.0",
+    "unist-util-visit": "^2.0.2",
     "url-loader": "^1.1.2",
+    "urql": "^1.9.5",
     "util.promisify": "^1.0.1",
     "uuid": "^3.4.0",
     "v8-compile-cache": "^1.1.2",
@@ -144,6 +176,7 @@
     "webpack-hot-middleware": "^2.25.0",
     "webpack-merge": "^4.2.2",
     "webpack-stats-plugin": "^0.3.1",
+    "ws": "^7.2.3",
     "xstate": "^4.8.0",
     "yaml-loader": "^0.5.0"
   },
@@ -153,6 +186,7 @@
     "@types/hapi__joi": "^16.0.12",
     "@types/socket.io": "^2.1.4",
     "babel-preset-gatsby-package": "^0.3.1",
+    "copy-and-watch": "^0.1.4",
     "cross-env": "^5.2.1",
     "documentation": "^12.1.4",
     "eslint-plugin-jsx-a11y": "^6.2.3",
@@ -202,17 +236,21 @@
     "graphql": "^14.6.0"
   },
   "scripts": {
-    "build": "npm run build:src && npm run build:internal-plugins && npm run build:rawfiles && npm run build:cjs",
+    "build": "npm run build:src && npm run build:internal-plugins && npm run build:rawfiles && npm run build:cjs && npm run build:recipes",
     "postbuild": "node scripts/output-api-file.js",
     "build:internal-plugins": "copyfiles -u 1 src/internal-plugins/**/package.json dist",
     "build:rawfiles": "copyfiles -u 1 src/internal-plugins/**/raw_* dist",
+    "build:recipes": "copyfiles -u 1 src/recipes/*.mdx dist",
+    "watch:recipes": "copy-and-watch src/recipes/*.mdx dist/recipes",
     "build:cjs": "babel cache-dir --out-dir cache-dir/commonjs --ignore **/__tests__",
     "build:src": "babel src --out-dir dist --source-maps --verbose --ignore **/gatsby-cli.js,src/internal-plugins/dev-404-page/raw_dev-404-page.js,**/__tests__ --extensions \".ts,.js\"",
     "clean-test-bundles": "find test/ -type f -name bundle.js* -exec rm -rf {} +",
     "prebuild": "rimraf dist && rimraf cache-dir/commonjs",
     "postinstall": "node scripts/postinstall.js",
     "prepare": "cross-env NODE_ENV=production npm run build",
-    "watch": "rimraf dist && mkdir dist && npm run build:internal-plugins && npm run build:rawfiles && npm run build:src -- --watch"
+    "watch": "rimraf dist && mkdir dist && npm run build:internal-plugins && npm run build:rawfiles && npm run build:src -- --watch",
+    "test": "jest",
+    "test:watch": "jest --watch"
   },
   "types": "index.d.ts",
   "yargs": {

packages/gatsby/src/commands/recipes.ts

@@ -0,0 +1,45 @@
+import telemetry from "gatsby-telemetry"
+import execa from "execa"
+import path from "path"
+import fs from "fs"
+
+module.exports = async (program: IProgram): Promise<void> => {
+  const recipe = program._[1]
+  telemetry.trackCli(`RECIPE_RUN`, { recipe })
+
+  // Start GraphQL serve
+  let subprocess
+  const scriptPath = path.join(
+    program.directory,
+    `node_modules/gatsby/dist/recipes/graphql.js`
+  )
+  subprocess = execa(`node`, [scriptPath], {
+    cwd: program.directory,
+    all: true,
+  })
+  subprocess.stderr.on("data", data => {
+    console.log(data.toString())
+  })
+  process.on("exit", () =>
+    subprocess.kill("SIGTERM", {
+      forceKillAfterTimeout: 2000,
+    })
+  )
+  // Log server output to a file.
+  if (process.env.DEBUG) {
+    const logFile = path.join(program.directory, "./recipe-server.log")
+    fs.writeFileSync(logFile, `\n-----\n${new Date().toJSON()}\n`)
+    const writeStream = fs.createWriteStream(logFile, { flags: "a" })
+    subprocess.stdout.pipe(writeStream)
+  }
+
+  let started = false
+  subprocess.stdout.on("data", data => {
+    if (!started) {
+      const runRecipe = require(`../recipes/index`)
+      runRecipe({ recipe, projectRoot: program.directory })
+      started = true
+    }
+  })
+  // Run command
+}

packages/gatsby/src/recipes/README.md

@@ -0,0 +1,137 @@
+# Gatsby Recipes
+
+Gatsby Recipes is framework for automating common Gatsby tasks. Recipes are MDX
+files which when run by our interpretor, 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 RFC](https://github.com/gatsbyjs/gatsby/pull/22610)
+
+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
+
+## How to write a recipe
+
+Let's write our first Recipe to setup Emotion on a Gatsby site.
+
+```mdx
+# 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.
+
+---
+
+Install necessary NPM packages
+
+<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
+```
+
+Let's try running out this Recipe!
+
+First create a new Hello World Gatsby site:
+
+`gatsby new try-emotion https://github.com/gatsbyjs/gatsby-starter-hello-world`
+
+Meanwhile also upgrade the global gatsby-cli package to use the one with new recipes command.
+
+`npm install -g gatsby-cli@recipes`
+
+Once the global finishes installing, running `gatsby -v` should show this as your version: `Gatsby CLI version: 2.11.4-recipes.53`
+
+Upgrade the version of Gatsby installed to use one with Recipes.
+
+`yarn add gatsby@recipes`
+
+Now run the Emotion recipe and follow the commands.
+
+`gatsby recipes emotion`
+
+## Ways 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 `gatsby recipes ./my-cool-recipe.mdx`
+
+To run a remote recipe, just paste in the path to the recipe e.g. `gatsby recipes https://example.com/sweet-recipe.mdx`
+
+## How to write your own
+
+### API
+
+#### `<GatsbyPlugin>`
+
+Installs a Gatsby Plugin in the site's `gatsby-config.js`.
+
+Soon will support options.
+
+```jsx
+<GatsbyPlugin name="gatsby-plugin-emotion" />
+```
+
+##### props
+
+- **name** name of the plugin
+
+#### `<NPMPackage`
+
+`<NPMPackage name="lodash" version="latest" />`
+
+##### props
+
+- **name**: name of the package(s) to install. Takes a string or an array of strings.
+- **version**: defaults to latest
+- **dependencyType**: defaults to `dependency`. Other options include `devDependency`
+
+#### `<NPMScript>`
+
+`<NPMScript name="test" command="jest" />`
+
+##### props
+
+- **name:** name of the command
+- **command** the command that's run when the script is called
+
+#### `<File>`
+
+<File path="test.md" content="https://raw.githubusercontent.com/KyleAMathews/test-recipes/master/gatsby-receipe-sass.mdx" />
+
+##### 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 fixees to MDX.