Generate GraphQL queries and mutations

Overview

We use GraphQL for simplified, structured query writing for interfacing with the the data via our API. To achieve this we write our queries and mutations using the GraphQL syntax and then run a script via the command line to generate the necessary functions for retrieving and manipulating the data on the backend through the API.

This document describes the process of updating queries and mutations with new properties from our hosted schema.

We need to update all affected queries and mutations with the affected property in our preflight, whether we’re adding, removing or updating one. Here are the steps to follow:

  1. Navigate to our GraphQL playground
  2. Click on “Schema” at the right of the screen
  3. Confirm that the necessary changes have been applied to the schema by reviewing the document (if changes are not present they will need to be actioned by the backend team)
  4. Note the object within which our desired change has been made
  5. Perform a global project search for the affected object key (you could limit this search to only the src/graphql directory and exclude the graphql/generated directory to declutter the results)
  6. Make the necessary updates to all the instances of they affected object keys (add/delete/move/rename etc) and save each file
  7. In your terminal cd into the root directory of your project and run the following command
npm run codegen
  1. Validate that the generated files have been successfully updated (there should be three in total; one for cypress fixtures, and two in the graphql/generated directory)
  2. There is a known issue for the imports in the newly updated graphql/generated/graphql.tsx file where codegen has not imported the functions from the correct packages. These need to be updated as follows for the time-being:
import * as ApolloReactCommon from '@apollo/react-common' => '@apollo/client';
import * as ApolloReactComponents from '@apollo/react-components' => '@apollo/client/react/components';
import * as ApolloReactHoc from '@apollo/react-hoc' => '@apollo/client/react/hoc';
  1. Confirm that the updates have been effected and are working as expected by finding them in the Apollo dev tools and network requests
  2. Implement necessary changes in our codebase to effect the desired query values or mutation results

Video demonstration of the above process