Developing a first-class CMS integration for Gatsby Cloud

This guide will walk you through the steps to becoming a first-class technology integration with Gatsby Cloud, including all the technical requirements that need to be met, and help you get the process started.

NOTE: Any first-class integration for Gatsby Cloud requires a technical partnership with Gatsby. This helps us support our partners’ work and notify them of potentially overlapping work being done in the open source community. It’s an important first step, so if you have not already registered as a technical partner, please go to the Gatsby partner portal and sign up. We look forward to learning more about who you are and what you are building.

What are you building?

A first-class integration is a technology that works seamlessly with Gatsby Cloud. The exact requirements for a first-class integration vary based on the type of integration. Gatsby Cloud currently supports two kinds of first-class integrations, data source (CMS) and infrastructure (hosting). Gatsby also sees potential for integrations with services (e.g. authentication, image hosting, form handling, search, etc), design tools, and other web related technologies. This guide will help you build a first-class data source integration.

If you fall into one of the other integration categories, please apply for a partnership or contact partners@gatsbyjs.com and let us know what you want to build. The possibilities are endless!

Building a first-class data source integration

Building a quality Gatsby source plugin is only the first step in this process. To help keep frustrations low and productivity high, being a first-class integration also means writing thorough documentation to help users. Here is everything you will need to build and support:

• Step 1: Source plugin
• Step 2: CMS Gatsby Builds integration (webhook)
• Step 3: CMS Gatsby Preview integration (webhook + preview button)
• Step 4: Quick Connect (optional)
• Step 5: Quick Start (optional)
• Step 6: Documentation
  • Source plugin docs
  • Source Starter
  • Gatsby Cloud docs
  • Data sourcing guide
  • Gatsby Cloud guide
  • Willit.build benchmarks

Step 1: Source Plugin (required)

Before progressing to the specific checklist items, it is necessary to have a source plugin that does the following:

1. Fetches data from your CMS and exposes that data via Gatsby’s GraphQL schema
2. Support incremental data fetching (Has the ability to create, update, and delete data based on CMS content changes)

For assistance with both, refer to the Creating a Source Plugin guide which gives code examples and a high level overview. For a more detailed walk-through, check out the Source plugin tutorial.

Incremental data fetching is a critical part of keeping build times blazing fast. In Gatsby Cloud we expect first-class plugins to be able to drive <5 second Preview updates and <10 second Incremental Builds on a site with 8192 pages. These metrics are measured by Willit.build benchmarks which will be discussed below.

Once your source plugin meets these requirements, you may progress to Step 2 and the rest of the checklist. Woo hoo!

Step 2: Builds Integration (required)

Whenever content is created, updated, or deleted in the CMS, Gatsby Builds need to be notified in order to rebuild your Gatsby site and ship changes to production. This is done from the CMS using webhooks to trigger builds. Your CMS must have a way for users to configure webhooks to be triggered on CRUD events for published data.

Step 3: Preview Integration (required)

Gatsby Preview’s key value is delivering a preview experience for a headless CMS that is similar to the features built into a traditional CMS. Specifically, a traditional CMS often has a “Preview” button that allows the editor to preview current content changes before publishing. These changes are shown in context to gain an understanding of what the content will look like after publishing.

To deliver a first-class experience, an extension or widget must be created that will allow certain content types to be previewed directly in Gatsby Preview. This provides a seamless editing experience and gives content editors that great preview functionality that they’ve come to expect.

Please see the “Creating an Extension or Widget to Preview Content” guide for more info.

Step 4: Quick Connect (optional but recommended)

Gatsby Cloud is optimized to be the best place for creating, updating and deploying sites built with Gatsby. However, integration between Gatsby Cloud and a CMS typically requires quite a bit of configuration. Gatsby needs to have credentials and an API endpoint to fetch data, and the CMS needs to be configured with multiple webhooks and the Gatsby Preview URL. Enabling Quick Start functionality allows this to all happen with little input from the user. This creates a more seamless and enjoyable experience, and we highly recommend this optional step.

Quick Connect requires your CMS integration to have an API with which we can share and fetch the appropriate data and the ability to authorize via OAuth. The development work to support a new CMS is currently completed by the Gatsby team. When you are ready to support this feature, please let partners@gatsbyjs.com know and provide us with any documentation and JavaScript client libraries that would be helpful.

Step 5: Quick Start (optional)

Supporting this feature also allows you to place a starter(s) on the Gatsby Cloud /get-started page for increased visibility. This enables a flow in which a user of Gatsby Cloud can pick a starter from which a new git repo, Gatsby site, and CMS are provisioned and seeded with sample content, e.g. a blog or portfolio.

NOTE: All starters submitted for use in Quick Start are required to use the BSD Zero Clause License or similar OSI aproved license with Gatsby approval. More Info

Quick Start requires supporting Quick Connect and a means to import content. Ideally, an API should be provided that will allow the CMS to be automatically provisioned and content created. Please see the “Importing Content” guide for more info.

Step 6: Documentation (required)

Robust documentation is necessary to help people learn about using your integration, and to cover the different scenarios they will encounter while working with it. Here is the list of documentation required for a first-class technology integration. Fortunately, we have docs designed to help you create great documentation, quickly!

Source plugin docs

This documents the configuration options and use of the source plugin. Here is a source plugin README template and plugin docs example to give you some ideas.

Source starter

Starters help devs create a new Gatsby site quickly. They also provide working examples for config and code to help devs learn about and play with your source plugin. Check out our Creating a Starter doc for more details.

Gatsby Cloud docs

These describe how to integrate your CMS with the Gatsby Cloud. We have a detailed guide on How to Create Gatsby Cloud Docs. For an example of a well-written guide, check out the Strapi docs.

Data sourcing guide

Your “Sourcing data from X” guide will be a detailed walk through on how to integrate your source plugin into a Gatsby site. See How to Write a Sourcing Guide and this data sourcing example for guidance around creating this documentation.

Gatsby Cloud guide

Gatsby Cloud guides are non-technical documentation designed to give high level information to engineering managers and executives. See How to write a Gatsby Guide for detailed information and Contentful’s guide for a finished example.

Willit.build benchmarks

These benchmarks are very important. Beyond being a valuable resource for those looking to build projects with Gatsby + your CMS, they also act as performance tests. These Willlit.build benchmarks help us identify issues and optimize performance in Gatsby Cloud and in source plugins. Check out our instructions for creating a Willit.build benchmark to get started.

What’s Next?

Once you’ve met all the technical and documentation requirements above, then congratulations! If you have not yet, please apply to become an official partner, otherwise email partners@gatsbyjs.com to let us know you are ready to be considered for first-class integration status. We will review and test the source plugin, documentation, and anything else submitted, providing feedback as needed. Once everything is reviewed and ready to go, we will begin the process of deploying the new first-class integration. We’re so glad you’re joining us.