Integrated GraphQL in JSS apps
With integrated GraphQL, the layout data format returned for a specific component by the Layout Service can be modified into the result of a GraphQL query. This means you can define a GraphQL query that defines the data you require to power a front-end component and then receive the data from that query as a property, such as props.fields for a React component. This gives you control over the data you receive, and the power of GraphQL if you require advanced data sources such as child items or CRM data.
The Sitecore Accelerate recipe Getting Component Specific Data contains additional context on component-specific data fetching, including what to consider when choosing a method to use.
In the Content Editor, an integrated GraphQL query is attached to a rendering in the GraphQL field Component GraphQL Query, as shown in the following two examples for Link List and Title components.
We recommend you use integrated GraphQL when:
-
Your component requires more data than just the datasource template fields in the GraphQL schema.
-
The datasource template contains extra fields that you do not want to render.
-
You do not want to have any client-side GraphQL libraries such as Apollo. Integrated GraphQL requires no additional dependency other than JSS.
We recommend you avoid using integrated GraphQL when:
-
The component uses only content template field data. The default layout data output is sufficient without requiring GraphQL.
-
Your GraphQL query is not performant. For example, it aggregates multiple REST API calls behind the scenes. Integrated GraphQL blocks the app's rendering until all layout queries have been completed.
We recommend you use Connected GraphQL instead to defer longer running queries until after the initial layout is rendered.
-
The component has to issue additional GraphQL queries in response to state changes. Integrated queries run only when the layout data is loaded.
-
The component has to run mutations (updates) or subscriptions (real-time data). In integrated GraphQL, you can only run queries.
-
You need to use pagination or cursors (for example,
pageInfo.endCursor).Integrated GraphQL queries are executed at publish time against the preview endpoint. Because cursor values are dynamic and endpoint-specific, the same query can return different cursors at publish time and at runtime.
We recommend you use Connected GraphQL instead instead for this use case.
When using integrated GraphQL queries, for the default and jss layout service configurations, values for $datasource, $contextItem, and $language are automatically injected.