Introduce <DeferredQuery> and useDeferredQuery?

[njbmartin]

These are two GraphQL hooks I have been thinking about for some time, and looks like I'm not the only one: #2080 (@KyleAMathews)

Deferred Queries

This would be useful in instances where might want to keep the initial page query as light as possible (eg. SEO and placeholders), but once the client has loaded, you load the rest of the page data.

As a prime example, one of our page-data.json files is currently about 150kbs, mainly due to all the images. That's a considerable amount of "bloat" that would benefit from a trim, but at the moment we would have to use a server-side API query to achieve this (or, create a plugin?).

Playing on the idea of @defer and using https://graphql.org/blog/2020-12-08-improving-latency-with-defer-and-stream-directives/ as an example:

query {
  person(id: "cGVvcGxlOjE=") {
    name
    ...HomeworldFragment @defer
}

fragment HomeworldFragment on Person {
    homeworld {
      name
      gatsbyImageData # Added as an example.
    }
}

}

Data from fields marked with @defer would be separated out into a separate JSON file, and the page query would return a deferredRef, which is derived from the payload, eg.

{
  "data": { 
    "person": {
      "name": "Luke Skywalker",
      "deferredRef": "d677628f-83ca-5d50-a746-22641fded3d5"
    }
  },
}

There would then be a deferred JSON file generated at /deferred-data/d677628f-83ca-5d50-a746-22641fded3d5.json:

{
  "id": "d677628f-83ca-5d50-a746-22641fded3d5",
  "path": ["person"],
  "data": { 
    "homeworld": {
      "name": "Tatooine",
      "gatsbyImageData": {
        ...
      }
    }
  }
}

<DeferredQuery>

Your page might look something like this:

const PageWithDeferred = ({ data }) => {

  return (
    <div>
      <h1>{ data.person.name}</h1>
      <DeferredQuery
        ref={data.person.deferredRef}
        fallback={<PlaceholderImage />}
        enabled={__condition__}
        render={deferredQuery => <GatsbyImage image={deferredQuery.gatsbyImageData} />}
      />
    </div>
  )
}

DeferredQuery component is designed to reduce the impact of re-renders.

useDeferredQuery

The alternative is the useDeferredQuery hook:

const PageWithDeferred = ({ data }) => {
const [enabled, setEnabled] = useState(false) // to be enabled at some point (eg. page interaction)
const deferredQuery = useDeferredQuery(data.person.deferredRef, enabled)

  return (
    <div>
      <h1>{ data.person.name}</h1>
      <DeferredComponent ref={} />
      { deferredQuery ? (<GatsbyImage image={deferredQuery.gatsbyImageData} />) : (<PlaceholderImage />)  }
    </div>
  )
}

const useDeferredQuery = (deferredRef, enabled = true) => {
  const [query, setQuery] = useState();

  const fetchData = useCallback(async () => {
    const data = await fetch(`/deferred-data/${deferredRef}.json`).json()
    setQuery(data);
  }, [deferredRef]);

  useEffect(() => {
    if(!enabled || !deferredRef) return;
    fetchData()
  }, [deferredRef, enabled]);

  return query
}

Given that @defer is still in RFC, it might be best to use a Gatsby-specific directive like @GatsbyDefer.