From c31edbea5288a24266c08bc7cb7a42adba7755e3 Mon Sep 17 00:00:00 2001 From: Max Stoiber Date: Wed, 22 Jul 2020 07:39:04 +0200 Subject: [PATCH 1/7] Write more detailed Admin architecture docs --- packages/gatsby-admin/README.md | 37 ++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/packages/gatsby-admin/README.md b/packages/gatsby-admin/README.md index c0157f75f558c..a4d5c40dcf7aa 100644 --- a/packages/gatsby-admin/README.md +++ b/packages/gatsby-admin/README.md @@ -2,11 +2,42 @@ A visual interface to configure your Gatsby site. -## Development +## Architecture + +The Gatsby Admin interface (this package) is a standard Gatsby site. + +It uses [theme-ui](https://theme-ui.com) (with the [strict-ui](https://github.com/system-ui/theme-ui/pull/719) experimantal extension) and [gatsby-interface](https://github.com/gatsby-inc/gatsby-interface) for styling. + +It fetches its data from the [gatsby-recipes GraphQL server](../gatsby-recipes/src/graphql-server/), which exposes all the information we need about the locally running Gatsby site, using [urql](https://github.com/FormidableLabs/urql). + +It also listens to the [`gatsby develop` status server](../gatsby/src/commands/develop.ts), which exposes information about whether the developer changed the config files and needs to restart the develop process. + +### Service Discovery + +We automatically start both the GraphQL and status server when developers run `gatsby develop`. However, they use random ports. -The Admin app itself is a standard Gatsby site. It fetches its data from the Recipes GraphQL server, which exposes all the information we need about the Gatsby site. +To discover where they are (and whether they are already running), we added a service discovery mechanism to `gatsby-core-utils`. This stores the ports of the running Gatsby site(s) at `~/.config/gatsby/sites//.json`. -It uses [theme-ui](https://theme-ui.com) (with the [strict-ui](https://github.com/system-ui/theme-ui/pull/719) experiment) and [gatsby-interface](https://github.com/gatsby-inc/gatsby-interface) to style the app and [urql](https://github.com/FormidableLabs/urql) to fetch the data from the GraphQL server. +We can then fetch `localhost:8000/___services` (where `:8000` is the well-known port of the running site), which returns a list of all the random ports used by the site: + +``` +$ curl http://localhost:8000/___services | jq +{ + "developproxy": { + "port": 8000 + }, + "developstatusserver": { + "port": 60731 + }, + "recipesgraphqlserver": { + "port": 50400 + } +} +``` + +That's how the Admin frontend knows to connect to `localhost:50400/graphql` to connect to the GraphQL server, and `localhost:60731` to connect to the develop status server. + +## Development ### Running it locally From 2bb82ace54bca670ed1cffb468b2b11992a285d8 Mon Sep 17 00:00:00 2001 From: Max Stoiber Date: Wed, 22 Jul 2020 07:45:00 +0200 Subject: [PATCH 2/7] Add section on production deployment to gatsby-admin docs --- packages/gatsby-admin/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/packages/gatsby-admin/README.md b/packages/gatsby-admin/README.md index a4d5c40dcf7aa..c02de943ae460 100644 --- a/packages/gatsby-admin/README.md +++ b/packages/gatsby-admin/README.md @@ -37,6 +37,14 @@ $ curl http://localhost:8000/___services | jq That's how the Admin frontend knows to connect to `localhost:50400/graphql` to connect to the GraphQL server, and `localhost:60731` to connect to the develop status server. +### Production Deployment + +We do not want developers to use `gatsby-admin` as a plugin, as that would enable them to override anything in our `src/` folder due to theme shadowing! Instead, we statically serve the built files from the [develop parent proxy](../gatsby/src/utils/develop-proxy.ts). + +Initially, @mxstbr thought this would be as simple as publishing `gatsby-admin` to npm and adding that as a dependency to `gatsby`. However, yarn and lerna do not handle circular dependencies well. Doing this breaks `lerna bootstrap` due to `gatsby-admin` trying to build (with `gatsby`!) before `gatsby` is built. + +Instead, `gatsby-admin` copies its built files to `gatsby/gatsby-admin-public` which is then published to npm. While not an ideal solution, it fixes the issue and works relatively reliably. + ## Development ### Running it locally From 7bfb86c421230c2ffa189a74b6a0e80ba12e3ed0 Mon Sep 17 00:00:00 2001 From: Max Stoiber Date: Wed, 22 Jul 2020 07:57:19 +0200 Subject: [PATCH 3/7] Absolute URLs so they work on npm etc. --- packages/gatsby-admin/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/gatsby-admin/README.md b/packages/gatsby-admin/README.md index c02de943ae460..71004b2c92b5b 100644 --- a/packages/gatsby-admin/README.md +++ b/packages/gatsby-admin/README.md @@ -8,9 +8,9 @@ The Gatsby Admin interface (this package) is a standard Gatsby site. It uses [theme-ui](https://theme-ui.com) (with the [strict-ui](https://github.com/system-ui/theme-ui/pull/719) experimantal extension) and [gatsby-interface](https://github.com/gatsby-inc/gatsby-interface) for styling. -It fetches its data from the [gatsby-recipes GraphQL server](../gatsby-recipes/src/graphql-server/), which exposes all the information we need about the locally running Gatsby site, using [urql](https://github.com/FormidableLabs/urql). +It fetches its data from the [gatsby-recipes GraphQL server](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-recipes/src/graphql-server), which exposes all the information we need about the locally running Gatsby site, using [urql](https://github.com/FormidableLabs/urql). -It also listens to the [`gatsby develop` status server](../gatsby/src/commands/develop.ts), which exposes information about whether the developer changed the config files and needs to restart the develop process. +It also listens to the [`gatsby develop` status server](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/commands/develop.ts), which exposes information about whether the developer changed the config files and needs to restart the develop process. ### Service Discovery @@ -39,7 +39,7 @@ That's how the Admin frontend knows to connect to `localhost:50400/graphql` to c ### Production Deployment -We do not want developers to use `gatsby-admin` as a plugin, as that would enable them to override anything in our `src/` folder due to theme shadowing! Instead, we statically serve the built files from the [develop parent proxy](../gatsby/src/utils/develop-proxy.ts). +We do not want developers to use `gatsby-admin` as a plugin, as that would enable them to override anything in our `src/` folder due to theme shadowing! Instead, we statically serve the built files from the [develop parent proxy](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/develop-proxy.ts). Initially, @mxstbr thought this would be as simple as publishing `gatsby-admin` to npm and adding that as a dependency to `gatsby`. However, yarn and lerna do not handle circular dependencies well. Doing this breaks `lerna bootstrap` due to `gatsby-admin` trying to build (with `gatsby`!) before `gatsby` is built. From aa10363e648117d47936f388e43ee46188ab0976 Mon Sep 17 00:00:00 2001 From: Max Stoiber Date: Wed, 22 Jul 2020 17:12:52 +0200 Subject: [PATCH 4/7] Fix pronouns and wording --- packages/gatsby-admin/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/gatsby-admin/README.md b/packages/gatsby-admin/README.md index 71004b2c92b5b..6f439bf6094a4 100644 --- a/packages/gatsby-admin/README.md +++ b/packages/gatsby-admin/README.md @@ -8,17 +8,17 @@ The Gatsby Admin interface (this package) is a standard Gatsby site. It uses [theme-ui](https://theme-ui.com) (with the [strict-ui](https://github.com/system-ui/theme-ui/pull/719) experimantal extension) and [gatsby-interface](https://github.com/gatsby-inc/gatsby-interface) for styling. -It fetches its data from the [gatsby-recipes GraphQL server](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-recipes/src/graphql-server), which exposes all the information we need about the locally running Gatsby site, using [urql](https://github.com/FormidableLabs/urql). +It fetches its data from the [gatsby-recipes GraphQL server](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-recipes/src/graphql-server), which exposes all the information Admin needs about the locally running Gatsby site, using [urql](https://github.com/FormidableLabs/urql). -It also listens to the [`gatsby develop` status server](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/commands/develop.ts), which exposes information about whether the developer changed the config files and needs to restart the develop process. +It also listens to the [`gatsby develop` status server](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/commands/develop.ts), which exposes information about whether you changed the config files and need to restart the develop process. ### Service Discovery -We automatically start both the GraphQL and status server when developers run `gatsby develop`. However, they use random ports. +`gatsby develop` automatically starts both the GraphQL and status server. However, both of these use random ports. -To discover where they are (and whether they are already running), we added a service discovery mechanism to `gatsby-core-utils`. This stores the ports of the running Gatsby site(s) at `~/.config/gatsby/sites//.json`. +To discover where they are (and whether they are already running) there is a service discovery mechanism in `gatsby-core-utils`. It stores the ports of the running Gatsby site(s) at `~/.config/gatsby/sites//.json`. -We can then fetch `localhost:8000/___services` (where `:8000` is the well-known port of the running site), which returns a list of all the random ports used by the site: +Admin can then fetch `localhost:8000/___services` (where `:8000` is the well-known port of the running site), which returns a list of all the random ports used by the site: ``` $ curl http://localhost:8000/___services | jq @@ -39,7 +39,7 @@ That's how the Admin frontend knows to connect to `localhost:50400/graphql` to c ### Production Deployment -We do not want developers to use `gatsby-admin` as a plugin, as that would enable them to override anything in our `src/` folder due to theme shadowing! Instead, we statically serve the built files from the [develop parent proxy](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/develop-proxy.ts). +`gatsby-admin` cannot be used as a plugin, as that would enable users to override anything in the `src/` folder due to theme shadowing! Instead, `gatsby develop` statically serves the built files from the [develop parent proxy](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/develop-proxy.ts). Initially, @mxstbr thought this would be as simple as publishing `gatsby-admin` to npm and adding that as a dependency to `gatsby`. However, yarn and lerna do not handle circular dependencies well. Doing this breaks `lerna bootstrap` due to `gatsby-admin` trying to build (with `gatsby`!) before `gatsby` is built. From df8c9c6b6eb2ca6ba72fd7fc92c4249c898ecbf4 Mon Sep 17 00:00:00 2001 From: Max Stoiber Date: Wed, 22 Jul 2020 17:14:29 +0200 Subject: [PATCH 5/7] Clean up some more --- packages/gatsby-admin/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/gatsby-admin/README.md b/packages/gatsby-admin/README.md index 6f439bf6094a4..277043d75b61b 100644 --- a/packages/gatsby-admin/README.md +++ b/packages/gatsby-admin/README.md @@ -41,7 +41,7 @@ That's how the Admin frontend knows to connect to `localhost:50400/graphql` to c `gatsby-admin` cannot be used as a plugin, as that would enable users to override anything in the `src/` folder due to theme shadowing! Instead, `gatsby develop` statically serves the built files from the [develop parent proxy](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/develop-proxy.ts). -Initially, @mxstbr thought this would be as simple as publishing `gatsby-admin` to npm and adding that as a dependency to `gatsby`. However, yarn and lerna do not handle circular dependencies well. Doing this breaks `lerna bootstrap` due to `gatsby-admin` trying to build (with `gatsby`!) before `gatsby` is built. +Initially, @mxstbr published the built `gatsby-admin` files to npm and added it as a dependency to `gatsby`. However, yarn and lerna do not handle circular dependencies well. Doing this breaks `lerna bootstrap` due to `gatsby-admin` trying to build (with `gatsby`!) before `gatsby` is built. Instead, `gatsby-admin` copies its built files to `gatsby/gatsby-admin-public` which is then published to npm. While not an ideal solution, it fixes the issue and works relatively reliably. From 88c264aae12f8b8354e7f6671501ac4210b04ea2 Mon Sep 17 00:00:00 2001 From: Max Stoiber Date: Thu, 23 Jul 2020 01:56:38 -0700 Subject: [PATCH 6/7] Tighten up language around production deployment Co-authored-by: Brent Jackson --- packages/gatsby-admin/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/gatsby-admin/README.md b/packages/gatsby-admin/README.md index 277043d75b61b..8b244d3b77a72 100644 --- a/packages/gatsby-admin/README.md +++ b/packages/gatsby-admin/README.md @@ -39,7 +39,7 @@ That's how the Admin frontend knows to connect to `localhost:50400/graphql` to c ### Production Deployment -`gatsby-admin` cannot be used as a plugin, as that would enable users to override anything in the `src/` folder due to theme shadowing! Instead, `gatsby develop` statically serves the built files from the [develop parent proxy](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/develop-proxy.ts). +To avoid clashing with the local site and potential issues with shadowing, `gatsby develop` statically serves the built files from the [develop parent proxy](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/develop-proxy.ts). Initially, @mxstbr published the built `gatsby-admin` files to npm and added it as a dependency to `gatsby`. However, yarn and lerna do not handle circular dependencies well. Doing this breaks `lerna bootstrap` due to `gatsby-admin` trying to build (with `gatsby`!) before `gatsby` is built. From c3f4bdab05c9c26b35bcf8393a11db2f79937371 Mon Sep 17 00:00:00 2001 From: Max Stoiber Date: Thu, 23 Jul 2020 01:56:50 -0700 Subject: [PATCH 7/7] Update packages/gatsby-admin/README.md Co-authored-by: Brent Jackson --- packages/gatsby-admin/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/packages/gatsby-admin/README.md b/packages/gatsby-admin/README.md index 8b244d3b77a72..dced258e8e86c 100644 --- a/packages/gatsby-admin/README.md +++ b/packages/gatsby-admin/README.md @@ -41,9 +41,7 @@ That's how the Admin frontend knows to connect to `localhost:50400/graphql` to c To avoid clashing with the local site and potential issues with shadowing, `gatsby develop` statically serves the built files from the [develop parent proxy](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/develop-proxy.ts). -Initially, @mxstbr published the built `gatsby-admin` files to npm and added it as a dependency to `gatsby`. However, yarn and lerna do not handle circular dependencies well. Doing this breaks `lerna bootstrap` due to `gatsby-admin` trying to build (with `gatsby`!) before `gatsby` is built. - -Instead, `gatsby-admin` copies its built files to `gatsby/gatsby-admin-public` which is then published to npm. While not an ideal solution, it fixes the issue and works relatively reliably. +To avoid issues with yarn, lerna, and circular dependencies, `gatsby-admin` copies its built files to `gatsby/gatsby-admin-public` which is then published to npm. While not an ideal solution, it fixes the issue and works relatively reliably. ## Development