Add GraphQL Edge Caching to Contentful

Grafbase is the easiest way to extend and cache existing APIs and add custom code that lives next to the user at the edge.

Contentful charges a premium for enabling caching by becoming a paid (enterprise) customer. With Grafbase we can add the Contentful GraphQL Content API as a data source that you can use to fine-tune caching.

The Contentful GraphQL API comes with queries to fetch content from your Contentful space using the schema built using the content models you define.

Get started locally

Begin by creating a new Grafbase project locally using the CLI:

npx grafbase init --template graphql-contentful

💡

You must run the command above inside your web or mobile app directory so you can later connect Grafbase to GitHub to deploy automatically.

Next, open the file grafbase/grafbase.config.ts and make any adjustments. By default, Grafbase will:

Set a maxAge to 60 seconds for the Query type
Set staleWhileRevalidate to 60 seconds
Add Contentful as a data source to the Grafbase API

import { g, connector, config } from '@grafbase/sdk'

const contentful = connector.GraphQL({
  url: g.env('CONTENTFUL_API_URL'),
  headers: (headers) => {
    headers.set('Authorization', `Bearer ${g.env('CONTENTFUL_API_TOKEN')}`)
  }
})

g.datasource(contentful, { namespace: 'Contentful' })

export default config({
  schema: g
})

💡

The template above uses namespacing so that other APIs you connect with Grafbase Edge Gateway don't conflict. You will need to update your client application queries with the additional nesting and renamed types. You can opt out of this by removing { namespace: 'Contentful' }.

If you'd prefer not to set the Authorization header you can instead forward the client request header to Contentful through Grafbase:

const contentful = connector.GraphQL({
  url: g.env('CONTENTFUL_API_URL'),
  headers: (headers) => {
    headers.set('Authorization', { forward: 'Authorization' }
  }
})

Now make sure to add your Contentful API URL (and optional API KEY) to grafbase/.env:

CONTENTFUL_API_URL=

# Only if you set the Authorization header with a static value
# CONTENTFUL_API_TOKEN=

Finally, run the Grafbase development server by using the command below:

npx grafbase dev

You now have a GraphQL API running locally that acts as a proxy to Contentful! 🎉

You can execute any GraphQL query or mutation you normally would with Contentful using the new endpoint: http://127.0.0.1:4000/graphql.

💡

Make sure you update any queries to use the namespace contentful if you kept that inside the configuration.

Grafbase Pathfinder can be found at http://127.0.0.1:4000 where you can explore the Grafbase Edge Gateway API and schema.

💡

Make sure to commit the grafbase folder with the rest of your application.

Deploy to Production

You can continue to use the Grafbase CLI when building locally to proxy your Contentful API but you will need to deploy to production to take advantage of GraphQL Edge Caching.

Follow these steps to deploy to production:

Signup for an account at grafbase.com
Visit grafbase.com/new to create a new project
Connect and deploy your application where the grafbase was added
Make sure to add your CONTENTFUL_API_URL (and optional CONTENTFUL_API_TOKEN) when deploying
Update your host (Netlify, Vercel, Fly, etc.) with the new GraphQL API endpoint that Grafbase supplied for your new project.

That's it!

Grafbase is programmed to autonomously deploy a fresh gateway each time it identifies a change to grafbase/grafbase.config.ts. Consequently, if you need to adjust any cache settings, including parameters like maxAge, staleWhileRevalidate, and mutationInvalidation, you’re free to do so.

Grafbase will handle the rest of the process seamlessly. We'll explore extending the Contentful Content API with custom fields in another post.