GraphQL

GraphQL allows us to query data from WordPress, without having to writing too much PHP code.

While GraphQL is sometimes a little cumbersome to work with, we’ve integrated it in such a way that you rarely have to worry about data fetching.

The “GraphQL Schema” is a representation of the data and operations available on the CMS. We use the WPGraphQL  WordPress plugin, installed via composer, to provide an automatically generated schema — so for the most part, we only need to write queries.

The WPGraphQL docs are a great place to learn about GraphQL and how WPGraphQL works:

GraphQL Files

There are a few locations where .graphql query files can be placed within your project’s codebase.

Global App Data

The query /views/_app.graphql to declare global data used by your application, and access it from any view/block/component using the useAppData hook.

Query Hooks

Sometimes you need to be able to run queries dynamically in the browser, rather than as part of a ‘view’ or ‘block’. This is useful for things like searching, filtering, pagination and form submissions.

You can place .graphql files in queries/*.graphql, and hooks will be automatically generated for you to use within your app.

Generated hooks use TanStack Query  under the hood.

Views

‘Views’ work just like regular WordPress templates. Instead of single.php, you can create a views/single.tsx file. Alongside your .tsx file, you can create a .graphql file with the same name as the .tsx file. These queries are automatically executed when the relevant page is accessed, and the result is passed to the props of that component.

Blocks

Just like views, block components can have a paired .graphql file, which is executed automatically for each block, and passed as props to that component.

Fragments

Fragments are useful for creating reusable GraphQL snippets, as well as TypeScript snippets, and must be stored within /queries/fragments/*.graphql

GraphQL Endpoint

WPGraphQL provide a GraphQL Endpoint at /graphql for POSTing full GraphQL queries, and getting results back. The GraphiQL IDE uses this endpoint.

However, this endpoint poses a risk — since it exposes the endpoint to abuse, allowing guests to write their own queries, and potentially scrape content/data straight from the CMS, and calling mutations. While the endpoint won’t allow users to access private or draft data, or access any data which isn’t available to them according to WordPress’ security rules, it does provide a little too much flexibility.

Instead:

• For runtime queries and mutations, we use a REST endpoint which only accepts a query/mutation name and input variables, rather than sending the entire query.
• For pages, we execute view/block queries automatically when pages are accessed.

For example, if you’ve got a GraphQL file called queries/UseLatestPosts.graphql in your theme folder, then useLatestPosts() will trigger a fetch request to http://my-site.local/wp-json/ed/v1/query/usePosts?params={%22limit%22:1} instead, noting that variables are JSON encoded into the URL. Use Chrome’s Network tab to see the request and responses in action.

This method also allows us to cache query results at a proxy level, as though they are static files, while keeping our /graphql hidden from hackers who might want to DDoS the site, search for vulneratbilities, or otherwise attempt to scrape data directly from the CMS. The result is that only the data we have manually selected in our query files is made publicly accessible.

Mutations also follow this pattern, however they use POST requests, so that data will never accidentally be cached.