The Prismic Gatsby source plugin

Prismic no longer recommends the gatsby-source-prismic-graphql plugin

With recent changes to Gatsby, Prismic no longer recommends the gatsby-source-prismic-graphql plugin that this documentation uses. Read more about the future of Prismic and Gatsby. We highly recommend using the gatsby-source-prismic instead. The documentation for this plugin can be found in the plugin's github README.

We will leave this documentation here for now, but will change it in the future when we determine the best approach for Prismic & Gatsby.

You can easily integrate a Gatsby project with Prismic using the gatsby-source-prismic-graphql plugin. This article will show you how to install and configure it, as well as explaining why it's our recommended plugin.

gatsby-source-prismic-graphql

This plugin works like any other Gatsby plugin. You install it using yarn or npm (as shown below), and then you go to the gatsby-config.js to configure it. We're going to go over an example of this further below in this article.

Advantages of this plugin?

The gatsby-source-prismic-graphql can be your choice for those reasons:

  • Has out-of-the-box support for the Prismic Preview feature
  • Provides easy configuration for dynamic page generation
  • Multiple language support

Note: The useStaticQuery hook is not yet supported in this plugin. Instead you can use the StaticQuery component. Learn more about it here.

Example plugin configuration

To get started using it in your Gatsby project, you need to install the plugin:

Copy
npm install @prismicio/gatsby-source-prismic-graphql

or

Copy
yarn add @prismicio/gatsby-source-prismic-graphql

Then add this configuration to your gatsby-browser.js to make the Link Resolver work (Learn more about the Link Resolver):

Copy
const { registerLinkResolver } = require('@prismicio/gatsby-source-prismic-graphql')
const { linkResolver } = require('./src/utils/linkResolver')

registerLinkResolver(linkResolver)

Finally, in our gatsby-config.js we define the plugin configuration. Some key information for this example is that we are going to dynamically generate pages for each language of the documents of the type Post and the type Article. (NOTE: All of these values will change when developing your project. This configuration is merely for example purposes).

Copy
{
  resolve: '@prismicio/gatsby-source-prismic-graphql',
  options: {
    repositoryName: 'your-repo-name',
    defaultLang: 'en-us',
    langs: ['en-us', 'fr-fr'],
    accessToken: 'MC5Yb1NHZHhJQUFNTFd5VUlB.F3xK77-977-9Me-_vUfvv73vv70',
    prismicRef: 'XoMvVhIAAKOawzME' 
    shortenUrlLangs: true,
    path: '/preview',
    previews: true,
    extraPageFields: 'category',
    sharpKeys: [
      /image|photo|picture/,
    ],
    pages: [
      {
        type: 'Post',
        match: '/:lang/post/:uid',
        path: '/post-preview',
        component: require.resolve('./src/templates/post.js'),
        sortBy: 'meta_lastPublicationDate_ASC',
        filter: data => data.node.category === 'news',
      }, 
      {
        type: 'Article',
        match: '/:lang/article/:uid',
        path: '/article-preview',
        component: require.resolve('./src/templates/article.js'),
        filter: data => data.node._meta.uid.includes('music'),
      }
    ],
  }
}

resolve

A key to set the package name.

options

An object property that holds all the plugin configuration.

options.repositoryName

The name of your Prismic repository. You can find it in the URL of the repository. (Required)

options.defaultLang

The master language of your Prismic repository. Only needed when you want to add language parameters to your project. To learn more about how to use it read: Query by language. (Optional, but recommended)

options.langs

All the available languages in your Prismic repository. Only needed when you want to add language parameters to your project. To learn more about how to use it read: Query by language. (Optional)

options.accessToken

The access token for private APIs. Only needed if you have a private Prismic repository. (Optional)

options.prismicRef

The reference for pulling content from different Prismic refs. Learn more about the refs of a Prismic API. (Optional)

options.shortenUrlLangs

This option will allow you to shorten the URL lang slug of the route. To learn more read: Query by language. (Optional)

options.path

The default path that is going to be created for previews. Learn more about Previews. (Optional)

options.previews

A boolean field option to enable or disable the Preview feature. Learn more about Previews. (Optional)

options.extraPageFields

A parameter that works along with the options.pages.filter parameter to filter our documents that match a given value. Learn more about this parameter. (Optional)

options.sharpKeys

This parameter was created to support the gatsby-image plugin by adding a new property to GraphQL types that contains fields that match the sharpKeys array to the Sharp suffix. Now this can be omitted thanks to the Image Optimization feature. To learn more read: Gatsby-Image plugin vs Image Optimization. (Optional)

options.pages

Property that holds all the configuration for dynamically generated pages. (Optional)

options.pages.type

The name of the custom type created in the Prismic repository for which the dynamic pages will be generated.

options.pages.match

The structure of the dynamic URL slugs. Only top level pages are created here. To see examples of how this is used read: Query by ID or UID and Query by language.

options.pages.path

The path that is going to be created for page previews. Learn more about Previews.

options.pages.component

This parameter along with the require.resolve() function defines the path to the template that handles the dynamic pages.

options.pages.sortBy

A method you can use to sort the response. To learn more read: Order your results. (Optional)

options.pages.filter

This parameter allows you to conditionally generate pages. You can either use it alone to filter out using values from the metadata or along with extraPageFields, that will allow you to generate pages by a content field. Learn more about this parameter. (Optional)