Install 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 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 adding responsive images to your site and is required to support Gatsby's automatic image optimization component, <GatsbyImage>

The prismic-reactjs library helps to render certain structured fields like Rich Text, Dates, and Links to your templates:

  • npm
  • Yarn
Copy
npm install gatsby-source-prismic gatsby-plugin-image prismic-reactjs
Copy
yarn add gatsby-source-prismic gatsby-plugin-image prismic-reactjs

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

Read Configure the plugin further below to learn about each plugin option. Update your environment variable files and add only the variables that apply to your project configuration. For example, if you have a public repository, the access token isn't needed.

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.

Copy
GATSBY_PRISMIC_REPO_NAME=your-repo-name
PRISMIC_ACCESS_TOKEN=your-access-token
PRISMIC_CUSTOM_TYPES_API_TOKEN=your-custom-types-api-token

Once this is set 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

Description

resolve

string (required)

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

options

object (required)

Property that holds all the plugin configuration.

options.repositoryName

string (required)

The name of your Prismic repository. If your prismic.io URL is 'https://my-cool-website.prismic.io/api/v2', your repo name is 'my-cool-website'.

options.accessToken

string

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

options.customTypesApiToken

string

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

options.linkResolver

function

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.

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 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')

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.

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

require('dotenv').config({
  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

You need to declare all the Custom Types in your repository inside your plugin configuration, including those that aren't in use anymore. This is 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 it's enabled 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:

Copy
customTypesApiToken:  process.env.PRISMIC_CUSTOM_TYPES_API_TOKEN,

Your Custom Types will be automatically retrieved using the Custom Types API and loaded into Gatsby.

And that is it. At this point, your plugin configuration should be ready for you to start creating queries and templating pages. Read Query Basics 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? Get in touch with us on our Community Forum.