The next major version of the Prismic plugin, v4.0.0, contains a number of new features and fixes that make working with Prismic within Gatsby easier and more flexible. The changes described below are a result of real-world usage within Wall-to-Wall Studios and user feedback shared on GitHub and the Prismic community forums.

A detailed migration guide will be created explaining the changes needed to upgrade from V3 to V4.

The changes described below are not yet publicly available and are still in development. If you would like to provide input on this roadmap, please comment on the V4 Roadmap GitHub issue.

Dedicated preview plugin

V4’s largest change aims to greatly improve Prismic’s built-in preview support when used with Gatsby sites while also making it completely optional. Part of this process involves separating the preview functionality into its own plugin.

Traditionally, Gatsby source plugins (typically named gatsby-source-*) only fetch data and make it available to your pages. Any other functionality, like adding Context Providers or remote scripts, are handled using general plugins (typically named gatsby-plugin-*). Moving preview functionality into its own plugin will better align with this convention and set better expectations for users.

Separating also allows users to decide whether or not they need client-side preview functionality. For small, personal sites, live previews may not be a necessity. For larger sites built by teams where editor previews are a requirement, developers can choose between integrating Gatsby Preview or the new Prismic plugin.

Note that Gatsby Preview, Gatsby’s official cloud service for live previews, is supported in the latest version of V3 and will continue to be a core feature of the source plugin.

In addition to separating previews into its own plugin, several updates are being made to the preview process. See the list of updates below.

Multiple repository support

Sourcing content from multiple repositories can be helpful when working with large, separated teams where separating content by repository keeps things organized. It can also help when creating child sites that live separately from a main parent site to ensure global content is not duplicated.

In V3, sourcing content from multiple Prismic repositories can be a challenge, if not impossible. The plugin is currently not built with multiple usage in mind. If you have more than one repository with a custom type named “Page”, for example, the types for PrismicPage may conflict.

In V4, multiple repository usage is taken into account in all parts of the plugin. Sourcing from more than one repository is as simple as adding another plugin instance to your gatsby-config.js file and adding a unique typePrefix option for each.

// gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        repositoryName: 'example-parent-repo',
        typePrefix: 'Parent',
        schemas: {
          page: require('../parent-site/schemas/page.json'),
        },
      },
    },
    {
      resolve: 'gatsby-source-prismic',
      options: {
        repositoryName: 'example-microsite-repo',
        typePrefix: 'Microsite',
        schemas: {
          page: require('./schemas/page.json'),
        },
      },
    },
  ],
}

Setting the typePrefix option automatically namespaces GraphQL types where appropriate. In the above example, we can now query PrismicParentPage and PrismicMicrositePage if both repositories have a Page custom type.

query AboutPageQuery {
  # From the parent repository
  prismicParentPage(uid: { eq: "about" }) {
    data {
      title {
        text
      }
    }
  }

  # From the microsite repository
  prismicMicrositePage(uid: { eq: "about" }) {
    data {
      content {
        html
      }
    }
  }
}

Smaller features and fixes

Since all client-side preview functionality has been moved to a separate plugin, changes listed below are grouped by plugin.

Source plugin

This plugin is used to pull CMS data into Gatsby using Prismic’s REST API.

• Validate plugin options (details)
• gatsby-plugin-image support
• GraphQuery support (replacement for fetchLinks option)
• Serve media files from Link fields locally via localFile field (details)
• Download image and media files only when queried for faster start-up times
• Full support for Embed fields with oEmbed data
• Full support for unknown data, such as Integration Fields
• Private plugin options, including repository names, access tokens, and schemas

Preview plugin

This plugin is used to provide live editor previews client-side directly from the Prismic editor. The following changes are made over the existing preview functionality.

• Live refreshing as document changes are saved
• Preview changes across all data and pages, not just the previewed document’s page
• Preview a release with multiple documents
• Sharable preview links
• Easier to use hooks and higher-order-components to integrate with your site
• Private access tokens (optional)

Breaking changes

• All client-side preview functionality is moved to a separate plugin and will require updating imports and, in some cases, usage
• Link Resolvers and HTML Serializers no longer provide node, key, and value arguments (details)
• shouldDownloadFile option is removed (details)
• typePathsFilenamePrefix option is removed
• prismicToolbar option is moved to the preview plugin and is not optional

Current Status

Most of the work to support these changes is complete, but everything is open to feedback and suggestions. If you would like to provide input on this roadmap, please comment on the V4 Roadmap GitHub issue.

