-
Notifications
You must be signed in to change notification settings - Fork 10.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
add first draft of API Lifecycle docs #6229
Conversation
merge gatsby/master
Deploy preview for using-drupal ready! Built with commit 1cb7ba7 |
Deploy preview for gatsbygram ready! Built with commit 1cb7ba7 |
👍 I'm going to try pointing this at |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, thanks @tsiq-swyx 👍
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great start! This will be a fantastic resource once it's done!
docs/docs/gatsby-lifecycle-apis.md
Outdated
- 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
sure thing. i dont know this part very well myself haha
docs/docs/gatsby-lifecycle-apis.md
Outdated
|
||
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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
hmm: example to maybe motivate discussion #5196 (comment)
docs/docs/gatsby-lifecycle-apis.md
Outdated
|
||
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) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
eg
should be e.g.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
done
docs/docs/gatsby-lifecycle-apis.md
Outdated
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) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please link to the master version of packages
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
done
ok thanks! i pointed at v1 cos the pull request template said docs go to v1.. is that not accurate? |
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...
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 |
Just left a couple comments. I'm not able to give feedback on accuracy, mostly just on clarity! |
hi Shannon, thanks for that! where did you leave the comments? cos i don't see them here? |
@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. |
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 |
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? |
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 |
docs/docs/gatsby-lifecycle-apis.md
Outdated
- 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. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also it seems like our documentation so far always uses bacticks for names of plugins and packages, like gatsby-source-filesystem
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
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 👍 |
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>
.
|
Meant the latter. wow, words are hard 😂 . Ok I like including that sentence. |
address Shannon's comments
Done! @m-allanson |
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>
.
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
Cherry-picked to |
closes #6197