How to set up a staging environment with Prismic.io
Prismic.io is a content management system that makes it really easy to draft and publish content to a website. It allows you to define custom types for your CMS data, has an excellent dashboard interface, and and has a simple SDK to integrate with whatever technology stack you are using.
One of the weaker points of their API is previewing content in a staging environment before pushing to production. After taking a look at their in-website preview functionality, I found it to be lacking and an unnecessary addition of client-side Javascript just to preview content you want to add to your site. In addition, we here at Philosophie have strict requirements about separation between staging and production environments. This is in order to protect information we are previewing before we roll it out to production.
After doing some research through Prismic’s API documentation, I found a small section on their References API, and this particular section of the documentation piqued my interest:
For your production site you will be using master [reference], but it can be useful to set up one or more instances of your front-end pointing to an upcoming release to preview that release internally. It can be considered as a “staging” version of your site.
After seeing this portion of the API, I came up with a workflow to deploy a staging and production version of your Prismic-backed website while still maintaining a separation of content in both environments using References server-side and Releases CMS-side.
- Create new apps “Staging” and “Production” in your Prismic dashboard. With “Staging”, make sure the permanent access token allows access to master+releases. The access token must be set in this way for “Staging” so that your API requests have access to releases. Separating out these two environments as separate applications makes sure that production has no access through its API token to any unpublished material.
- Decide on a name to be used for every new “release” that will be used for previewing content in your staging environment. Case and name matter, because you will be directly referencing this in your code when querying the Prismic API. I have opted to use “Staging”, I’ve provided an example below of what this should look like:
3. Add logic to your application that uses the References API to add data from the staging release into your staging application. This can be done through some environment variables and business logic so you form your API call properly. Here’s a small example below of how I did it in Javascript:
4. Deploy your application to a staging and production environment and test things out! If all works well, everything in your “Staging” release should be available to view on your staging server!
I’ve also created a more in-depth example that shows how the above code works with an actual Prismic API call. You can find that repo here. It also shows how to set up staging and production environments with Node (Hapi.js and Prismic’s JS SDK). Check it out!
