Quick Start: Gridsome + Craft CMS GraphQL API

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". Now, in the newest release (Craft 3.3), they've added an out-of-the-box GraphQL API which is perfect for pulling your content into a static site generator like Gridsome or Gatsby.

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 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-graphql
yarn 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 you're working in. 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
CRAFT_API_TOKEN=schemaAccessToken

That's it!

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.

If you have any comments/questions don't hesitate to leave a comment! I also love hearing when my articles were helpful to you, so leave a comment if these steps worked for you!