Install the Plugin

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


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

1. Install the plugin and dependencies

Let's install the plugin and other helpful dependencies.

The gatsby-plugin-image plugin helps you add responsive images to your site and is required to support Gatsby's automatic image optimization component, <GatsbyImage>

The @prismicio/react library helps to render specific structured fields like Rich Text, Dates, and Links to your templates:

  • npm
  • Yarn
npm install gatsby-source-prismic gatsby-plugin-image @prismicio/react
yarn add gatsby-source-prismic gatsby-plugin-image @prismicio/react

2. Add environment variables

Environment variables allow you to safely store sensitive information about your projects, like your repository name or access token. At the root of your project, create two files:

  • .env.development
  • .env.production

Then, add the variables on each file to match your Prismic repository's information.

Example environment variables

In this example, we set up all variables for the following plugin options:

  1. repositoryName
  2. accessToken
  3. customTypesApiToken

Update your environment variable files and add only the variables that apply to your project configuration.

Environment variables prefixed with GATSBY_ will become available in the browser's client-side JavaScript. All the others will only be available in the gatsby-config.js file.


Once you set this up, you'll be able to access your repository name variable like this: process.env.GATSBY_PRISMIC_YOUR_VARIABLE_NAME.

3. Configure the plugin

Then, define the plugin configuration in the gatsby-config.js file. The following table indicates the basic setup of the plugin:

Plugin option



string (required)

The name of the plugin. It must be 'gatsby-source-prismic'.


object (required)

Property that holds all the plugin configuration.


string (required)

The name of your Prismic repository. If your URL is '', your repo name is 'my-cool-website'.



The access token for private APIs. Only needed if the API of your repository is private.



An API token for your Prismic repository that allows your Custom Type schemas to automatically be fetched from the The Custom Types API.



Set a Link Resolver to process links in your documents. You'll use it to process links in your content. Rich Texts, Links, and Content Relationship fields use this to generate the correct link URLs.


string (required when sourcing from more than one repository)

A prefix that is used for all GraphQL types for your Prismic repository. If you are sourcing from multiple repositories, each plugin should have a unique typePrefix to avoid type conflicts.

Read the plugin's technical reference to learn about all the available plugin options.

⚠️ 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 valid. 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')

Example plugin configuration

In this example plugin configuration, we are declaring the basic setup options of the plugin:

Update your plugin configuration and add only the options that apply to your project configuration. For example, if your repository's API is public, you don't need an accessToken.

If you have multiple repositories, duplicate the plugin configuration for each repository and add the typePrefix plugin option to differentiate the schemas.

const linkResolver = require('./example-route-to-linkResolver')

  path: `.env.${process.env.NODE_ENV}`,

module.exports = {
  plugins: [
    // ...
      resolve: 'gatsby-source-prismic',
      options: {
        repositoryName: process.env.GATSBY_PRISMIC_REPO_NAME,
        accessToken: process.env.PRISMIC_ACCESS_TOKEN,
        customTypesApiToken: process.env.PRISMIC_CUSTOM_TYPES_API_TOKEN,
        linkResolver: (doc) => linkResolver(doc),

4. Add all Custom Type schemas

Declare all the Custom Types of your repository inside your plugin configuration. Include the ones that you don't use anymore. That's how you'll let Gatsby know about your Prismic Custom Types. There are two ways of doing this:

  1. Automatically: using the customTypesApiToken option of the plugin.
  2. Manually: using the schemas option of the plugin. Learn how to do it in the plugin's technical reference.

All Custom Types are required

Please note that you must provide all the Custom Types of your repository even if they aren't in use; otherwise, the project might break.

Auto setup

The Custom Types API feature allows you to fetch your repository's schema.

Once you enable the Custom Types API on your repository, create a bearer permanent access token to authenticate your request. Then add it to an environment variable and pass it to the plugin configuration:

customTypesApiToken:  process.env.PRISMIC_CUSTOM_TYPES_API_TOKEN,

Your Custom Types will be automatically retrieved using the Custom Types API and loaded into Gatsby. Please note that if you delete one of the Custom Types, you need to declare it as an empty object in the plugin options. Even when using the customTypesApiToken option:

// Example gatsby-config.js

module.exports = {
  plugins: [
      resolve: 'gatsby-source-prismic',
      options: {
        schemas: {
          my_deleted_schema: {}

At this point, your plugin configuration should be ready for you to start creating queries and templating pages. Read Query Data to learn how to generate pages and queries:

Technical reference

If you'd like to get more in-depth information about how the gatsby-source-prismic plugin options works refer to the dedicated article:

Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.