Previews & the Prismic Toolbar

This page will show you how to get previews working when using Prismic with the GraphQL API and the apollo-link-prismic library. The main example shown on this page is for a React.js project, but the logic would be the same if you are using another framework or technology.


1. Include the Prismic Toolbar javascript file

The first step is to include the Prismic toolbar script on every page of your website. This means including it on your 404 page! You can find this script in your repository's Settings / Previews.

This toolbar will add a preview cookie when a user hits the preview button. This cookie contains the preview ref needed to call the API and receive the proper content.

Note for Sharable Previews & unpublished previews

To guarantee that Sharable Previews and unpublished document 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 these previews might not work.

2. Setup a preview environment

In your repository's Settings / Previews, add a site name and the domain for your website where you wish to preview your content. Make sure to also add a Link Resolver route which will allow you to be taken directly to the page you are previewing.

The interface for adding a new preview in Prismic

Note that you can also enter localhost domains such as: http://localhost:3000.

A typical endpoint to use for the Link Resolver field is /preview. In the next section you'll see how to configure this route in your website project.

3. Add the Link Resolver route to your application

Now you need to add the Link Resolver endpoint route to your website router. This example is for a React.js website, but the logic would be the same if using another framework.

Copy
import React from 'react';
import {
  BrowserRouter,
  Route,
  Switch,
} from 'react-router-dom';
import Preview from './Preview';
import NotFound from './NotFound';
 
const App = () => (
  <BrowserRouter>
    <Switch>
      {/* Add the new preview route here */}
      <Route exact path="/preview" component={Preview} />
      <Route exact path="/" component={Homepage} />
      <Route exact path="/blog/:uid" component={Post} />
      <Route component={NotFound} />
    </Switch>
  </BrowserRouter>
)
 
export default App;

You can see that when the "/preview" route is called, it will use the Preview component. Let's create this component now.

Add the Preview component

The Preview component must do the following:

  • Retrieve the preview token from the token parameter in the query string
  • Retrieve the documentId from 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

The Preview Token

Note that the preview token will be a URL. You DO NOT need to follow this url.

Processing the Preview Token

All you need to do is pass the token and documentId into the getPreviewResolver method as shown below. This requires the use of the prismic-javascript kit V2.7.0 and above.

If your project doesn't already have it installed, run the following command from the root of your project.

Copy
npm install prismic-javascript

Here is an example of what your preview endpoint/component might look like.

Copy
import { useEffect } from 'react';
import qs from 'qs';
import Prismic from 'prismic-javascript';
import { linkResolver } from './path/to/the/link-resolver.js'; // Update this with the path to your link resolver

const apiEndpoint = 'https://your-repo-name.cdn.prismic.io/api/v2'; // Update this with your repo name
const previewClient = Prismic.client(apiEndpoint);

const Preview = ({ history, location }) => {
  useEffect(() => {
    const {token, documentId} = qs.parse(location.search.slice(1));
    if (!token) {
      console.warn('No token available, check your configuration');
    }

    // Retrieve the correct URL for the document being previewed.
    // Once fetched, redirect to the given url
    previewClient.getPreviewResolver(token, documentId)
      .resolve(linkResolver, '/')
      .then((url) => history.push(url));
  });

  return null;
};

export default Preview;

The Link Resolver function

This requires the use of a Link Resolver function so that the preview endpoint knows where to redirect to. You can learn more about link resolving by checking out the Link Resolving page in your framework of choice. For example, here is the Link Resolving page for React.js.

You either need to define the Link Resolver in the Preview component or import it.

4. Use the correct reference

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 that shows how to check for the preview cookie and use the ref in your query:

Copy
import gql from 'graphql-tag';
import { PrismicLink } from 'apollo-link-prismic';
import { InMemoryCache, IntrospectionFragmentMatcher } from 'apollo-cache-inmemory';
import ApolloClient from 'apollo-client';
import Cookies from 'js-cookie';
import introspectionQueryResultData from './fragmentTypes.json';

const fragmentMatcher = new IntrospectionFragmentMatcher({ introspectionQueryResultData });

// Client method to query documents from the Prismic repo
const client = new ApolloClient({
  link: PrismicLink({ uri: 'https://your-repo-name.cdn.prismic.io/graphql' }), // Update this with your repo name
  cache: new InMemoryCache({ fragmentMatcher }),
});

const blogPostQuery = gql`
query myPost($uid: String) {
  allPosts(uid: $uid) {
    edges {
      node {
        title
      }
    }
  }
}
`;

const queryPostByUid = (uid) => {
  const previewCookie = Cookies.get('io.prismic.preview');

  const queryOptions = {
    query: blogPostQuery,
    variables: { uid },
  };

  if (previewCookie) {
    queryOptions.context = {
      headers: {
        'Prismic-ref': previewCookie,
      },
    };
  }

  return client.query(queryOptions);
};

const fetchPostContent = async () => {
  const postContent = await queryPostByUid("example-uid");
  console.log(postContent);
};
fetchPrismicData();

Introspection query

Note that the example above uses the results of an Introspection query. To learn more about this, check out the Introspection query page.

And you're all set!

The preview functionality should now be all set on your project.

5. A working example project

If you're interested in viewing a full working website example project with Prismic previews, check out this example project on github.

6. Troubleshooting

Mistakes happen. Sometimes you might need a little help figuring out what exactly is causing the problem. Luckily we've created a troubleshooting article just for this.