Setting Up a Headless JSS Project with GraphQL in Sitecore

Setting Up a Headless JSS Project with GraphQL in Sitecore

Headless development with Sitecore JSS offers powerful frontend flexibility while leveraging the robust content management capabilities of Sitecore. GraphQL enhances this by making content queries efficient, reducing API payload size, and improving performance. This guide walks you through creating a Sitecore JSS project with GraphQL from scratch, ensuring a smooth developer experience.

Prerequisites

Before getting started, ensure you have the following installed:

• Node.js (Latest LTS)
• Sitecore JSS CLI (npm install -g @sitecore-jss/sitecore-jss-cli)
• A Sitecore 10+ instance with JSS enabled
• A basic understanding of React and GraphQL

Step 1: Create a New JSS Project with GraphQL

jss create my-jss-app react --fetchWith=GraphQL
cd my-jss-app
jss setup

Step 2: Configure Sitecore for GraphQL

1. Modify scjssconfig.json to use the GraphQL endpoint:

{
"sitecoreInstance": "http://your-sitecore-instance",
"apiKey": "{YOUR-JSS-API-KEY}",
"graphQLEndpoint": "/sitecore/api/graph/edge"
}

1. Enable GraphQL in Sitecore:
   • Go to /sitecore/admin → GraphQL → Settings.
   • Ensure the JSS Schema is exposed.
   • Modify C:\inetpub\wwwroot\your-sitecore-instance\App_Config\Include\zzz.GraphQL.CORS.config to allow CORS for local development.

Step 3: Connected vs Integrated Mode

Connected Mode

• The JSS app runs locally and directly fetches data from Sitecore.
• Useful for rapid development without deploying to Sitecore.
• Requires JSS API key and proper GraphQL endpoint configuration.

Run your app in connected mode:

jss start:connected

Integrated Mode

• The JSS app is deployed inside Sitecore and fetches data from the same server.
• Ideal for production and fully integrated Sitecore environments.
• Requires deployment of JSS app using jss deploy.

Deploy and run in integrated mode:

jss deploy app --includeContent

jss start:integrated

Step 4: Query Sitecore Data with GraphQL

To test GraphQL queries, open http://your-sitecore-instance/sitecore/api/graph/edge/ui and run:

{
item(path: "/sitecore/content/Home") {
name
url
children {
name
url
}
}
}

Fetching Data in JSS Without Apollo Client

Modify your React component to fetch data using the native fetch API:

Here is the sample code file: https://github.com/krithviktrs/JSSReference/blob/main/SitecoreContent.js

Step 5: Rendering Contents Resolver vs Component GraphQL Query

JSS allows you to configure a Rendering Contents Resolver on each rendering to determine how data is serialized. The available resolvers include:

• Datasource Resolver – Serializes the rendering’s datasource item.
• Datasource Item Children Resolver – Serializes the children of the datasource item.
• Context Item Resolver – Serializes the context item instead of the datasource item.
• Context Item Children Resolver – Serializes the children of the context item.
• Folder Filter Resolver – Serializes the descendants of the datasource item, excluding folders.

With GraphQL, you can define the query and receive only the required data, reducing API payloads and improving performance. This is useful when:

• Your component needs more data than available in the datasource fields.
• You want to exclude unnecessary fields from the response.
• You prefer not to use client-side GraphQL libraries like Apollo.

Example: Using Component GraphQL Query Instead of Resolver

Modify the rendering component by adding a GraphQL query:

{
item(path: "/sitecore/content/Home") {
name
url
contextItem {
title
}
}
}

This approach enhances flexibility by fetching only the necessary fields.

Conclusion

By using GraphQL in Sitecore JSS, you enhance performance, reduce API payloads, and streamline content querying. Whether in connected or integrated mode, the setup provides flexibility and speed without requiring external GraphQL clients like Apollo.