Use GraphQL to fetch component-level data in JSS Next.js apps

Version:

The Next.js sample app supports component-level data fetching enabling querying GraphQL endpoints at the component level. Following the code-first developer workflow, you can run GraphQL component-level queries only in connected mode.

Danger

Do not include secrets or sensitive information in component-level getStaticProps and getServerSideProps functions. These functions are included in the client-side bundle. Also included in the client bundle are any imports the functions depend on, even if the client-side code does not use the imports.

This does not affect page-level getStaticProps and getServerSideProps functions.

In the code, it is a good practice to have strong types connected to GraphQL types defined in the Sitecore GraphQL Edge endpoint. The application uses the library graphql-let and GraphQL introspection data to achieve this.

The sample app provides a GraphiQL interface for exploring the schema and testing queries. By default, the interface can be accessed using ${SITECORE_API_HOST}/sitecore/api/graph/edge/ui?sc_apikey=${SITECORE_API_KEY}. This interface is helpful if you want to determine what GraphQL types can be used by your components.

Note

The graphql-let library provides the same information about types in the corresponding .graphq.d.ts files.

To use component-level data fetching with GraphQL:

In a GraphQL-ConnectedDemo.graphql file, define a GraphQL query following the Connected Demo query example.

The library graphql-let generates a file GraphQL-ConnectedDemoQuery.graphql.d.ts.

In your component file, add the following import statement:

import {
  constants,GetServerSideComponentProps,
  GetStaticComponentProps,  useComponentProps,
  GraphQLRequestClient} from '@sitecore-jss/sitecore-jss-nextjs';

If needed, update your introspection data to have access to the latest GraphQL types.

Import your GraphQL query:

import {
  ConnectedDemoQueryDocument,
  AppRoute,
  Item,
  GraphQlConnectedDemo as GrapQLConnectedDemoDatasource,} from './ConnectedDemoQuery.graphql';

In your component, define getStaticProps or getServerSideProps functions. In this example, we implement getStaticProps. Because GraphQL does not work in disconnected mode, you must exit the function if the app runs in disconnected mode. You must also create a new GraphQL client using the GraphQLRequestClient class. For example:

 export const getStaticProps: GetStaticComponentProps = async (rendering, layoutData) => {
    if (process.env.JSS_MODE === constants.JSS_MODE.DISCONNECTED) {    
        return null;  
    }
    const graphQLClient = new GraphQLRequestClient(config.graphQLEndpoint, {    
      apiKey: config.sitecoreApiKey,  
    });
 }

Perform the request and return the result:

export const getStaticProps: GetStaticComponentProps = async (rendering, layoutData) => {
  if (process.env.JSS_MODE === constants.JSS_MODE.DISCONNECTED) {
    return null;  
  }
  const graphQLClient = new GraphQLRequestClient(config.graphQLEndpoint, {
    apiKey: config.sitecoreApiKey,
  });
  const result = await graphQLClient.request<GraphQLConnectedDemoData>(MyQuery, {
    datasource: rendering.dataSource,
    contextItem: layoutData?.sitecore?.route?.itemId,
    language: layoutData?.sitecore?.context?.language,
  });
  return result;
};

In your component function, you can access the resulting data using the useComponentProps hook:

const GraphQLConnectedDemo = (props: StyleguideComponentProps): JSX.Element => {
  const data = useComponentProps<GraphQLConnectedDemoData>(props.rendering.uid);
  // implement your component
}

Implement a strategy for showing content in editing mode. You can use the Sitecore context to render static data. Alternatively, to see master database data in editing mode, instantiate the GraphQL client with the endpoint URL for the Content Management instance.

Note

If you omit this step, the application displays the same data in editing mode as it does for site visitors because the Content Delivery URL endpoint serves from the web rather than the master database.

To render placeholder markup in your component:

import { useSitecoreContext} from '@sitecore-jss/sitecore-jss-nextjs';

const MyComponent = () => {
  const { sitecoreContext } = useSitecoreContext(); 
  // define some stub data
  if (sitecoreContext.pageEditing) {
    return (
      <div>
       This would usually render dynamic GraphQL data. This stub is used only for editing mode.
      </div>
    );
  }
  // ... rest of the component  
}

To use a different endpoint for data fetching, check if the component is in preview/edit mode and switch the URL accordingly. In this example, we assume you assigned your GraphQL editing URL to an environment variable named EDITING_GQL_ENDPOINT.

export const getStaticProps: GetStaticComponentProps = async (rendering, layoutData, context) => {

  if (process.env.JSS_MODE === constants.JSS_MODE.DISCONNECTED) {
    return null;  
  }
  
  const {preview} = context;
  const graphQLEndpoint = preview ? process.env.EDITING_GQL_ENDPOINT : config.graphQLEndpoint;

  // if using getServerSideProps, you can use the Sitecore context from the layoutData
  // const graphQLEndpoint = layoutData.sitecore.context.pageEditing ? process.env.EDITING_GQL_ENDPOINT : config.graphQLEndpoint;
  
  const graphQLClient = new GraphQLRequestClient(graphQLEndpoint, {
    apiKey: config.sitecoreApiKey,
  });

  const result = await graphQLClient.request<GraphQLConnectedDemoData>(MyQuery, {
    datasource: rendering.dataSource,
    contextItem: layoutData?.sitecore?.route?.itemId,
    language: layoutData?.sitecore?.context?.language,
  });

  return result;
};

Note

The sitecoreApiKey can differ between endpoints so make sure you switch it using a logic similar to switching the endpoint.

For a more complex example of using GraphQL queries in components, in the nextjs-styleguide addon template, see the component defined in the /src/components/graphql/GraphQL-ConnectedDemo.dynamic.tsx.

If you have suggestions for improving this article, let us know!