Best practices and recommendations for using GraphQL in JSS apps
When using Sitecore GraphQL API endpoints, we recommend you follow some general best practices.
When you consume the GraphQL API from the front end, we recommend the following:
-
Separate your queries into
.graphqlfiles. Do not mix them with your code.-
This gives a good separation of concerns, and with a tool like
graphql-tag/loader, you can import the file in the same way as a JavaScript file. -
Statically analyzable queries make things easier to validate all your queries at build time, run a security whitelist, and do other common operations.
-
When this is not possible (for example, currently with Angular, you cannot customize the build to add the GraphQL loader), separate your queries into
.jsor.tsfiles that contain only queries, for example,mycomponent.graphql.tsfor Angular components.
-
-
Never use dynamic string-concatenated queries (with non-GraphQL variables in the query text). Query variables must always be GraphQL query variables.
-
This defeats whitelisting, static analysis, performance analysis, and is generally just a bad idea.
-
-
Take advantage of query batching:
-
One of the major advantages of GraphQL over REST is that because GraphQL is a protocol, it makes it possible to do some things REST cannot do.
-
Query batching makes it possible to automatically combine multiple queries (made within a short time span) into a single HTTP request.
-
-
Use tools to ensure your GraphQL queries are valid against the GraphQL schema, such as
eslint-plugin-graphql.-
This provides build-time safety that your query expressions are valid and will not break when run.
-
Use Sitecore GraphQL with GraphQL tooling
Many kinds of GraphQL tools (such as eslint-plugin-graphql to validate queries at build time, graphql-tools to create a disconnected mock GraphQL API, or ts-graphql-plugin to provide code completion of GraphQL in TypeScript) require a copy of your GraphQL Schema to execute correctly. In some cases, you can download this directly from a Sitecore instance to have a live schema. However, there is no live Sitecore instance in other cases, so you must have a static copy of the schema.
There are two main types of schema input:
-
A JSON-formatted schema. This is the result of an introspection query against the GraphQL API. This is what GraphiQL uses to give documentation in the browser, for example.
-
A schema-definition language schema. This is a text format that defines the schema in a readable format. You can download this by visiting
$endpointUrl/schemato get the content, then save it as a.graphqlfile.
Changes in the Sitecore setup (such as changing or adding templates) result in the GraphQL schema changing. When you use a static schema file, you must ensure it stays updated to avoid false validations.