Configure the plugin

This article will show you how to install and configure the gatsby-source-prismic plugin.


gatsby-source-prismic

The gatsby-source-prismic plugin allows you to pull data from your Prismic repository. Follow the next steps to start configuring it in your project.

1. Install the plugin

First, install the plugin in your existing Gatsby project:

  • npm
  • yarn
Copy
npm install gatsby-source-prismic
Copy
yarn add gatsby-source-prismic

2. Configure the plugin

Then, define the plugin configuration in the gatsby-config.js file.

⚠️ Replace the example config

Remember that you will need to update this with the repository name, access token, link resolver, etc., to match your project. This configuration is mere, for example, purposes.

Example plugin configuration

resolve

Required

The name of the plugin: 'gatsby-source-prismic'

options

Required

An object property that holds all the plugin configuration

options.repositoryName

Required

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

options.accessToken

Optional

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

options.releaseID

Optional

The Release ID you'll use to preview releases with Gatsby Cloud (Required when using Gatsby Cloud).

options.linkResolver

Required

The Link resolver you'll use to process links in your content. For example, Content relationship or Rich Text fields use this to generate the correct link URL. (Required to make links between docs work)

options.htmlSerializer

Optional

By using the HTMLSerializer you can customize the HTML output of a Rich Text Field.

options.fetchLinks

Optional

fetchLinks allows you to set a list of links to fetch and makes them available in your link resolver function.

options.schemas

Required

Provide a JSON object per Custom Type in your repository to load the schema into Gatsby.

options.lang

Optional

The default value is * which will fetch all languages from your repo. (Required if you have a multiple locales)

options.prismicToolbar

Optional

Add the Prismic Toolbar script to the site. (Required when using Gatsby Cloud)

options.shouldDownloadImage

Optional

Set a function to determine if images are downloaded locally and made available for gatsby-transformer-sharp for use with gatsby-image. Return true to download the image or false to skip.

options.imageImgixParams

Optional

Provide a default set of Imgix image transformations applied to Imgix-backed gatsby-image fields. These options will override the defaults set by Prismic.

options.imagePlaceholderImgixParams

Optional

Provide a default set of Imgix image transformations applied to the placeholder images of Imgix-backed gatsby-image fields. These parameters will be applied over those provided in the above `imageImgixParams` option.

⚠️ Dashes in Custom Type names

If your Custom Type names have dashes or hyphens (-) you need to wrap them in 'single quotes' in the options.schemas configuration, otherwise the schema won't be recognized. For example: If your Custom Type name is home-page, you'll need to declare it like this:

'home-page': require('./custom_types/home-page.json')
Copy
const linkResolver = require('./example-route-to-linkResolver')

module.exports = {
 plugins: [
 {
      resolve: 'gatsby-source-prismic',
      options: {
        repositoryName: 'example-repository-name',
        accessToken: 'example-access-token',
        releaseID: 'example-id',
        linkResolver: () => linkResolver,,
        fetchLinks: [],
        htmlSerializer: ({ node, key, value }) => (
          type,
          element,
          content,
          children,
        ) => {},
        schemas: {
          page: require('./custom_types/example_type.json'),
        },
        lang: '*',
        prismicToolbar: true,
        shouldDownloadImage: ({ node, key, value }) => {},
        imageImgixParams: {
          auto: 'compress,format',
          fit: 'max',
          q: 50,
        },
        imagePlaceholderImgixParams: {
          w: 100,
          blur: 15,
          q: 50,
        },
      },
    },
  ] 
}

3. Add your Custom type schemas

  1. At the root of your project, create a directory called custom_types
  2. Inside of it, create JSON files for each Custom Type that exists in your repository
  3. In your repository, go to each of your Custom Type, click on the JSON editor tab, copy the object and paste it into the corresponding file
  4. Import each Custom Type JSON in the gatsby-config.js file; that way, they can be declared in the plugin configuration in options.schemas. (We'll cover an example of how this looks like further bellow)

Example

In this example, we have only one repeatable Custom Type with Blog Post's ID. Inside the custom_types folder, we create this file:

  1. blog_post.json

Then, we copy the JSON object from the Custom type editor > JSON Editor tab and paste it into the file:

Copy
// custom_types/blog_post.json

{
  "Main": {
    "uid": {
      "type": "UID",
      "config": {
        "label": "uid"
      }
    },
    "title": {
      "type": "StructuredText",
      "config": {
        "single": "heading1, heading2, heading3, heading4, heading5, heading6",
        "label": "Title",
        "placeholder": "Title"
      }
    },
    "description": {
      "type": "StructuredText",
      "config": {
        "multi": "paragraph, preformatted, heading1, heading2, heading3, heading4, heading5, heading6, strong, em, hyperlink, image, embed, list-item, o-list-item, rtl",
        "label": "description",
        "placeholder": "description"
      }
    }
  }
}

Finally, we declare the Custom Type file in the plugin configuration in the gatsby-config.js file, and we're good to go. The schema now knows about our Custom Types, and it's ready to build a GraphQL schema with them!

Copy
schemas: {
  blog_post: require('./custom_types/blog_post.json')
},