Static Queries are useful in normal Gatsby applications to
add data like the site's title, a link to a github repo, or
any other site metadata defined in
gatsby-config.js to the
In themes, Static Queries can take advantage of Component Shadowing to build up a navigation data structure and let the user override the appearance of the navigation without having to worry about how to fetch and calculate a tree from a list of Markdown.
Since we've put the
gatsby-theme-my-theme/src/components we've opted in to
letting it be shadowed by a user of our theme. We've also
enabled our user to not have to worry about figuring out
what the proper algorithm is for creating the navigation
elements in the proper data structure, which can be hard or
time consuming depending on how complex it is. A user can
create a file at
src/components/gatsby-theme-my-theme/side-nav.js in their
site and purely worry about rendering the object they are
given as a prop in their new
Since Static Queries are only run once we aren't adding any extra network calls on each page load to build up this navigation structure.
Static Queries in themes are also useful in the original
example, to pull in site metadata. The difference is that
siteMetadata is merged between themes and the user's
gatsby-config.js is merged), a user can
override the content returned in the query by setting a
field in the
siteMetadata object in their site. This can
be their name in an author field, a GitHub URL to their
project to construct an "edit this page on GitHub"
component, or anything else you can think of.
Static Queries are useful in regular applications and they can also be used to empower users when built into themes and theme components.