NEW

Prismic offers an ideal solution to feature your e-commerce products in your promotional landing pages or inspirational content. View more

Gatsby + Prismic v5

Written by Angelo Ashmore in announcement on October 21, 2021

A new release of Prismic's Gatsby integration is out! This version brings support for Gatsby 4 and its new features. It also brings some ergonomic improvements that make using Prismic in your Gatsby projects easier.

If you are upgrading to Gatsby 4, you will also need to use V5 of Prismic's Gatsby plugins. We have a quick migration guide available for sites currently on V4 of the Prismic plugins.

Learn more: Migration Guide: gatsby-source-prismic V4 to V5

If you find anything broken after upgrading, please share your findings with us on GitHub, so we can fix it quickly.

If you aren't trying out Gatsby 4 today, no problem! You don't need to change anything on your site yet. Gatsby 4 and the updated Prismic plugins bring some great improvements, so we recommend upgrading as soon as you are able to.

New features and updates

This release includes the following:

  • 4️⃣ Support for Gatsby 4
  • 👁️ Simpler preview configuration with <PrismicPreviewProvider>
  • 🍰 Preparations for the upcoming Slice Machine integration

This release introduces a couple of breaking changes to support Gatsby's new features. Please see the V4 to V5 migration guide for details on upgrading.

Support for Gatsby 4

Gatsby 4 introduces a number of new features. Most notable are Deferred Static Generation, Server-Side Rendering, and parallel query running. You can learn more about Gatsby 4 and its features on the Gatsby 4 announcement page.

gatsby-source-prismic fully supports these new features.

Simpler preview configuration with <PrismicPreviewProvider>

In V4, setting up in-browser previews with gatsby-plugin-prismic-previews requires providing configuration to individual page templates. In most cases, the configuration is identical among all templates, making it a tedious process to setup and make changes.

In V5, repository configurations can now be provided in one shared location: <PrismicPreviewProvider>. Defining your preview configurations in one location is easier to setup and maintain than doing so in each template.

See the V4 to V5 Migration Guide to learn how to make this change.

Preparations for the upcoming Slice Machine integration

Many of you have asked for a Slice Machine integration with Gatsby. We're working on it! This release of the plugin sets it up for the upcoming integration. There's nothing you need to do right now in response to these changes but we'll share more information once it's ready. Be on the lookout for this!

For those who are unfamiliar with Slice Machine, it is a tool and workflow from Prismic to efficiently build websites. One notable feature is support for Shared Slices which allow you to model a Slice once and use it in multiple Custom Types. It currently works with Next.js and Nuxt.js and support for other frameworks is in development.

To learn more about Slice Machine, check out the official Slice Machine site.

Breaking changes

To support Gatsby's newly optimized startup and build process, a breaking change involving file downloads was introduced. Locally downloaded files, such as images transformed with gatsby-transformer-sharp, must be listed in gatsby-config.js.

In addition to that change, the preview plugin now scopes its styles using a shadow DOM to ensure your site's styling is unaffected. This changes means you no longer need to import the plugin's stylesheet yourself.

See the Gatsby + Prismic V4 to V5 Migration Guide for instructions on upgrading.

Providing feedback or getting help

As always, if you have any questions or run into issues with the plugins, please feel free to reach out for help.

❓ Asking a question
Open a new topic on our community forum explaining what you want to achieve / your question. Our support team will get back to you shortly.

🐛 Reporting a bug
Open an issue explaining your site's setup and the bug you're encountering.

💬 Suggesting an improvement
Open an issue explaining your improvement or feature so we can discuss and learn more.

🧑‍💻 Submitting code changes
For small fixes, feel free to open a PR with a description of your changes. For large changes, please first open an issue so we can discuss if and how the changes should be implemented.

We look forward to seeing what you build with Gatsby and Prismic! 🚀

Profile picture

Angelo Ashmore

Developer Experience Engineer at Prismic focusing on Gatsby, React, and TypeScript, in no particular order.