RFC: GraphQL Client

[moonmeister]

Abstract

The GraphQL over HTTP standard is fairly simple to start. You make a post request with the body as your query and the Content-Type: application/json set, and you're golden. But advanced HTTP caching, application state management, types, etc., all creep into "client features." These features often require the client to be tightly coupled to the dev's framework of choice.

So far in Faust, we've used GQTY and then Apollo. GQTY was replaced because of a difficult learning curve and non-standard patterns. We chose Apollo as a good default option. Since then, the React/Next world has changed. There are other significant GraphQL clients in the game, as well as simpler options.

Motivation

It's not just that Apollo is no longer the clear default choice. There should be no default choice; we want to enable developers to choose the tooling that best fits their needs.

As we look forward and want to provide documentation and tooling that serves the widest variety of users, we need a solution that is not so niche to the React world. We also recognize that many users have preferred tooling that isn't Apollo. Faust's current dependence on Apollo makes this a required technology, which also happens to be holding us back from App router support in Next.js.

Research

fetch

One of the biggest changes in the last couple of years is that fetch is now the default way to make HTTP requests across the industry. It's in the browser. It is now built into Node.js. It's provided for you in SvelteKit, Next.js App router, and Nuxt.js for data loading. It is everywhere.

Application state

Apollo does a lot to manage the application state, but this is technically an issue distinct from making a GraphQL query. This is not an uncommon thing for GraphQL clients but newer tooling such as Tanstack Query go out of their way to only solve the state management issue while allowing you to choose the method of fetching data.

Ultimately, our research shows that we don't want to be opinionated in this space but choose an option that allows developers to manage the application state as they desire, not as their GraphQL client dictates.

GraphQL Clients Features

We've compiled a list of possible features that we see as important to a GraphQL client.

1. This is fundamentally a GraphQL client.
   1. Make GraphQL Queries (POST & GET)
   2. Support for Persisted Queries
      • Automatic Persisted Queries (at runtime)
      • Persisted queries (at build w/ webpack/vite integration)
2. Extensible to support things like https://www.leefroese.com/blog/headless-wordpress-gravity-forms-uploads or other standard and non-standard GraphQL features
3. TypeScript - Support TS for writing queries and typing responses (possibly highly dependent on meta-framework)
4. Support Authentication (multiple types)
   • Oauth
   • Token
   • Basic Auth
   • etc...
5. Multiple GraphQL APs - support multiple endpoints for multisite and other non-WPGraphQL APIs
6. Fragment support - https://www.apollographql.com/docs/react/data/fragments#colocating-fragments

Proposal

Much of our future work will be built around documentation (authentication, previews, caching, etc.). These documents need a client, but the client isn't the point. We believe fetch will be best for documenting these solutions without distraction. The bare nature of fetch will also aid in folks' understanding of GraphQL and the broader topic (i.e., Authentication) by not obfuscating GraphQL behind a purpose-built client.

Instead of bundling a client into our future tooling, we'll leverage fetch as a clear way to get started quickly and simply. To support existing Faust.js users we'll also document any new tooling with Apollo. As time goes on, we might further document other, more feature-rich clients.

Beyond feature specific documentation, we should create some docs teaching the basics of GraphQL clients and the various ways to make a GraphQL request over HTTP. Here are some suggested docs:

• [Tutorial] Making a GraphQL Request (POST/GET basics, fetch)
• [Explanation] What URL should I use to fetch data from WPGraphQL (?graphql vs /graphql)
• [Explanation] GET vs POST for GraphQL requests
• [How To] Enabling Automatic Persisted Queries for WPGraphQL Smart Cache (Apollo and fetch versions)
• [How To] Co-locating Fragments in
• [Example] Fetching data using Apollo client (pages router)
• [Example] Fetching data using fetch (app router)
• [Example] Fetching data from Multiple WP sites (app router, fetch)

Alternatives Considered

Minimal clients like graphql-request or graffle are tempting here too. They find a nice balance of being a GraphQL client
without being full state management libraries. They could possibly accelerate some GraphQL features we'd otherwise have to manually document for fetch. For the time being, we don't believe this is a worthwhile trade-off. I believe these should be considered in the future as possible options if we build any functioning starters, or get more opinionated on a recommended client.

How Do We Teach This?

The good news is that fetch is a well-documented web standard, and node and mdn have great docs around that spec.

How Can You Help?

We are excited about this new toolkit and the opportunities it presents for the WordPress headless community.

We’d love your feedback on the following:

• Are there any drawbacks we haven't considered? Are there better approaches we should consider?
• Are we missing any major topics or examples?
• Are we missing any major GraphQL client features that would affect this decision?
• What other topics would you like us to cover? We would love to hear from you!

RFC Changelog

• February 6, 2025 - Initial WIP for GraphQL client.

[colinmurphy]

@moonmeister LGTM 👍