add first draft of API Lifecycle docs #6229

+- extracts, runs, and replaces graphql queries for pages and `StaticQuery`s
+- writes out the pages to cache
+
+In development this is a running process powered by [Webpack](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L128) and [react-hot-loader](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L104), so changes to any files get re-run through the sequence again, with smart cache invalidation.


We should also mention that source plugins like gatsby-source-filesystem can also be watching files for changes which can trigger re-running queries. Also that queries are watched so if you modify a query it's reloaded.

sure thing. i dont know this part very well myself haha

KyleAMathews · 2018-06-29T17:49:40Z

docs/docs/gatsby-lifecycle-apis.md

+
+In development this is a running process powered by [Webpack](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L128) and [react-hot-loader](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L104), so changes to any files get re-run through the sequence again, with smart cache invalidation.
+
+The core of the bootstrap process is the "api-runner", which helps to execute APIs in sequence, with state managed in Redux. Gatsby exposes a number of lifecycle APIs which can either be implemented by you or any of your provided plugins in `gatsby-node.js`, `gatsby-browser.js` or `gatsby-ssr.js`. **The sequence of your plugins matter**, so if the output of one plugin depends on another you should be sure to reflect this in `gatsby-config.js`.


The sequence of plugins should not matter. If they do, it's a bug. Plugins shouldn't ever depend on each other. If they do, there should be an explicit hierarchal relationship between the plugins e.g. gatsby-transformer-remark and its family of gatsby-remark-* plugins.

I mean.. respectfully... these two conflict:

Plugins shouldn't ever depend on each other.

If they do, *

which is it? "shouldn't ever" or "usually dont"?

edit: i later realize what you meant by "explicit hierarchical relationship"... but leaving my confusion here

i realize this can touch on some unresolved questions in gatsby itself - im happy to simply omit the sentence. but i just wrote that based on what i saw in the issues, just trying to help not misinform.

By design it's very hard but not impossible for plugins to depend on each other. So occasionally there can be implicit dependencies but these should be treated as bugs and fixed.

hmm: example to maybe motivate discussion #5196 (comment)

KyleAMathews · 2018-06-29T17:50:27Z

docs/docs/gatsby-lifecycle-apis.md

