Integrated GraphQL in JSS Apps

With integrated GraphQL, the format of the route data returned for a specific component by the Sitecore Layout Service can be modified into the result of a GraphQL query.

Usage

When the Sitecore Layout Service renders a page, it returns a JSON representation of the layout of the page and the data for each component. Normally the component data is a set of fields from the Sitecore datasource item. Integrated GraphQL lets you re-shape this into a GraphQL query result.

Prerequisites

• Define a Sitecore GraphQL endpoint that has the schema you wish to query. Get this working first, and play with the schema using GraphiQL ($endpointUrl/ui) to ensure it works. Generally the endpoint should be defined using the JSS app's config patch file (stored under /sitecore/config in the JSS app, but can also be stored with Sitecore).
• Attach your JSS app to the GraphQL endpoint. On the JSS <app> definition, add a graphQLEndpoint property pointing to the url of the endpoint. xml <app name="MyJssApp" graphQLEndpoint="/sitecore/api/jssbasicapp" />

Sitecore-first Apps

Integrated GraphQL operates by storing the GraphQL query in the Component GraphQL Query field on the component's rendering item. For example the GraphQL sample app sets a query on /sitecore/layout/Renderings/JssBasicAppGraphQL/IntegratedPage.

The Open xGraph Browser button will open the GraphiQL query editor and prefill the current query value so that you can edit and test it. The query is not auto-saved back into Sitecore; copy and paste the modified query back when done.

When a layout request is received by Sitecore, if a component defines a GraphQL query that is not empty, the query is executed against the JSS app's graphQLEndpoint, in-process and the result replaces the normal rendering field values that would be returned.

Code-first (manifest-driven) Apps

In a code-first app the actual mechanism for the query is identical to a Sitecore-first application, but the GraphQL query to execute is provided on the JSS manifest and imported into the Sitecore item field.

To define an integrated GraphQL query for a component:

• Find the component's manifest definition (normally /sitecore/definitions/components/ComponentName.sitecore.js)

• Create a parallel .graphql file to store the query, e.g. /sitecore/definitions/components/ComponentName.sitecore.graphql

• Set the graphQLQuery property when defining the component, for example:

  import { readFileSync } from 'fs';
  
  const query = readFileSync(
    'sitecore/definitions/components/ComponentName.sitecore.graphql',
    'utf8'
  );
  
  export default manifest => {
      manifest.addComponent({
          name: "ComponentName",
          graphQLQuery: query
      });
  };
  

Using readFileSync to include the GraphQL query is recommended so the query file can be linted, but literal strings are also allowed. Parsed GraphQL query ASTs (using graphql-tag's gql helper) are not allowed.