This guide provides information on how preloaded queries work and how to configure them in your Hydrogen app.
How preloaded queries workAnchor link to section titled "How preloaded queries work"
Preloaded queries allow your Hydrogen app to discover and preload nested queries within a page.
In the following diagram, none of the queries (
Localization) have been preloaded:
CollectionDetails queries must finish loading before
layoutContent can start. Subsequently,
layoutContent must finish loading before
localization can start. This behavior is called a request waterfall, and it can severely reduce your app performance.
Because none of these queries have dependencies, it would be ideal if they all started to load in parallel up front. This process is called preloading queries, and Hydrogen does it by default:
Preloaded queries work by storing the query fetcher for the next time the same URL is requested. The first time a route is loaded, no queries are preloaded. The second time a route is loaded, Hydrogen remembers which queries were necessary to render the same route.
Disabling preloaded queriesAnchor link to section titled "Disabling preloaded queries"
By default, all cached queries are preloaded. However, not all queries should be preloaded. For example, any query that returns personalized results shouldn't be preloaded. Just like caching personalized queries, preloading personalized queries can disperse data across requests. You can disable preloaded queries by setting cache to
CacheNone or explicitly opting out with
In development mode, Hydrogen detects request waterfalls, and warns you that the query isn't preloaded:
Routes with parametersAnchor link to section titled "Routes with parameters"
Preloaded queries work similarly for routes with parameters, like
Collection, except that each route with a different parameter has its own preloaded queries.
For example, the first time a user visits
/collections/freestyle-collection, no queries will be preloaded. Similarly, the first time a user visits
/collections/backcountry-collection, no queries will be preloaded. However, the second time that a user visits either route, queries will be preloaded. It's important that each route has separate preloaded queries, otherwise the results of one might show up for the results of the other.
Preload everywhereAnchor link to section titled "Preload everywhere"
You can tell Hydrogen to preload a query everywhere. The
preload property takes a Boolean value or a string. When the value is
*, Hydrogen will preload the query for every request. This option can be helpful for menu links in your navigation, allowing you to preload a query on button click or while you animate a transition to another page:
Debug query timingsAnchor link to section titled "Debug query timings"
If you have a suspense waterfall detected, then you can log request timing information by enabling the
logger.showQueryTiming property in your Hydrogen configuration file.
showQueryTiming property logs the timeline of when queries are being requested, resolved, and rendered. If a query is preloaded, but isn't being used, then a warning displays in the server log:
If a query is being double loaded, then a warning displays in the server log. This error typically happens when the preloaded query isn't the same query as the one requested:
Related components and hooksAnchor link to section titled "Related components and hooks"
- Learn about the analytics support built into Hydrogen.