Set up Prismic

By the end of this page, you will have a Prismic repository connected to your Gatsby project.


Prerequisites

Before you start, you will need a package manager like npm or Yarn installed globally. You'll also need a Gatsby project initiated. If you don't have those, here are some guides we recommend:

Create a repository in Prismic

If you don't already have one, create a repository where you will create and manage your content:

Then, add some content to your repository to have something to template in your Gatsby project.

Create or open your Gatsby project

If you don't already have one, visit the Gatsby docs to learn how to create a new project. When you have a project initiated, navigate to your project in your terminal.

Install the dependencies

Install gatsby-source-prismic, gatsby-plugin-image, and @prismicio/react.

  • gatsby-source-prismic is the source plugin to fetch the content from your repository.
  • The gatsby-plugin-image helps you add responsive images to your site and is required to support Gatsby's automatic image optimization component, <GatsbyImage>.
  • With @prismicio/react, you can render Rich Text and Links.
  • npm
  • Yarn
npm
Copy
npm install gatsby-source-prismic gatsby-plugin-image @prismicio/react
Yarn
Copy
yarn add gatsby-source-prismic gatsby-plugin-image @prismicio/react

Add environment variables

Environment variables allow you to store 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. 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 ones that apply to your project. Here's an example:

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

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.

Configure the plugin

Define the plugin configuration in the gatsby-config.js file. The following table describes available plugin options:

resolve

string (required)

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

options

object (required)

Property that holds the plugin configuration.

options.repositoryName

string (required)

The name of your Prismic repository. If your 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 Custom Types API.

options.routes

array of objects

An array of Route Resolver objects to resolve document URLs. This option can be used with the linkResolver option (Link Resolver will take priority if both are used for a specific document type).

options.linkResolver

function

A Link Resolver to process links in your documents. The Link Resolver processes links in your content.

options.typePrefix

string

A prefix that is used for all GraphQL types for your Prismic repository. This is required If you are sourcing from multiple repositories, and 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')

This example plugin configuration, shows basic setup options:

gatsby-config.js
Copy
require('dotenv').config({
  path: `.env.${process.env.NODE_ENV}`,
})

const routes = [
  {
    type: "article",
    path: "/articles/:uid",
  },
  {
    type: "page",
    path: "/:uid",
  },
];

module.exports = {
  plugins: [
    // ...
    'gatsby-plugin-image',
    {
      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,
        routes,
      },
    },
  ] 
}

Add the Custom Type schemas

The plugin requires all the Custom Types from your repository. This is done automatically using the customTypesApiToken option, which fetches the schemas from your repository.

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:

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. 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:

gatsby-config.js
Copy
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        customTypesApiToken:  process.env.PRISMIC_CUSTOM_TYPES_API_TOKEN,
        schemas: {
          my_deleted_schema: {}
        }
      }
    }
  ]
}

Your project is ready to query and template data with the source plugin. You'll learn how to query content from the API on the next page.


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.