Introducing the new Gatsby Source Strapi plugin

The updated version of this plugin supporting Strapi v4 and Gatsby Cloud has been released. Check it out here.

We know that many of you love using Strapi with Gatsby. It's a great match! Strapi can handle all your content workflows, and Gatsby makes that content shine by building super fast (dare I say blazing?) websites.

That's why we created the gatsby-source-strapi plugin. It helps you query Strapi content in Gatsby, and lets you benefit from all the Gatsby goodness, like their automatic image optimization.

But our plugin was built in 2018, which, in the Jamstack world, is ages ago. So after 250.000 downloads, 65 closed issues, and 55 code contributions, it was time for a change. That's why we're happy to release our work in a new major version.

What's new?

Both Strapi and Gatsby move fast and have recently released new versions and features. We have updated the plugin to let you benefit from the best and latest features of both products. This new release includes:

• Internationalization support

Strapi supports Internationalization since v3.6. Before this release, our Gatsby source plugin only fetched content in the default locale. Now you can specify which locales you want to fetch for every content type. You can finally build websites that are translated for all your audiences!

• Fixed dynamic zones support

Dynamic zones had become a common pain point when using Gatsby with Strapi. We have now changed their behavior to rely on the JSON type. No need to write complex GraphQL fragments anymore :)

• Support for Gatsby v3

The internal code of the plugin has been updated to work with Gatsby's latest major version. You can safely upgrade your Gatsby version and enjoy the speed boost.

• Support for arrays of images

Gatsby will now parse image fields, even if they come from an array of media fields, like a carousel. This means you can use the gatsby-plugin-image in even more places, and build more performant image-heavy pages.

• New README documentation

The source plugin's documentation was rewritten. It now features more examples for advanced configurations, like custom endpoints or authenticated requests.

Update your app to the new version

As this is a major release, there are a few breaking changes you need to make to enjoy the new version.

1. Update your Gatsby and Strapi versions

We recommend that you start by upgrading your frontend to Gatsby v3. If you're coming from the v2 version, you can follow Gatsby's official migration guide.

Then, make sure that your Strapi application is up to date as well. You want to have at least version 3.6, where we introduced internationalization. If your Strapi version is older, follow our docs on how to update Strapi.

2. Update the source plugin

Now that we're done with Gatsby and Strapi versions, it's time to update the actual source plugin. Inside your Gatsby frontend, open a terminal and run either of these commands:

Using Yarn

yarn add gatsby-source-strapi@latest

Using NPM

npm install gatsby-source-strapi@latest 

You should now see the 1.0.0 version in your package.json.

3. Rename contentTypes to collectionTypes

Strapi offers two content types: collection types and single types. To avoid any confusion, we renamed the contentTypes option to collectionTypes, since it doesn't handle single types. So you will need to make a small change in your gatsby-config.js file:

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-source-strapi`,
    options: {
      apiURL: `http://localhost:1337`,
      // Instead of contentTypes: [`article`]
      collectionTypes: [`article`],
      singleTypes: [`home-page`, `contact`],
    },
  },
];

4. Rewrite your dynamic zones queries

If you have tried using dynamic zones with Gatsby before, you may have written GraphQL queries that involved complex fragments. Instead, you can rewrite them to only query the dynamic zone field as a scalar:

{
  allStrapiPage {
    edges {
      node {
        id
        # contentSections is a Strapi dynamic zone
        # All its contents will be queried as JSON
        contentSections
      }
    }
  }
}

Get started with Strapi & Gatsby

We love working with Gatsby and are happy to make it easier to use for you. If you want an even faster way to get started with Strapi and Gatsby, you can check out our starters:

• Gatsby blog
• Gatsby catalog website
• Gatsby corporate website

We'll be updating these to use our new source plugin very shortly. Make sure you follow us on Twitter so you can find out when this happens.

In the meantime, enjoy the new plugin, and don't hesitate to give us your feedback on GitHub!