Implement the preview feature with the REST API

This page shows you how to get the preview reference and preview your content.

The preview works by using a preview token: when a user requests a preview from the Writing Room, a temporary and secure ref is generated for the preview session. Your website can then use this temporary ref to query the Prismic API. It will allow your website to display pending changes.

Additionally the prismic.js script automatically detects when a user is browsing the website in a preview session, and displays the preview bar.

All the required code is already available out-of-the-box in our starter projects, but if you want to include it into a custom development, here are the 4 simple steps to integrate it into your website.

1. Include the Prismic Toolbar javascript file

First you must include this script on every page of your website. If you are using a web framework with a templating system, you will typically include it once in your master layout.

Make sure to update <your-repo-name> with the name of the endpoint for your repository.

Copy
<script>
  window.prismic = {
    endpoint: 'https://<your-repo-name>.prismic.io/api/v2' // replace by your repository's endpoint
  };
</script>
<script type="text/javascript" src="//static.cdn.prismic.io/prismic.min.js"></script>

Note for Sharable Previews

To guarantee that Sharable Previews work properly you must ensure that these scripts are included on every page of your website, including your 404/Page Not Found page. Otherwise the Shareable Preview might not work.

2. Setup a preview environment

In your repository, head to the Settings / Previews. Add a site name and the domain for your website where you wish to preview your content. You can also add an optional Link Resolver route which you will learn more about in the next section.

Note that you can also enter localhost domains such as:

Copy
http://localhost:3000

3. Use the preview token as ref when available to make your queries

When you preview your website, a preview cookie is generated that contains the preview token. This token can be used as a valid ref to make Prismic API queries. For any query you make on your website, make sure to check for the Preview cookie and use this preview ref in the query options if the preview cookie exists.

Here is an example of how to retrieve the correct ref in Node.js:

Copy
var Cookies = require('cookies');

// Example ref selection for NodeJS with ExpressJS
const cookies = new Cookies(req, res);
const previewRef = cookies.get(Prismic.previewCookie);
const masterRef = api.refs.find(ref => { return ref.isMasterRef === true; });
const ref = previewRef || masterRef.ref;

Then here is an example that shows how to use this ref when constructing your api query:

Copy
http://your-repo-name.prismic.io/api/v2/documents/search?ref=Your_Ref

In order to be taken directly to the page you are previewing instead of the homepage, you need to add a Link Resolver endpoint. A typical example of this would be:

Copy
http://example.com/preview

In your preview settings add this endpoint to the optional Link Resolver field.

Now you need to add the Link Resolver endpoint in your website application.

This is a special URL of your website that Prismic will call to request a preview, passing the preview token in the query string. When requested this endpoint must:

  • Retrieve the preview token from the token parameter in the query string
  • Call the Prismic development kit with this token and the Link Resolver will retrieve the correct URL for the document being previewed
  • Redirect to the given URL

Here's an example of what this would look like if developing a NodeJS website:

Copy
// Example preview endpoint for NodeJS with ExpressJS 
const Prismic = require('prismic-javascript');
const linkResolver = require('./path/to/the/link-resolver.js');
const apiEndpoint = 'http://your-repo-name.prismic.io/api/v2';
 
app.get('/preview', function (req, res) {
  const token = req.query.token;
 
  Prismic.getApi(apiEndpoint, { req: req })
    .then((api) => api.previewSession(token, linkResolver, '/'))
    .then((url) => {
      res.redirect(302, url);
    });
});

And with that you should have everything in place that you need to begin previewing your content!