Introspecting the GraphQL schema in JSS Next.js apps

Current version: 19.x

GraphQL is strongly typed. The GraphQL schema defines the data types available from an endpoint - queries, mutations, and 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 GraphQL strong types available in the front-end application.

The JSS Next.js application uses the graphql-let package 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:

    RequestResponse
    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 values defined in src/temp/config.js, a file generated when you start your sample app for the first time.

Do you have some feedback for us?

If you have suggestions for improving this article,