Developing with Prismic and Gatsby just got a whole lot more powerful. We've released the next major version of our Gatsby integration. The version 4.0 release brings new features and refinements to make working with Prismic and Gatsby easier than ever.
Our Gatsby plugin, gatsby-source-prismic, fetches content from a Prismic repository and makes it available in Gatsby's GraphQL API. Among other new key features, it now includes gatsby-plugin-image and better Integration Fields support.
We also have a new plugin enabling live content previews called gatsby-plugin-prismic-previews.
Documentation for the plugins has been updated and restructured to include the latest features and best practices. You can learn everything about the Gatsby integration in the official documentation.
We're excited to have you try it out and let us know how the experience is!
The Road Ahead for React Developers
While we support Gatsby v6, it's important to note the framework's evolution has paused (as per this announcement). For React developers seeking cutting-edge solutions, we recommend exploring Next.js for its ongoing advancements.
Check out our Next.js tutorial.
How to get started or update your existing projects
If you are new to Gatsby and are interested in starting a project, check out the updated tutorial. It will teach you how to create a new Prismic repository and integrate it into a Gatsby site. If you need a quick intro to Gatsby, check out our previous blog post.
For those with existing Gatsby projects, we recommend upgrading to the latest version as soon as you are able to. Our V3 to V4 migration guide walks you through the steps of upgrading from the previous version.
If you are on the older V2 plugin or gatsby-source-prismic-graphql, don't worry, we have a V2 to V3 migration guide and gatsby-source-prismic-graphql migration guide for you as well. 😊
New preview plugin
V4’s largest goal was to greatly improve Prismic’s built-in preview support when used with Gatsby sites. The previous version included limited support for previews but lacked crucial features like previewing changes from multiple documents via Releases and sharing links to draft pages.
The new gatsby-plugin-prismic-previews provides full live preview support to your static Gatsby site — no extra server or costs required! This means your site can support previews even when hosted on Netlify or Amazon S3.
Some of the plugin's key features include:
- Live refreshing as document changes are saved
- Preview changes across all data and pages
- Preview a release with multiple documents
- Share links to previews
- Easier to use higher-order components and React hooks to integrate with your site
- For increased security, you may optionally make your access token private
Building these features involved separating the preview functionality into its own plugin. Users who just want to source Prismic content can do so with gatsby-source-prismic. Users who also want to enhance the editor experience by allowing content previews before publishing can do so with gatsby-plugin-prismic-previews.
You can learn how to add preview support to your site with the new Previews guide.
Gatsby Cloud Preview, Gatsby’s official cloud service for live previews, is also supported in the latest version and will continue to be a core feature of the integration. We're working on an updated guide on deploying and previewing with Gatsby Cloud, so be on the lookout if you're interested in using Gatsby Cloud!
New source plugin features
This release has so many new features that we'll just have to list them.
The new release includes:
- Multiple repository support via the typePrefix plugin option
- Validate plugin options to ensure everything is configured properly
- Automatic Custom Types schema fetching via the beta Custom Types API
- gatsby-plugin-image support
- GraphQuery support (replacement for the fetchLinks option)
- Download and serve media files from Link fields locally via the localFile field
- Download image and media files only when queried for faster start-up times
- Full support for Embed fields with oEmbed data
- Full support for Integration Fields
- Private plugin options, including repository names, access tokens, and schemas
You can learn more about the reasoning behind some of the changes in the gatsby-source-prismic v4 Roadmap blog post from Wall-to-Wall Studios, where the plugin was previously developed.
Breaking changes
There are breaking changes included in this release. Many of the changes are meant to streamline the setup process and eliminate common issues.
For a full list of the breaking changes, see the V3 to V4 migration guide. It includes instructions on how to upgrade your project and how to handle each breaking change.
Providing feedback or getting help
As always, if you have any questions or run into issues with the new 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! 🚀
