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 withJSS
(Follow my guide How to setup JavaScript Services for Sitecore)node.js
v6.9 or laternpm
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. ThePage Components
items are standard folder items to group the content of a page.
- Open
/src/app/components/Navigation/index.js
and change therootPath
(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 changerootPath
,startItem
anddatabase
in thewebsite
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 athttp://{HOSTNAME}
. Also the experience editor is now fully functional.
- Instead of
jss deploy package
you can also runjss 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.