+
+The sequence of the **main** bootstrap Node API lifecycles are:
+
+- [onPreBootstrap](https://www.gatsbyjs.org/docs/node-apis/#onPreBootstrap) eg implemented by [gatsby-plugin-typography](https://github.com/gatsbyjs/gatsby/blob/06e4fccb1abc32ba29e878bb3de303afac390e4a/packages/gatsby-plugin-typography/src/gatsby-node.js)


eg should be e.g.

KyleAMathews · 2018-06-29T17:51:08Z

docs/docs/gatsby-lifecycle-apis.md

+The sequence of the **main** bootstrap Node API lifecycles are:
+
+- [onPreBootstrap](https://www.gatsbyjs.org/docs/node-apis/#onPreBootstrap) eg implemented by [gatsby-plugin-typography](https://github.com/gatsbyjs/gatsby/blob/06e4fccb1abc32ba29e878bb3de303afac390e4a/packages/gatsby-plugin-typography/src/gatsby-node.js)
+- [sourceNodes](https://www.gatsbyjs.org/docs/node-apis/#sourceNodes) eg implemented by [gatsby-source-wikipedia](https://github.com/gatsbyjs/gatsby/blob/1fb19f9ad16618acdac7eda33d295d8ceba7f393/packages/gatsby-source-wikipedia/src/gatsby-node.js)


Please link to the master version of packages

tsiq-swyx · 2018-06-29T18:05:14Z

ok thanks! i pointed at v1 cos the pull request template said docs go to v1.. is that not accurate?

KyleAMathews · 2018-06-29T18:14:00Z

v1 would be fine but since you created your branch from master, the PR won't work. Pointing at master is fine too as we can just cherry-pick the PR back to v1.

I hope this is right...

tsiq-swyx · 2018-06-29T18:27:23Z

by the way i'm totally ready to trash this PR because my brain wasn't functioning well yesterday. we still have the content, it'd be easy to just cut and paste. just tell me what to do @m-allanson

shannonbux · 2018-06-29T19:45:54Z

Just left a couple comments. I'm not able to give feedback on accuracy, mostly just on clarity!

swyxio · 2018-06-30T15:53:28Z

hi Shannon, thanks for that! where did you leave the comments? cos i don't see them here?

m-allanson · 2018-07-02T14:02:57Z

by the way i'm totally ready to trash this PR

@sw-yx no need to trash the PR unless you're unhappy with it? We can keep iterating here and merge once it's 👍. Commits will be squashed to one as part of the merge.

swyxio · 2018-07-03T00:08:59Z

ok sure @m-allanson. may I ask what else has to be edited? I addressed your and Kyles comments, haven't seen Shannon's yet

m-allanson · 2018-07-03T12:39:24Z

may I ask what else has to be edited?

I think we just need to find out where Shannon's comments went. @shannonbux it looks like your comments didn't show up? Can you add again?

pieh · 2018-07-03T12:55:08Z

inline comments not showing up on github can happen if person started review and didn't finish it (something like commit review :) ) - happened to me once or twice

shannonbux · 2018-06-29T19:43:07Z

docs/docs/gatsby-lifecycle-apis.md

+- writes out the pages to cache
+
+In development this is a running process powered by [Webpack](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L128) and [react-hot-loader](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L104), so changes to any files get re-run through the sequence again, with [smart cache invalidation](https://github.com/gatsbyjs/gatsby/blob/ffd8b2d691c995c760fe380769852bcdb26a2278/packages/gatsby/src/bootstrap/index.js#L141). In particular, source plugins like gatsby-source-filesystem can also be watching files for changes which can trigger re-running queries. Queries are also watched so if you modify a query your development environment is reloaded.
+


it says that "source plugins like gatsby-source-filesystem can watch files for changes which can trigger re-running queries." The can words make it sound like source re-running queries only gets triggered sometimes. Is that true? If so, how would I know which file changes would trigger re-running queries?

Also it seems like our documentation so far always uses bacticks for names of plugins and packages, like gatsby-source-filesystem

The can words make it sound like source re-running queries only gets triggered sometimes.

ah well I mean it really depends on what plugins you have. I think what the phrase is trying to express is that if you have a plugin like gatsby-source-filesystem it -will- watch the files for changes, but if you have other plugins it might not. so its deterministic based on the plugin, but its not like we're not gonna know what plugins you have. how best to express this? I don't know. personally from working with Gatsby enough I don't even feel like this is an important detail, I just always assume the queries re-run.

always uses backticks

ok sure. I will address this once we finalize the other comment, didn't want GitHub to swallow it while its still unaddressed

shannonbux · 2018-07-03T16:00:58Z

Yes, thanks everyone for your patience! Turns out I just didn't click "submit review." GitHub did save my comments though, so I didn't have to rewrite them 👍

shannonbux · 2018-07-03T19:12:22Z

Wait, do you mean that certain plugins cancel out `gatsby-source-filesystem`'s ability to watch files for changes? If so, it ought to read "In an ideal setup, `gatsby-source-filesystem` watches files for changes, which trigger re-running queries. If you have certain other plugins installed along with `gatsby-source-filesystem`, like ___________, this functionality will not work." Or, do you mean that no matter what, if you have `gatsby-source-filesystem` installed, it watches files for changes? If so, then it ought to read something like "For example, `gatsby-source-filesystem` watches files for changes, and each change triggers re-running queries." And then you can mention that other source plugins may also perform this same service (don't know if that's true, just said it in case)

…

On Tue, Jul 3, 2018 at 10:48 AM, shawn wang ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/docs/gatsby-lifecycle-apis.md <#6229 (comment)>: > +## Bootstrap sequence + +During "bootstrap" gatsby: + +- reads `gatsby-config.js` to load in your list of plugins +- initializes its cache (stored in `/.cache`) +- pulls in and preprocesses data ("source and transform nodes") into a GraphQL schema +- creates pages in memory + - from your `/pages` folder + - from your `gatsby-node.js` if you implement `createPages`/`createPagesStatefully` (e.g. templates) + - from any plugins that implement `createPages`/`createPagesStatefully` +- extracts, runs, and replaces graphql queries for pages and `StaticQuery`s +- writes out the pages to cache + +In development this is a running process powered by [Webpack](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L128) and [react-hot-loader](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L104), so changes to any files get re-run through the sequence again, with [smart cache invalidation](https://github.com/gatsbyjs/gatsby/blob/ffd8b2d691c995c760fe380769852bcdb26a2278/packages/gatsby/src/bootstrap/index.js#L141). In particular, source plugins like gatsby-source-filesystem can also be watching files for changes which can trigger re-running queries. Queries are also watched so if you modify a query your development environment is reloaded. + The can words make it sound like source re-running queries only gets triggered sometimes. ah well I mean it really depends on what plugins you have. I think what the phrase is trying to express is that if you have a plugin like gatsby-source-filesystem it -will- watch the files for changes, but if you have other plugins it might not. so its deterministic based on the plugin, but its not like we're not gonna know what plugins you have. how best to express this? I don't know. personally from working with Gatsby enough I don't even feel like this is an important detail, I just always assume the queries re-run. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#6229 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Ae9o2rP2c6C5wqtd7mhYTL9MjXunNQHXks5uC6BagaJpZM4U9JKr> .

swyxio · 2018-07-03T21:04:08Z

Meant the latter. wow, words are hard 😂 . Ok I like including that sentence.

address Shannon's comments

swyxio · 2018-07-03T21:34:32Z

Done! @m-allanson

shannonbux · 2018-07-03T23:40:03Z

wohoo! Yes, words are definitely hard. Every time I re-read blogposts I write, I find new things to edit 😂

…

On Tue, Jul 3, 2018 at 3:34 PM, shawn wang ***@***.***> wrote: Done! @m-allanson <https://github.com/m-allanson> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#6229 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Ae9o2pHt0pBavep_05r0Mik3PZ_Mlajvks5uC-NxgaJpZM4U9JKr> .

m-allanson

Alright, this is going in! Thanks @tsiq-swyx 👍

* first attempt at lifecycle sequence docs closes #6197 * address Kyle's review I hope this is right... * address Shannon's comments address Shannon's comments

m-allanson · 2018-07-04T12:20:05Z

Cherry-picked to v1

swyxio added 3 commits June 23, 2018 15:43

Merge pull request #1 from gatsbyjs/master

5cb1213

merge gatsby/master

Merge pull request #2 from gatsbyjs/master

4e1f065

update

first attempt at lifecycle sequence docs

d7f804c

closes gatsbyjs#6197

m-allanson changed the base branch from v1 to master June 29, 2018 15:00

m-allanson previously approved these changes Jun 29, 2018

View reviewed changes

KyleAMathews reviewed Jun 29, 2018

View reviewed changes

address Kyle's review

4a4855e

I hope this is right...

swyxio dismissed m-allanson’s stale review via 4a4855e June 29, 2018 18:26

shannonbux reviewed Jul 3, 2018

View reviewed changes

address Shannon's comments

1cb7ba7

address Shannon's comments

m-allanson approved these changes Jul 4, 2018

View reviewed changes

m-allanson merged commit 0986a67 into gatsbyjs:master Jul 4, 2018

m-allanson pushed a commit that referenced this pull request Jul 4, 2018

add first draft of API Lifecycle docs (#6229)

73218b6

* first attempt at lifecycle sequence docs closes #6197 * address Kyle's review I hope this is right... * address Shannon's comments address Shannon's comments

This was referenced Apr 18, 2024

[Snyk] Upgrade axios from 0.20.0 to 0.28.1 X-oss-byte/gatsby-1#664

Open

[Snyk] Upgrade axios from 0.20.0 to 0.28.1 X-oss-byte/gatsby-1#665

Open

[Snyk] Upgrade axios from 0.20.0 to 0.28.1 X-oss-byte/gatsby-1#670

Open

This was referenced May 7, 2024

[Snyk] Upgrade axios from 0.19.2 to 0.28.1 nidhi42/gatsby#3449

Open

[Snyk] Upgrade axios from 0.19.2 to 0.28.1 nidhi42/gatsby#3451

Open


		In development this is a running process powered by [Webpack](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L128) and [react-hot-loader](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L104), so changes to any files get re-run through the sequence again, with smart cache invalidation.

		The core of the bootstrap process is the "api-runner", which helps to execute APIs in sequence, with state managed in Redux. Gatsby exposes a number of lifecycle APIs which can either be implemented by you or any of your provided plugins in `gatsby-node.js`, `gatsby-browser.js` or `gatsby-ssr.js`. The sequence of your plugins matter, so if the output of one plugin depends on another you should be sure to reflect this in `gatsby-config.js`.


		The sequence of the main bootstrap Node API lifecycles are:

		- [onPreBootstrap](https://www.gatsbyjs.org/docs/node-apis/#onPreBootstrap) eg implemented by [gatsby-plugin-typography](https://github.com/gatsbyjs/gatsby/blob/06e4fccb1abc32ba29e878bb3de303afac390e4a/packages/gatsby-plugin-typography/src/gatsby-node.js)

		- writes out the pages to cache

		In development this is a running process powered by [Webpack](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L128) and [react-hot-loader](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L104), so changes to any files get re-run through the sequence again, with [smart cache invalidation](https://github.com/gatsbyjs/gatsby/blob/ffd8b2d691c995c760fe380769852bcdb26a2278/packages/gatsby/src/bootstrap/index.js#L141). In particular, source plugins like gatsby-source-filesystem can also be watching files for changes which can trigger re-running queries. Queries are also watched so if you modify a query your development environment is reloaded.

add first draft of API Lifecycle docs #6229

add first draft of API Lifecycle docs #6229

Conversation

tsiq-swyx commented Jun 29, 2018

gatsbybot commented Jun 29, 2018 • edited Loading

gatsbybot commented Jun 29, 2018 • edited Loading

m-allanson commented Jun 29, 2018

m-allanson left a comment

Choose a reason for hiding this comment

KyleAMathews left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tsiq-swyx Jun 29, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tsiq-swyx commented Jun 29, 2018

KyleAMathews commented Jun 29, 2018

tsiq-swyx commented Jun 29, 2018

shannonbux commented Jun 29, 2018

swyxio commented Jun 30, 2018

m-allanson commented Jul 2, 2018

swyxio commented Jul 3, 2018

m-allanson commented Jul 3, 2018

pieh commented Jul 3, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shannonbux commented Jul 3, 2018

shannonbux commented Jul 3, 2018 via email

swyxio commented Jul 3, 2018

swyxio commented Jul 3, 2018

shannonbux commented Jul 3, 2018 via email

m-allanson left a comment

Choose a reason for hiding this comment

m-allanson commented Jul 4, 2018

gatsbybot commented Jun 29, 2018 •

edited

Loading

gatsbybot commented Jun 29, 2018 •

edited

Loading

tsiq-swyx Jun 29, 2018 •

edited

Loading