Quick Start: Gridsome + GraphQL API = Craft CMS Headless

Craft CMS is a fantastic CMS that just got a whole lot easier to use with Gridsome (or any static site generator). The Craft team appears to have noticed the trend of people starting (or hoping) to use Craft as a "Headless CMS." In Craft 3.3 they added an out-of-the-box GraphQL API which is perfect for pulling your content into a static site generator like Gridsome or Gatsby to make Craft CMS Headless.

Let's jump right into how to use the new GraphQL API to integrate with Gridsome.

5 Steps

1. Set up your Craft installation

To use the GraphQL API, you need to have a Craft installation running 3.3+ and licensed as Craft Pro*. If you have a current Craft installation and are running a lower version than 3.3, you can update by changing the craftcms/cms version in your composer.json to "^3.3.0" and then running composer update.

*In development you can use the Craft Pro trial

2. Create a schema

Schemas are the way you can access your Craft data through GraphQL. Each schema comes with an access token, that you provide to Craft with your GraphQL query to identify which schema to pull data from. Each schema has its own permissions set, so you can limit access to types of data based on which schema they're allowed querying.

For this step, head over to Control Panel > GraphQL > Schemas, then create a new schema, give it the proper data permissions and copy the access token.

3. Set up a route to your GraphQL API.

Add the following route to routes.php. This will allow you to send GraphQL queries to example.com/api.

// routes.php
return [ 'api' => 'graphql/api' ];

4. Set up your Craft API as a Gridsome data source

Assuming you have a working Gridsome installation up and running, the actual integration of your CMS data into the Gridsome GraphQL store is extremely simple!

First, you'll need to install the Gridsome source plugin for GraphQL:

npm install @gridsome/source-graphqlyarn add @gridsome/source-graphql

Then, add the following to your gridsome.config.js:

// gridsome.config.js
{ 
 use: '@gridsome/source-graphql',
 options: {
 url: process.env.CRAFT_API_URL,
 fieldName: 'craft',
 typeName: 'craft',
 headers: {
 Authorization: `Bearer $​{process.env.CRAFT_API_TOKEN​}`,
 }
 }
}

This gets us 90% of the way to a working integration, but it still won't work quite yet! You may have noticed the references to process.env variables for our API URL and token. This is what we'll set up in the next - and final - step.

5. Create a .env in your Gridsome project

If you're familiar with Craft, you've seen a .env file before. .env contains all of your "environmental variables": information specific to the environment in which you're working. Gridsome takes this same approach to environmental variables, so we're going to create (or add to) a .env file in our Gridsome project.

# .env - in Gridsome project

CRAFT_API_URL="http://example.test/api"

Now run gridsome develop and you're off to the races! You should be able to query your Craft data from anywhere within Gridsome now. To test everything head over to the GraphQL playground and try sending the following request:

query {
 craft { ping }
}

If everything's working properly, the ping field should return pong.

Congratulations! You have now activated headless mode. If you have any comments/questions don't hesitate to reach out. I also love hearing when my articles were helpful, so let me know if these steps worked for you!