feat(themes): Add a starter for theme development (#15640)

.gitignore

@@ -62,3 +62,4 @@ package-lock.json
 !themes/gatsby-starter-blog-theme/package-lock.json
 !themes/gatsby-starter-notes-theme/package-lock.json
 !themes/gatsby-starter-theme/package-lock.json
+!themes/gatsby-starter-theme-workspace/package-lock.json

scripts/clone-and-validate-theme-starters.sh

@@ -8,7 +8,7 @@ if [ "$IS_CI" = true ]; then
   sudo apt-get update && sudo apt-get install jq
 fi
 
-for folder in "themes/gatsby-starter-blog-theme" "themes/gatsby-starter-notes-theme" "themes/gatsby-starter-theme"; do
+for folder in "themes/gatsby-starter-blog-theme" "themes/gatsby-starter-notes-theme" "themes/gatsby-starter-theme" "themes/gatsby-starter-theme-workspace"; do
   [ -d "$folder" ] || continue # only directories
   cd $BASE
 

themes/gatsby-starter-theme-workspace/.gitignore

@@ -0,0 +1,3 @@
+.cache
+public
+node_modules

themes/gatsby-starter-theme-workspace/README.md

@@ -0,0 +1,73 @@
+<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">
+  Starter for creating a Gatsby Theme workspace
+</h1>
+
+```shell
+gatsby new my-theme https://github.com/gatsbyjs/gatsby-starter-theme-workspace
+cd my-theme
+yarn workspace example develop
+```
+
+## Layout
+
+```shell
+➜ tree . -L 2 -I node_modules
+.
+├── README.md
+├── gatsby-theme-minimal
+│   ├── README.md
+│   ├── gatsby-config.js
+│   ├── index.js
+│   └── package.json
+├── example
+│   ├── README.md
+│   ├── gatsby-config.js
+│   ├── package.json
+│   └── src
+├── package.json
+└── yarn.lock
+
+3 directories, 10 files
+```
+
+### `gatsby-theme-minimal`
+
+This directory is the theme package itself. You should rename this at
+some point to be `gatsby-theme-my-theme-name`. Also change the
+`package.json` name field and the corresponding dependency in the
+example directory's `package.json`/`gatsby-config.js`.
+
+- `gatsby-theme-minimal/`
+  - gatsby-config.js
+    An empty gatsby-config that you can use as a starting point for
+    building functionality into your theme.
+  - index.js
+    Since themes also function as plugins, this is an empty file that
+    gatsby needs to use this theme as a plugin.
+  - package.json
+    The dependencies that your theme will pull in when people install
+    it. `gatsby` should be a `peerDependency`.
+
+### `example`
+
+This is an example usage of your theme. It should look the same as the
+site of someone who installed and used your theme from npm.
+
+- `example/`
+  - gatsby-config.js
+    Specifies which theme to use and any other one-off config a site
+    might need.
+  - src/
+    source code such as one-off pages or components that might live in
+    a user's site.
+
+You can run the example with:
+
+```sh
+yarn workspace example start
+```

themes/gatsby-starter-theme-workspace/example/README.md

@@ -0,0 +1,6 @@
+# Gatsby Theme Minimal Example
+
+A usage of
+[gatsby-theme-minimal](https://github.com/ChristopherBiscardi/gatsby-theme-minimal)
+that does nothing but use the theme. As a result you will see `Error: Missing resources for /` when navigating to `localhost:8000`. To get
+rid of that, create a page in `src/pages/index.js`.

themes/gatsby-starter-theme-workspace/example/gatsby-config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  plugins: [{ resolve: `gatsby-theme-minimal`, options: {} }],
+}

themes/gatsby-starter-theme-workspace/example/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "example",
+  "version": "1.0.0",
+  "main": "index.js",
+  "repository": "git@github.com:ChristopherBiscardi/gatsby-theme-minimal-example.git",
+  "author": "christopherbiscardi <chris@christopherbiscardi.com> (@chrisbiscardi)",
+  "license": "MIT",
+  "scripts": {
+    "develop": "gatsby develop",
+    "build": "gatsby build"
+  },
+  "dependencies": {
+    "gatsby": "^2.13.3",
+    "gatsby-theme-minimal": "^1.0.0",
+    "react": "^16.8.6",
+    "react-dom": "^16.8.6"
+  }
+}

themes/gatsby-starter-theme-workspace/example/src/pages/index.js

@@ -0,0 +1,3 @@
+import React from "react"
+
+export default () => <div>Homepage in a user's site</div>

themes/gatsby-starter-theme-workspace/gatsby-theme-minimal/README.md

@@ -0,0 +1,51 @@
+# The smallest possible Gatsby theme
+
+## Quick Start
+
+```sh
+mkdir my-site
+cd my-site
+yarn init
+# install gatsby-theme-minimal and it's dependencies
+yarn add gatsby react react-dom gatsby-theme-minimal
+```
+
+Then add the theme to your `gatsby-config.js`. We'll use the long form
+here for education purposes.
+
+```javascript
+module.exports = {
+  __experimentalThemes: [
+    {
+      resolve: "gatsby-theme-minimal",
+      options: {},
+    },
+  ],
+}
+```
+
+That's it, you can now run your gatsby site using
+
+```sh
+yarn gatsby develop
+```
+
+Note that this site doesn't _do_ anything, so you're see a missing
+resources error. Create a simple page in `src/pages/index.js` to see a
+page on the root url.
+
+```javascript
+import React from "react"
+
+export default () => <div>My Site!</div>
+```
+
+## Doing more with themes
+
+You can use this as a place to start when developing themes. I
+generally suggest using [yarn
+workspaces](https://yarnpkg.com/lang/en/docs/workspaces/) like the
+[gatsby-theme-examples repo
+does](https://github.com/ChristopherBiscardi/gatsby-theme-examples),
+but using `yarn link` or `npm link` is a viable alternative if you're
+not familiar with workspaces.

themes/gatsby-starter-theme-workspace/gatsby-theme-minimal/gatsby-config.js

@@ -0,0 +1 @@
+module.exports = {}

themes/gatsby-starter-theme-workspace/gatsby-theme-minimal/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "gatsby-theme-minimal",
+  "version": "1.0.0",
+  "main": "index.js",
+  "author": "christopherbiscardi <chris@christopherbiscardi.com> (@chrisbiscardi)",
+  "license": "MIT",
+  "peerDependencies": {
+    "gatsby": "^2.6.0"
+  }
+}

themes/gatsby-starter-theme-workspace/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "gatsby-starter-theme-develop",
+  "private": true,
+  "version": "0.0.1",
+  "main": "index.js",
+  "license": "MIT",
+  "scripts": {
+    "build": "yarn workspace example build"
+  },
+  "workspaces": [
+    "gatsby-theme-minimal",
+    "example"
+  ]
+}

themes/package.json

@@ -8,6 +8,7 @@
     "gatsby-theme-notes",
     "gatsby-starter-theme",
     "gatsby-starter-blog-theme",
-    "gatsby-starter-notes-theme"
+    "gatsby-starter-notes-theme",
+    "gatsby-starter-theme-workspace"
   ]
 }