chore: add starters to monorepo (#10310)

This PR adds in starters to the monorepo. Longer term, I believe we'll merge starters/examples since they're very much linked.

Future implementation improvements:

- Run a `build` script to validate that the starter(s) can be built
  - I planned to use `lerna run --scope gatsby-starter-*` for this, but if there's another approach, happy to try that
- Implement yarn workspaces/lerna so we can get automatic versioning in the starters (I have this built out at https://github.com/dschau/starters)
- Author `e2e` tests vs. the starters so that we can ensure we're not breaking anything
  - These would follow a similar approach to the current e2e tests

Blocked by

gatsbyjs/gatsby-starter-blog#139 gatsbyjs/gatsby-starter-default#120 gatsbyjs/gatsby-starter-hello-world#32

Author: DSchau

.circleci/config.yml

@@ -161,6 +161,20 @@ jobs:
       - e2e-test:
           test_path: e2e-tests/production-runtime
 
+  starters_publish:
+    executor: node
+    steps:
+      - checkout
+      - <<: *restore_cache
+      - <<: *install_node_modules
+      - <<: *persist_cache
+      - run: ./scripts/assert-changed-files.sh "starters/*"
+      - run: yarn markdown
+      - run: sudo apt-get update && sudo apt-get install jq # jq is helpful for parsing json
+      - run: git config --global user.name "GatsbyJS Bot"
+      - run: git config --global user.email "[email protected]"
+      - run: sh ./scripts/clone-folder.sh starters
+
 workflows:
   version: 2
   build-test:
@@ -189,3 +203,8 @@ workflows:
           <<: *e2e-test-workflow
       - e2e_tests_runtime:
           <<: *e2e-test-workflow
+      - starters_publish:
+          filters:
+            branches:
+              only:
+                - master

.eslintrc.json

@@ -24,7 +24,8 @@
     "jest": true
   },
   "globals": {
-    "spyOn": true
+    "spyOn": true,
+    "__PATH_PREFIX__": true
   },
   "rules": {
     "arrow-body-style": [

.gitignore

@@ -50,6 +50,12 @@ node_modules/
 .vscode/
 *.sw*
 
+# misc
 .serverless/
+
+# lock files
 yarn.lock
 package-lock.json
+
+# starters are special; we want to persist the lock files
+!starters/*/package-lock.json

lerna.json

@@ -12,7 +12,9 @@
     }
   },
   "loglevel": "success",
-  "packages": ["packages/*"],
+  "packages": [
+    "packages/*"
+  ],
   "version": "independent",
   "npmClient": "yarn",
   "registry": "https://registry.npmjs.org/",

markdown.config.js

@@ -0,0 +1,45 @@
+const fs = require(`fs-extra`)
+const path = require(`path`)
+const _ = require(`lodash`)
+
+module.exports = {
+  transforms: {
+    LIST_STARTERS() {
+      const base = path.join(process.cwd(), `starters`)
+      const starters = fs
+        .readdirSync(base)
+        .filter(dir => fs.statSync(path.join(base, dir)).isDirectory())
+        .reduce((merged, dir) => {
+          merged[dir] = JSON.parse(
+            fs.readFileSync(path.join(base, dir, `package.json`), `utf8`)
+          )
+          return merged
+        }, {})
+
+      return `
+        |Name|Demo|Description|
+        |:--:|----|-----------|
+        ${Object.keys(starters)
+          .map(name => {
+            const starter = starters[name]
+            return `
+            |[${name}](https://github.com/gatsbyjs/gatsby-starter-${name})|[gatsby-starter-${name}-demo.netlify.com](https://gatsby-starter-${name}-demo.netlify.com/)|${
+              starter.description
+            }|
+          `.trim()
+          })
+          .join(`\n`)}
+      `.replace(/^[^|]+/gm, ``)
+    },
+    STARTER(content, options, { originalPath }) {
+      const starter = path.basename(path.dirname(originalPath))
+      const template = fs.readFileSync(
+        path.join(process.cwd(), `starters`, `README-template.md`),
+        `utf8`
+      )
+      return _.template(template)({
+        name: starter,
+      })
+    },
+  },
+}

package.json

@@ -26,6 +26,7 @@
     "jest-junit": "^5.0.0",
     "lerna": "^3.3.0",
     "lint-staged": "^8.0.4",
+    "markdown-magic": "^0.1.25",
     "npm-run-all": "4.1.5",
     "plop": "^1.8.1",
     "prettier": "^1.14.3",
@@ -73,6 +74,8 @@
     "lint:code": "eslint --ignore-path .gitignore --ignore-path .prettierignore --ext .js,.jsx .",
     "lint:flow": "babel-node scripts/flow-check.js",
     "lint:other": "npm run prettier -- --list-different",
+    "markdown": "md-magic --path \"starters/**/*.md\"",
+    "postmarkdown": "prettier --write \"starters/**/*.md\"",
     "plop": "plop",
     "prebootstrap": "yarn",
     "prettier": "prettier \"**/*.{md,css,scss,yaml,yml}\"",

scripts/clone-folder.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+FOLDER=$1
+BASE=$(pwd)
+
+for folder in $FOLDER/*; do
+  [ -d "$folder" ] || continue # only directories
+  cd $BASE
+
+  NAME=$(cat $folder/package.json | jq -r '.name')
+  CLONE_DIR="__${NAME}__clone__"
+
+  git clone --depth 1 https://$GITHUB_API_TOKEN@github.com/gatsbyjs/$NAME.git $CLONE_DIR
+  cd $CLONE_DIR
+  find . | grep -v ".git" | grep -v "^\.*$" | xargs rm -rf # delete all files (to handle deletions in monorepo)
+  cp -r $BASE/$folder/. . # copy all content
+  git add .
+  git commit --message "$(git log -1 --pretty=%B)"
+  git push origin master
+  cd $BASE
+done

starters/README-template.md

@@ -0,0 +1,94 @@
+<p align="center">
+  <a href="https://www.gatsbyjs.org">
+    <img alt="Gatsby" src="https://www.gatsbyjs.org/monogram.svg" width="60" />
+  </a>
+</p>
+<h1 align="center">
+  Gatsby's <%= name %> starter
+</h1>
+
+Kick off your project with this <%= name %> boilerplate. This starter ships with the main Gatsby configuration files you might need to get up and running blazing fast with the blazing fast app generator for React.
+
+_Have another more specific idea? You may want to check out our vibrant collection of [official and community-created starters](https://www.gatsbyjs.org/docs/gatsby-starters/)._
+
+## 🚀 Quick start
+
+1.  **Create a Gatsby site.**
+
+    Use the Gatsby CLI to create a new site, specifying the <%= name %> starter.
+
+    ```sh
+    # create a new Gatsby site using the <%= name %> starter
+    npx gatsby new my-<%= name %>-starter https://github.com/gatsbyjs/gatsby-starter-<%= name %>
+    ```
+
+1.  **Start developing.**
+
+    Navigate into your new site’s directory and start it up.
+
+    ```sh
+    cd my-<%= name %>-starter/
+    gatsby develop
+    ```
+
+1.  **Open the source code and start editing!**
+
+    Your site is now running at `http://localhost:8000`!
+
+    \_Note: You'll also see a second link: `http://localhost:8000/___graphql`. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the [Gatsby tutorial](https://www.gatsbyjs.org/tutorial/part-five/#introducing-graphiql).\_
+
+    Open the `my-<%= name %>-starter` directory in your code editor of choice and edit `src/pages/index.js`. Save your changes and the browser will update in real time!
+
+## 🧐 What's inside?
+
+A quick look at the top-level files and directories you'll see in a Gatsby project.
+
+    .
+    ├── node_modules
+    ├── src
+    ├── .gitignore
+    ├── .prettierrc
+    ├── gatsby-browser.js
+    ├── gatsby-config.js
+    ├── gatsby-node.js
+    ├── gatsby-ssr.js
+    ├── LICENSE
+    ├── package-lock.json
+    ├── package.json
+    └── README.md
+
+1.  **`/node_modules`**: This directory contains all of the modules of code that your project depends on (npm packages) are automatically installed.
+
+2.  **`/src`**: This directory will contain all of the code related to what you will see on the front-end of your site (what you see in the browser) such as your site header or a page template. `src` is a convention for “source code”.
+
+3.  **`.gitignore`**: This file tells git which files it should not track / not maintain a version history for.
+
+4.  **`.prettierrc`**: This is a configuration file for [Prettier](https://prettier.io/). Prettier is a tool to help keep the formatting of your code consistent.
+
+5.  **`gatsby-browser.js`**: This file is where Gatsby expects to find any usage of the [Gatsby browser APIs](https://www.gatsbyjs.org/docs/browser-apis/) (if any). These allow customization/extension of default Gatsby settings affecting the browser.
+
+6.  **`gatsby-config.js`**: This is the main configuration file for a Gatsby site. This is where you can specify information about your site (metadata) like the site title and description, which Gatsby plugins you’d like to include, etc. (Check out the [config docs](https://www.gatsbyjs.org/docs/gatsby-config/) for more detail).
+
+7.  **`gatsby-node.js`**: This file is where Gatsby expects to find any usage of the [Gatsby Node APIs](https://www.gatsbyjs.org/docs/node-apis/) (if any). These allow customization/extension of default Gatsby settings affecting pieces of the site build process.
+
+8.  **`gatsby-ssr.js`**: This file is where Gatsby expects to find any usage of the [Gatsby server-side rendering APIs](https://www.gatsbyjs.org/docs/ssr-apis/) (if any). These allow customization of default Gatsby settings affecting server-side rendering.
+
+9.  **`LICENSE`**: Gatsby is licensed under the MIT license.
+
+10. **`package-lock.json`** (See `package.json` below, first). This is an automatically generated file based on the exact versions of your npm dependencies that were installed for your project. **(You won’t change this file directly).**
+
+11. **`package.json`**: A manifest file for Node.js projects, which includes things like metadata (the project’s name, author, etc). This manifest is how npm knows which packages to install for your project.
+
+12. **`README.md`**: A text file containing useful reference information about your project.
+
+## 🎓 Learning Gatsby
+
+Looking for more guidance? Full documentation for Gatsby lives [on the website](https://www.gatsbyjs.org/). Here are some places to start:
+
+- **For most developers, we recommend starting with our [in-depth tutorial for creating a site with Gatsby](https://www.gatsbyjs.org/tutorial/).** It starts with zero assumptions about your level of ability and walks through every step of the process.
+
+- **To dive straight into code samples, head [to our documentation](https://www.gatsbyjs.org/docs/).** In particular, check out the _Guides_, _API Reference_, and _Advanced Tutorials_ sections in the sidebar.
+
+## 💫 Deploy
+
+[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/gatsbyjs/gatsby-starter-<%= name %>)

starters/README.md

@@ -0,0 +1,106 @@
+<p align="center">
+  <a href="https://gatsbyjs.org">
+    <img alt="Gatsby" src="https://www.gatsbyjs.org/monogram.svg" width="60" />
+  </a>
+</p>
+<h1 align="center">
+  Gatsby Starters
+</h1>
+
+<h3 align="center">
+  ⚛️ 📄 :rocket:
+</h3>
+<p align="center">
+  <strong>Blazing fast modern site generator for React</strong><br>
+  Go beyond static sites: build blogs, e-commerce sites, full-blown apps, and more with Gatsby.
+</p>
+<p align="center">
+  <a href="https://github.com/gatsbyjs/gatsby/blob/master/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Gatsby is released under the MIT license." />
+  </a>
+  <a href="https://circleci.com/gh/DSchau/starters">
+    <img src="https://circleci.com/gh/DSchau/starters.svg?style=shield" alt="Current CircleCI build status." />
+  </a>
+  <a href="https://www.npmjs.org/package/gatsby">
+    <img src="https://img.shields.io/npm/v/gatsby.svg" alt="Current npm package version." />
+  </a>
+  <a href="https://npmcharts.com/compare/gatsby?minimal=true">
+    <img src="https://img.shields.io/npm/dm/gatsby.svg" alt="Downloads per month on npm." />
+  </a>
+  <a href="https://gatsbyjs.org/docs/how-to-submit-a-pr/">
+    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome!" />
+  </a>
+</p>
+
+<h3 align="center">
+  <a href="https://gatsbyjs.org/docs/">Quickstart</a>
+  <span> · </span>
+  <a href="https://gatsbyjs.org/tutorial/">Tutorial</a>
+  <span> · </span>
+  <a href="https://gatsbyjs.org/plugins/">Plugins</a>
+  <span> · </span>
+  <a href="https://gatsbyjs.org/docs/gatsby-starters/">Starters</a>
+  <span> · </span>
+  <a href="https://gatsbyjs.org/showcase/">Showcase</a>
+  <span> · </span>
+  <a href="https://gatsbyjs.org/docs/how-to-contribute/">Contribute</a>
+  <span> · </span>
+  Support: <a href="https://spectrum.chat/gatsby-js">Spectrum</a>
+  <span> & </span>
+  <a href="https://discord.gg/0ZcbPKXt5bVoxkfV">Discord</a>
+</h3>
+
+Gatsby is a modern framework for blazing fast websites. This repository is our monorepo for managing all the great GatsbyJS starters for the community.
+
+## What's a starter?
+
+A starter is a simplified example to get up and running with Gatsby quickly and easily. These starters are directly integrated with the Gatsby Command Line Interface (CLI).
+
+## Official Starters
+
+<!-- AUTO-GENERATED-CONTENT:START (LIST_STARTERS) -->
+
+|                                 Name                                  | Demo                                                                                                | Description                                                   |
+| :-------------------------------------------------------------------: | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+|        [blog](https://github.com/gatsbyjs/gatsby-starter-blog)        | [gatsby-starter-blog-demo.netlify.com](https://gatsby-starter-blog-demo.netlify.com/)               | A starter for a blog powered by Gatsby and Markdown           |
+|     [default](https://github.com/gatsbyjs/gatsby-starter-default)     | [gatsby-starter-default-demo.netlify.com](https://gatsby-starter-default-demo.netlify.com/)         | A simple starter to get up and developing quickly with Gatsby |
+| [hello-world](https://github.com/gatsbyjs/gatsby-starter-hello-world) | [gatsby-starter-hello-world-demo.netlify.com](https://gatsby-starter-hello-world-demo.netlify.com/) | A simplified bare-bones starter for Gatsby                    |
+
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+## 🚀 Get Up and Running in 5 Minutes
+
+```sh
+# install the Gatsby CLI globally
+npm install -g gatsby-cli
+
+# create a new Gatsby site using the default starter
+gatsby new my-blazing-fast-site
+```
+
+e.g. `gatsby new blog my-blazing-fast-site` or `gatsby new hello-world my-blazing-fast-site` to use a specific starter!
+
+This will clone the starter of specified name into the folder `my-blazing-fast-site` and get you up and running in under 5 minutes with Gatsby and a fantastic starter. We can't wait to see what you build!
+
+## 🤝 How to Contribute
+
+Whether you're helping us fix bugs, improve the docs, or spread the word, we'd love to have you as part of the Gatsby community! :muscle: :purple_heart:
+
+Check out our [**Contributing Guide**][contributing-guide] for ideas on contributing and setup steps for getting our repositories up and running on your local machine.
+
+### Code of Conduct
+
+Gatsby is dedicated to building a welcoming, diverse, safe community. We expect everyone participating in the Gatsby community to abide by our [**Code of Conduct**][code-of-conduct]. Please read it. Please follow it. In the Gatsby community, we work hard to build each other up and create amazing things together. :muscle: :purple_heart:
+
+### A note on how this repository is organized
+
+This repository is a [monorepo][monorepo] managed using [Lerna][lerna]. This means there are [multiple packages--starters!!--][starters] managed in this codebase that are independently versioned but co-exist within this repository.
+
+We have set-up read-only clones of all of the [starters][starters] in the official gatsbyjs organization. For example, the [`default` starter](starters/default) is available as a read-only clone at [`gatsbyjs/gatsby-starter-default`][gatsby-starter-default]. Please open PRs versus **this** repository rather than the read-only clones. Upon merge any starters that have been modified will be tagged and released.
+
+[code-of-conduct]: https://gatsbyjs.org/docs/code-of-conduct/
+[contributing-guide]: https://gatsbyjs.org/docs/how-to-contribute/
+[monorepo]: https://trunkbaseddevelopment.com/monorepos
+[lerna]: https://github.com/lerna/lerna
+[starters]: /starters
+[gatsby-starter-default]: https://github.com/gatsbyjs/gatsby-starter-default

starters/blog/.eslintrc.js

@@ -0,0 +1,19 @@
+module.exports = {
+  "env": {
+    "browser": true,
+    "es6": true,
+  },
+  "plugins": [
+    "react",
+  ],
+  "globals": {
+    "graphql": false,
+  },
+  "parserOptions": {
+    "sourceType": "module",
+    "ecmaFeatures": {
+      "experimentalObjectRestSpread": true,
+      "jsx": true,
+    },
+  }
+}