Introspecting the GraphQL schema in JSS Next.js apps

Abstract

Understanding and using the GraphQL schema in a JSS Next.js application

GraphQL is strongly typed. The GraphQL schema defines the data types available from an endpoint - queries, mutations, directives.

As these data types are implemented server-side, front-end developers must use tools that help them understand the schema to write efficient queries. Such tools use the GraphQL introspection system and provide introspection data. Introspection data describes all the types available for querying.

The Sitecore instance provides an interface for exploring the schema, and testing queries at ${SITECORE_API_HOST}/sitecore/api/graph/edge/ui?sc_apikey=${SITECORE_API_KEY}. You can access the introspection data in the Docs tab of the interface.

To write type-protected code with rich IDE assists, front-end developers need these GraphQL strong types available in the front-end application.

The JSS Next.js application uses graphql-let to generate TypeScript typings based on introspection data from a GraphQL schema. The introspection data is located in the file src/temp/GraphQLIntrospectionResult.json .

Update introspection data

When you alter item templates related to the site, your locally stored introspection data becomes out of sync with the information in your Sitecore instance.

To update the data:

  • In the root directory of your Next.js application, run:

    jss graphql:update 

This calls a script scripts/fetch-graphql-introspection-data.ts which fetches fresh introspection data from your defined GraphQL endpoint and updates the file.

The script uses the graphQLEndpoint and sitecoreApiKey defined in src/temp/config.js, a file generated when you start your sample app for the first time.