Gatsby-Prismic plugins: what’s going on?

Written by Edward Hewitt in Engineering on July 17,2020

Gatsby is one of the most popular frameworks among Prismic users. Prismic's flexibility allows users to build the stack that they prefer without foregoing any of the benefits of any of the technologies involved. When paired with Gatsby, Prismic websites remain lightning-fast but also provides features and benefits that make managing a website and content much easier.

In developing Prismic, we have focused heavily on ensuring that all of our users have access to our key features regardless of their Prismic plan or the stack that they build. That commitment has been a large part of our success and it is the reason why many developers see us as the best option for small projects and why enterprise clients trust us with large websites.

That being said, if you’ve decided to read this article then there is a good chance that you may have encountered some of the issues regarding the Gatsby-Prismic plugins or, in the very least, you’re aware of some of the issues that people have been encountering. That commitment to delivering every feature with every stack has run into some problems when it comes to delivering multi-session previews in Gatsby.

Not been affected? Well, you may still find this article will provide an interesting look at the difficulties of managing plugins, third-party integrations, and product decisions.

The fact is, it’s rare for us to have to comment on issues with plugins. One of the major benefits of Prismic over traditional CMSs like WordPress is that our product doesn’t involve managing a world of plugins. For the vast majority of users, they can access all of our features right out of the box and never look back.

Gatsby is a little different.

But before we get on to that bit of the story, it is probably best to start at the root of the problem: the Prismic Previews feature.

Prismic Previews

Previews are one of our most popular features. Whilst almost every CMS will offer some sort of preview feature, ours offers functionalities that most don’t match.

With Prismic Previews, you can instantly generate a preview of the content that you are working on, see exactly what it will look like as a finished product, and use a link to share that version with anyone else — including no Prismic users.

These shareable links even update to reflect any changes that you may have made to your content after sharing that link, so you don’t have to worry about the fact that you sent a link and then made a small change before the other person was able to see it.

What’s more, these are multi-session previews. Meaning that you, and anyone else with access to your Prismic account, can be generating simultaneous previews for different pieces of content and it will cause you no issues.

Prismic Previews are one of the biggest game-changers for content creators when it comes to managing their workflow.

We obviously use Prismic for our website and all of the articles that we publish and I can’t tell you the number of times I will generate a preview to check what my content will look like or to share it with a colleague before I publish. It helps me to shape my content, proof-read, and ensure that it is consistent with the overall style and look of the rest of our work.

Now, I’m sure that you can see where the issue is coming. How do we generate multi-session previews for statically generated content?

Delivering multi-session previews with Gatsby

We know that a lot of our users choose Gatsby. We’re huge fans of the framework and we can understand why it is so popular amongst our users and within our community.

So the challenge for us was to make sure that we could offer all of Prismic’s core features and functionalities to Gatsby users and just over a year ago we thought we had done it.

The Gatsby plugin was developed by Birkir Gudjonssen from Ueno and he, along with our team, was able to find a solution that would allow multi-session previews in Gatsby without making any significant changes to your code.

The details of how he did that are actually very interesting and worth reading about, so I would encourage you to read this article from last year, but, as you will already know, we’ve encountered some difficulties with this plugin.

It is important that we say that we are incredibly grateful of the work that Birkir put in and the plugin was a great solution at the time, so the problems that we have encountered are in no way a reflection of his work.

In fact, we even saw this plugin as a sign of a thriving ecosystem that was growing around Prismic. We work very hard on involving our community in our decision-making and roadmap and it is always very pleasing to see members fo the community working on solutions, workarounds, and improvements that they can share with other Prismic users.

What went wrong?

One of the biggest issues has been something that will be very familiar to anyone who has ever worked on third-party integrations or plugins.

The GraphQL plugin relied on an internal mechanism from the Gatsby framework and not on a stable API. This means that there is a risk that it may break whenever Gatsby makes an update or a change to their framework.

This is a pretty big issue and it has caused problems throughout the lifetime of the plugin.

This problem also leads us on to the one major downfall of having community-created plugins and solutions. Whilst we were involved in Birkir’s work, we were only contributors. So whenever an update to the plugin was required we were in exactly the same situation as all of our other users.

We know that this has caused significant frustration as some users didn’t realize this and thought that we were instead ignoring the issues with the plugin. This wasn’t the case.

When these issues started to grow we knew that we would need to find a different solution, particularly as we can’t expect Birkir, or any other member of our community for that matter, to maintain a plugin in the way that we will often need to.

So, we decided to reach out to Gatsby themselves and see what solutions we could find and it was at this point that we saw a second major problem.

A few months ago Gatsby launched Gatsby Cloud. It’s a great move for them, but has brought about a shift in their approach that means that they discouraged us from using a GraphQL plugin that wouldn’t support all of the new Gatsby Cloud features — an example of this being the fact that incremental builds will not work with the GraphQL plugin.

As you can imagine, these meant that we needed to make a major rethink in how we would approach this problem. Once again, this isn’t to shift any responsibility away from ourselves. We think that Gatsby Cloud will be really useful for a lot of our users and this is simply one of the many challenges that come with working in a landscape that has so many different technologies at companies operating within it.

So what are we suggesting now?

We know that some users have read our documentation or watched our videos and felt that we suggested that they use a plugin and a feature that didn’t work properly. We can only apologize to anyone who has encountered difficulties that they weren’t expecting.

For the time being, and we must stress that this is not our long-term solution, we are going to adopt a more standard approach to previews in Gatsby. We are opting for functionality over perfection and are picking a solution that works with Gatsby's incremental builds and will ensure that Prismic and Gatsby users do get a reliable preview feature, even if it isn't as powerful as the one available to other Prismic users.

That’s why we are now suggesting that our users opt for a different plugin for all new projects. This plugin is once again community-created, but it doesn’t rely on GraphQL, is future-proofed for Gatsby Cloud, and we are very heavily involved in maintaining it.

We’ve already made a fork to the Gatsby-source plugin, so it should be ready to use and more usable than the previous version, but we will continue to improve and maintain it over the coming months.

You will still be able to preview your content, but the preview feature will not be able to play such a game-changing role in your workflow and content management.

What does the future hold for Prismic Previews in Gatsby?

This entire process has been a big learning experience for us. Any reader that has ever been involved in managing product or making product decisions will be able to relate to the fact that you sometimes have to choose between what you think is the best possible solution and what you feel is the best immediate solution.

For a long time, we have fought hard to bring the best possible solution to Gatsby users. We have no doubt that multi-session previews are invaluable to any user and any product and we would want every Prismic user to be able to take advantage of this feature.

But we also need a product that is reliable and that meets the expectations of our users. Gatsby has its own previews feature. It doesn’t allow for multi-session previews, but it works and is stable and that is most important.

Over the past few months, we have worked closely with the Gatsby team and, although we know that they are very impressed with our multi-session previews, it may be best for our users to not expect that this will work in Gatsby for the time being.

But there is hope.

Anyone that has been following our updates will know that we are working at hard and developing better partnership with other technologies and companies and Gatsby is part of this.

We don’t want to abandon the idea that multi-session previews will be available to all of our users and we will continue to work hard on finding the best possible solution that will provide this.

So, for now, we hope that this article will answer many of the questions that have been asked in recent times and help you to choose the right Prismic-Gatsby plugin for your upcoming projects.

As for what are solution will be in the long-term? Stay tuned and we will update you shortly.

Edward Hewitt

Content Strategist. If the devs have their way, Edward will one day be replaced by a Prismic feature.