How to setup GraphQL for Sitecore 9

The first time I heard about GraphQL was two years ago. I was fascinated by the idea that a frontend developer can write queries exactly as they need it for every specific purpose. But when I first started setting up a GraphQL endpoint for Sitecore I realised very fast, that much more is needed than just setting up an endpoint like it is needed for REST.

That’s why I was even happier, when Kam Figy in his session “Uber-modern APIS for Sitecore” at the SUGON 2018 in Berlin told that they already implemented GraphQL in the Sitecore JavaScript Services (JSS).

And so I found myself setting up GraphQL on my experimental environment just a day after I arrived home from the SUGCON. Below you find everything it took me to start GraphQL and a very basic sample app.

Prerequisites

• Sitecore 9 installation with JSS (Follow my guide How to setup JavaScript Services for Sitecore)
• node.js v6.9 or later
• npm v5.7 or later

Make sure you did set <compilation debug=”true”> in the Web.config as described in the guide How to setup JavaScript Services for Sitecore.

Also make sure that you set * for AllowedControllers and CORS Origins in your API Key item (this should only be done for development, for production you should set appropriate values in here).

Configure GraphQL Endpoint

Sitecore and JSS don’t come with an already defined GraphQL endpoint. Therefore we first need to configure that endpoint. For that we will use the offical GraphQL sample app.

Open a command window in admin mode. Then run the following scripts. They will create an example app for a React application with GraphQL

npm install -g @sitecore-jss/sitecore-jss-cli
jss create HERE-NAME-OF-YOUR-APP basic-sample-react-graphql
cd HERE-NAME-OF-YOUR-APP
jss setup

Now the script will ask for the following three inputs:

• Full path to sitecore website folder (eg. c:\dev\sitecore\Website)
• Sitecore host name (eg. http://sitecore9)
• API Key (See how to create the API Key in this blogpost)

After you entered this data run the following scripts

jss deploy config
jss deploy package

jss deploy config will copy the file at /sitecore/config from your frontend repository example to /App_Config/Include/zzz in your website root.

jss deploy package will build and bundle the frontend repository and deploy the bundle to /App_Config/Include/zzz. Also it will create the needed item structure in you Sitecore Content Tree.

Test your GraphQL endpoint

Now you can open the GUI interface to build and test your GraphQL. To find out the correct URL open the .config file in /sitecore/config in your GraphQL sample app. Look for this part:

Here you see that the url for the GraphQL endpoint is defined as /sitecore/api/jssbasicapp.

Open this url in the browser http://{HOSTNAME}/{GRAPHQL-ENDPOINT}/ui?sc_apikey={API-KEY}. You should get the following interface. In there you can now write and test your GraphQL queries.

Test the GraphQL sample app

• Setup a small content tree inside the root of your javascript application inside sitecore. Use /sitecore/templates/NAME-OF-YOUR-APP/NAME-OF-YOUR-APP Route as the template for your page items. The Page Components items are standard folder items to group the content of a page.

• Open /src/app/components/Navigation/index.js and change the rootPath (See line 10 in the following example) so that it matches the page structure you just created.

• Open /App_config/Sitecore.config in your website root and change rootPath, startItem and database in the website site specification so that it matches the page structure you created (Or better you do the changes with a patch config).

• Open a command window with admin rights in your GraphQL sample app. Run jss deploy package. Your first JSS react app with GraphQL is now ready at http://{HOSTNAME}. Also the experience editor is now fully functional.

• Instead of jss deploy package you can also run jss start:connected to run the GraphQL sample app in development mode with connection to sitecore backend.

What’s next?

Now you are ready to start building react components with GraphQL connection to your Sitecore backend. Please leave some claps and comment with your experiences and thoughts about this new approach to Sitecore development.

For a detailed guide about GraphQL check out graphql.org.

Or check this API Documentation for the Sitecore GraphQL implementation.