The goal is to have a public beta in the next month or two (February/March 2021) where we can gather feedback and bug reports from real-world usage.

Read on for detailed explanations

If you want to learn more about some of the changes and the decisions behind them, check out the footnotes below.

Validate plugin options

In V3, basic plugin validation occurs to ensure all required fields are provided. A common source of errors, however, comes from not providing all custom type JSON schemas, which the current validation system does not check.

In V4, multiple levels of validation occurs:

1. Ensure all provided options are valid.
2. Ensure all required options are present.
3. Check access to the Prismic repository to ensure the repository name and access token are correct.
4. Ensure a schema is provided for each of the repository’s custom types.
5. Print a warning if it appears the provided JSON schema is out of sync with the repository.

Gatsby has also since introduced first-class support for plugin options validation which can hook into other tooling. The validation steps described above are implemented using this system to ensure the plugin can benefit from future Gatsby improvements.

Private plugin options

In V3, all plugin options are exposed in the browser through the plugin’s gatsby-browser.js file. This includes potentially sensitive data such as your access token and schemas. This data is necessary client-side for previews to work, but its exposure is usually unexpected and may be unnecessary for those not needing preview support.

In V4, all plugin options provided to gatsby-source-prismic are kept private and not exposed client-side.

If gatsby-plugin-prismic-preview is installed, only options provided to that plugin are exposed client-side as, again, it is necessary for previews to work. This plugin, however, does not require sensitive data to be provided, including access tokens and schemas.

If an access token is required to access your repository (which is highly recommended), editors will be prompted to provide the token in the browser when previewing. It is only saved as a cookie in the browser for use in future preview requests.

Thanks to @patspam for pointing out this issue and ideas for a solution here.

Serve media files locally from Link fields

In V3, linking to a Media item is only possible by linking to the Prismic CDN URL. This may not always be a viable option, such as environments with strict network security policies where all URLs must come from the same host or a trusted location.

In V4, Link fields containing a Media item (anything from the Media Library such as a PDF or image) can be downloaded locally and served from your built Gatsby site. This means that if you have a link to a file, you can serve it from https://your-site.com rather than https://cdn.prismic.io. The exact path will contain an automatically generated hash.

All you need to do is query for the local file’s public URL in your GraphQL query.

query MyPageQuery {
  prismicPage {
    data {
      linked_file {
        url
        localFile {
          publicURL
        }
      }
    }
  }
}

The data will look something like the following:

// Standard Prismic CDN URL
data.linked_file.url ===
  'https://repo-name.cdn.prismic.io/repo-name%2F41afcdaa-83e7-465e-9e68-8118e653b16c_some_filename.pdf'

// publicURL field
data.linked_file.localFile.publicURL ===
  'https://your-site.com/static/41afcdaa-83e7-465e-9e68-8118e653b16c_some_filename.pdf'

This will require gatsby-source-filesystem to be installed as a plugin if you plan to serve files directly from your site. gatsby-source-filesystem adds a publicURL field to the downloaded file which automatically copies it into your /public directory.

Simpler Link Resolver and HTML Serializer signatures

In V3, Link Resolvers and HTML serializers provided extra data that is not normally available when working with Prismic. The extra data, comprised of the field’s root document, the field’s name, and the field’s value, could be used to customize the responses on a per-document-type or per-field basis. While this can be helpful, it is non-standard, is a common source of issues, and is not widely used.

In V4, the linkResolver and htmlSerializer options accept a standard Prismic Link Resolver and HTML Serializer function, respectively.

// V3 with extra contextual data:
const linkResolver = ({ node, key, value }) => (doc) => `/${doc.uid}`

// V4 with standard Prismic signature:
const linkResolver = (doc) => `/${doc.uid}`

“Should download file” option is removed

In V3, the shouldDownloadFile option allows providing a function to determine if images should be downloaded locally. This allows one to download some images while skipping others. With the introduction of the Imgix-based fixed and fluid fields, this option is only used to opt in to local file processing with gatsby-transformer-sharp using the localFile image field.

In V4, the shouldDownloadFile option is removed. Instead, querying for an image’s localFile field represents “opting in” to downloading the file. If you don’t need the file to be downloaded locally, don’t query for the field.

As a nice side effect of this change, files will only be downloaded on request in order to speed up the initial gatsby develop and gatsby build bootstrap time.

Again, the changes described above are not yet publicly available and are still in development. If you would like to provide input on this roadmap, please comment on the V4 Roadmap GitHub issue.