When to use fetchSync vs useQuery

[davidhousedev]

It seems like fetchSync and useQuery share similar roles though with a different public API. Could someone help me understand what the high-level goal is of each of these APIs, when I should use one versus when I should use the other?

It seems that the biggest difference between the two is that fetchSync can be run in client components, though with numerous caveats (outlined here). What else should I keep in mind?

[jplhomer]

• fetchSync is a "sync version of fetch." If you are making an HTTP call to an endpoint, you should use fetchSync. This is because Hydrogen can easily optimize this for its preload cache. It also means you don't have to write an async function or provide a custom set of cache keys.
• useQuery is a way to run an async function in a Suspense-friendly way. You should use it if you need to use a third-party JavaScript library that requires async/await or Promises — aka something that isn't a simple fetch call. Hydrogen cannot automatically infer the keys to be used in the cache like it can with fetchSync, so you need to provide the keys every time.

Note that this might change someday, as we are revisiting how data fetching works in Server Components. For now, hopefully that guidance is helpful!

[jplhomer]

There's no difference between the two in terms of prioritization or loading states. In fact, fetchSync uses useQuery under the hood.

It's more of a convenience to be able to write:

fetchSync('https://my.api.com').json();

over

useQuery(['some', 'key'], async () => {
  return await fetch('https://my.api.com').then(r => r.json());
});

[davidhousedev]

Ah ha! Okay, that clarifies things a lot. Thank you so much!

[davidhousedev]

@jplhomer one more follow-up question just to confirm: say I am using useQuery and am calling a client method to fetch data from my CMS. I'm assuming that I should configure a cache key that is unique to the method and arguments I pass to the underlying client, right?

Say for example:

useQuery(
  ['cmsClient', 'retrieveProductData', 'sort:ascending'],
  () => cmsClient.retrieveProductData({ sort: 'ascending' }),
  { cache: CacheMinutes() } 
)

I would want to make sure that 'sort:ascending' was captured in the cache key, because changing the sort order would change the data in the response. Is that right? Are there any disallowed characters in cache keys that I should be mindful of?

[frandiox]

@davidhousedev Yes, you need pass also the parameters or anything that makes it "unique".
If you were using a normal fetch internally to call your custom API, you would be passing /retrieveProductData?sort=ascending or similar as the key. Therefore, you should do the same when using a JS SDK like in your example. You can just pass JSON.stringify(params) or similar.

Also, if you fancy you can make your own abstraction around useQuery: useCMSQuery('retrieveProductData', params, options) that creates the key internally and call your CMS.

[davidhousedev]

Wonderful! Thank you!