Skip to main content

Static vs Normal Queries

This documentation isn’t up to date with the latest version of Gatsby.

Outdated areas are:

  • describe how queries are stripped and JSON imports are rewritten

You can help by making a PR to update this documentation.

How StaticQuery differs from page query

StaticQuery can do most of the things that page query can, including fragments. The main differences are:

  • page queries can accept variables (via pageContext) but can only be added to page components
  • StaticQuery does not accept variables (hence the name “static”), but can be used in any component, including pages
  • StaticQuery does not work with raw React.createElement calls; please use JSX, e.g. <StaticQuery />
    • NOTE: you can also use the new useStaticQuery hook; more information below
  • Static Queries don’t need to get run for each page.(ie:Just once)

useStaticQuery hook


Started here because they’re referenced in page-query-runner:findIdsWithDataDependencies.

The redux staticQueryComponents is a map from component jsonName to StaticQueryObject. E.g

The staticQueryComponents redux namespace is owned by the static-query-components.js reducer with reacts to REPLACE_STATIC_QUERY actions.

It is created in query-watcher. TODO: Check other usages

TODO: in query-watcher.js/handleQuery, we remove jsonName from dataDependencies. How did it get there? Why is jsonName used here, but for other dependencies, it’s a path?


  • websocket-manager. TODO

  • query-watcher.

    • getQueriesSnapshot returns map with snapshot of state.staticQueryComponents
    • handleComponentsWithRemovedQueries. For each staticQueryComponent, if passed in queries doesn’t include staticQueryComponent.componentPath. TODO: Where is StaticQueryComponent created? TODO: Where is queries passed into handleComponentsWithRemovedQueries?

    TODO: Finish above

Edit this page on GitHub