gatsby-source-strapi
Source plugin for pulling documents into Gatsby from a Strapi API.
⚠️ This version of
gatsby-source-strapi
is only compatible with Strapi v3 at the moment. We are currently working on a v4 compatible version.
Installing the plugin
# Using Yarn
yarn add gatsby-source-strapi
# Or using NPM
npm install --save 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`,
queryLimit: 1000, // Defaults to 100
collectionTypes: [`article`, `user`],
singleTypes: [`home-page`, `contact`],
},
},
];
Advanced usage
Custom endpoint
By default, we use the pluralize module to deduct the endpoint that matches a collection type. You can opt out of this behavior. To do so, pass an entity definition object with your custom endpoint.
// In your gatsby-config.js
plugins: [
{
resolve: `gatsby-source-strapi`,
options: {
apiURL: `http://localhost:1337`,
collectionTypes: [
{
name: `collection-name`,
endpoint: `custom-endpoint`,
},
]
},
},
];
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.
// In your gatsby-config.js
plugins: [
{
resolve: `gatsby-source-strapi`,
options: {
apiURL: `http://localhost:1337`,
collectionTypes: [
// Fetch all locales for collection-name
{
name: `collection-name`,
api: { qs: { _locale: `all` } }
},
// Only fetch english content for other-collection-name
{
name: `other-collection-name`,
api: { qs: { _locale: `en` } }
},
// Combined with a custom endpoint
{
name: `another-collection-name`,
endpoint: `custom-endpoint`,
api: { qs: { _locale: `en` } }
},
]
},
},
];
For single types, the all
value will not work, since single type queries do not return an array. If you want a single type to be available in different locales, add several entity definition objects for that same single type. The source plugin will merge them together, so you can access the right locale in your queries using the locale
filter.
// In your gatsby-config.js
plugins: [
{
resolve: `gatsby-source-strapi`,
options: {
apiURL: `http://localhost:1337`,
singleTypes: [
{
name: 'single-type-name',
api: {
qs: {
_locale: 'en'
}
},
},
{
name: 'single-type-name',
api: {
qs: {
_locale: 'fr'
}
},
},
],
},
},
];
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, use the query string option to specify the publication state API parameter.
// In your gatsby-config.js
plugins: [
{
resolve: `gatsby-source-strapi`,
options: {
apiURL: `http://localhost:1337`,
collectionTypes: [
{
name: 'collection-name',
api: {
qs: {
// 'preview' fetches both draft & published content
_publicationState: 'preview',
}
}
}
],
},
},
],
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 so that this plugin can access to the protected data.
// In your gatsby-config.js
plugins: [
{
resolve: `gatsby-source-strapi`,
options: {
apiURL: `http://localhost:1337`,
collectionTypes: [`collection-name`],
loginData: {
identifier: '',
password: '',
},
},
},
];
Querying data
You can query Document nodes created from your Strapi API like the following:
{
allStrapiArticle {
edges {
node {
id
title
content
}
}
}
}
You can query Document nodes in a chosen language
Make sure to add api.qs._locale
to your strapi configuration in gatsby-config.js
(see example above)
{
allStrapiArticle(filter: { locale: { eq: "en" } }) {
edges {
node {
id
title
content
}
}
}
}
To query images you can do the following:
{
allStrapiArticle {
edges {
node {
id
singleImage {
localFile {
publicURL
}
}
multipleImages {
localFile {
publicURL
}
}
}
}
}
}