Strapi Source Plugin

Source plugin for pulling documents into Gatsby-v4 from the Strapi-v4 graphql API.

This plugin depends on Strapi's GraphQL introspection, which enables a lot of missing features in the plugin released by Strapi (i.e. grapqhl unions, builds failing due to missing data in fields, etc), but it also requires introspection to be enabled in production (read below how to enable it).

Deep nesting and dynamic zones
Relationships with other collection types (all types, one-way, two-way)
Gatsby Cloud CMS previews & incremental builds
Build caching and only fetching changes since last build
Support for images in markdown / richtext fields
No more failing builds do to missing content in fields

🚀 Installing the plugin

This version of gatsby-source-strapi is only compatible with Strapi v4 and uses the graphql api of Strapi.

# Using Yarn
yarn add gatsby-source-strapi@relate-app/gatsby-source-strapi

# Or using NPM
npm install --save gatsby-source-strapi@relate-app/gatsby-source-strapi

🔥 Setting up the plugin

You can enable and configure this plugin in your gatsby-config.js file.

Basic usage

// In your gatsby-config.js
plugins: [
  {
    resolve: 'gatsby-source-strapi',
    options: {
      apiURL: 'http://localhost:1337',
      collectionTypes: ['Article', 'User'],
      singleTypes: ['Home Page', 'Contact'],
      // Extract images from markdown / richtext fields.
      inlineImages: {
        typesToParse: {
          Article: ['body'],
          ComponentBlockBody: ['text'],
        },
      },
      // Only include specific locales.
      locale: ['en', 'sv'], // defaults to 'all'
      // Include drafts in build.
      preview: true, // defaults to false
      // Use application token.
      token: 'xxx',
      // Add additional headers.
      headers: {},
      // Enable/disable cache.
      cache: false,
    },
  },
];

Production Requirements

Enable introspection of the schema in Strapi on the server by adding this snippet in ./config/plugins.js:

module.exports = ({ env }) => ({
  // ...,
  graphql: {
    config: {
      endpoint: "/graphql",
      apolloServer: {
        introspection: true,
      },
    },
  },
});

Internationalization support

Strapi now supports internationalization. But by default, this plugin will only fetch data in the default locale of your Strapi app. If your content types are available in different locales, you can also pass an entity definition object to specify the locale you want to fetch for a content type. Use the all value to get all available locales on a collection type, an array or comma separated list of locale codes will fetch only these locales.

Relationship support

Relationships to other collections both in collection fields and components are automatically connected to each other and included as a field if the node being linked to is included in the collectionTypes in your gatsby-config.

Draft content

Strapi now supports Draft and publish, which allows you to save your content as a draft and publish it later. By default, this plugin will only fetch the published content.

But you may want to fetch unpublished content in Gatsby as well. To do so, find a content type that has draft & publish enabled, and add an entity definition object to your config. Then, set preview to true in gatsby-config.

Authenticated requests

Strapi's Roles & Permissions plugin allows you to protect your API actions. If you need to access a route that is only available to a logged in user, you can provide your credentials (token) so that this plugin can access to the protected data.

Refresh content locally

Set ENABLE_GATSBY_REFRESH_ENDPOINT=true in your node env for gatsby, then you can add the a webhook in Strapi pointed towards http://localhost:8080/__refresh and see content update when saving it locally.

See more about this feature here: https://www.gatsbyjs.com/docs/refreshing-content/

Parent relationship

You can now add a relationship in Strapi and have it hook up parent relationship automatic in Gatsby, make sure it's a singular relationship and using the field name "parent" for it to work. This feature can be used to build tree structured url patterns.

Querying data

You can query Document nodes created from your Strapi API like the following:

{
  allStrapiArticle {
    edges {
      node {
        id # Gatsby uuid
        strapiId # all types get this field
        title
        content
      }
    }
  }
}

You can query Document nodes in a chosen language:

{
  allStrapiArticle(filter: { locale: { eq: "en" } }) {
    edges {
      node {
        id
        title
        content
      }
    }
  }
}

To query images you can do the following:

{
  allStrapiArticle {
    edges {
      node {
        id
        singleImage {
          file {
            publicURL
          }
        }
        multipleImages {
          file {
            publicURL
          }
        }
      }
    }
  }
}

To query inline images for a markdown / richtext field named "text" you can do the following:

To replace in markdown / richtext use the base returned from the file and create a custom renderer to match the url on the image with the base.

{
  allStrapiArticle {
    edges {
      node {
        id
        text
        text_images {
          base
          publicURL
        }
      }
    }
  }
}

This version also adds support for union types (most commonly used on dynamic component fields). All types in the gatsby schema gets prepended with the Strapi namespace. To query for dynamic field types you can do the following:

{
  allStrapiArticle {
    edges {
      node {
        id
        blocks {
          ... on StrapiComponentBody {
            body
          }
          ... on StrapiComponentImage {
            image {
              file {
                publicURL
              }
            }
          }
        }
      }
    }
  }
}

kesslerdev/gatsby-source-strapi