@prismicio/next Technical Reference - beta

Overview

@prismicio/next is the official Prismic package for creating web apps with Prismic and Next.js.

This package is currently in beta. If you would like to contribute, please reach out on GitHub.

Dependencies and requirements

This package can only be used in a Next.js project. It relies on @prismicio/client, @prismicio/helpers, and @prismicio/react as peer dependencies.

Installation

Install packages

Add @prismicio/next and its peer dependencies to your Next.js project via the command line:

Copy
npm install @prismicio/next @prismicio/client @prismicio/helpers @prismicio/react

Create an optional Link Resolver

Create a Link Resolver function. This is one of two ways to tell Next.js how to handle internal links in Prismic documents. (The other way to do so is with a Route Resolver, which works better for more complex routes. Read a comparison.)

Copy
export function linkResolver(document) {
  if (document.type === "post") {
    return "/blog/" + document.uid;
  }

  return "/";
}

Add <PrismicPreview> to _app.js

Add support for Prismic Previews to your Next.js app by adding the <PrismicPreview> component to your app’s _app.js. This component adds the Prismic Toolbar and registers event listeners to react to the toolbar’s events.

Here’s an example of setting up the component:

Copy
// _app.js

import { PrismicPreview } from '@prismicio/next'
import { repositoryName } from '../prismicio'

export default function App({ Component, pageProps }) {
  return (
    <PrismicPreview repositoryName={repositoryName}>
      <Component {...pageProps} />
    </PrismicPreview>
  )
}

More information about <PrismicPreview> is provided below.

Usage

<PrismicPreview>

Wrapper component that wraps around the entire Next.js app. Requires a repository name as a prop called repositoryName.

It makes the Prismic Toolbar available to the website and also adds event listeners for Prismic Toolbar events like prismicPreviewUpdate and prismicPreviewEnd.

Copy
import '../styles/globals.css';
import type { AppProps } from 'next/app';
import { PrismicPreview } from 'prismic-next';

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <PrismicPreview repositoryName='your-repo-name'>
      <Component {...pageProps} />
    </PrismicPreview>
  );
}

export default MyApp;

setPreviewData()

Copy
setPreviewData(params)

A function that sets Prismic Preview data to Next.js’s Preview Mode cookie. This function should only be called in an API route. Calling this function enables other parts of your app, such as your pages’ getStaticProps(), to query previewed content from your Prismic repository.

setPreviewData() accepts a params object that can have the following properties:

req

required

The API route’s req object.

res

required

The API route’s res object.

The API route will be used as your app’s Preview Resolver. When editors start a preview session from your Prismic repository, they will be sent to this route to prepare the app for Preview Mode.

Here is a full example of an API route using setPreviewData():

Copy
// pages/api/preview.js

import { setPreviewData, redirectToPreviewURL } from '@prismicio/next'
import { linkResolver, createClient } from '../../prismicio'

export default async function handler(req, res) {
  const client = createClient({ req })

  await setPreviewData({ req, res })

  await redirectToPreviewURL({ req, res, client, linkResolver })
}

redirectToPreviewURL()

Copy
redirectToPreviewURL(params)

A function that redirects the user to the previewed document’s URL. This function should only be called in an API route. Accepts a params object that can have the following properties:

req

The API route’s req object.

res

The API route’s res object.

client

A @prismicio/client client instance configured for your Prismic repository.

linkResolver

A Link Resolver function used to determine the previewed document’s URL. This is optional if your app uses the Route Resolver to define document URLs. See the Link Resolver and Route Resolver documentation for more information.

See the setPreviewData() section for a full example including redirectToPreviewURL().

exitPreview()

Copy
exitPreview(params)

A function that exits Next.js’s Preview Mode and redirects the user back to the previous page. This function should only be called in an API route. Accepts a params object that can have the following properties:

req

required

The API route’s req object.

res

required

The API route’s res object.

The API route will be used as your app’s “exit preview” route. When editors click the “exit preview” button in the Prismic Toolbar during a preview session, this API route will be fetched to end the preview session.

Here is a full example of an API route using exitPreview():

Copy
// pages/api/preview.js

import { exitPreview } from '@prismicio/next'

export default async function handler(req, res) {
  exitPreview({ req, res })
}

enableAutoPreviews()

Copy
enableAutoPreviews(params)

A function that enables automatic preview support in @prismicio/client instances. This function should be called in a reusable createClient() function to be used throughout your Next.js app. See a full example at the end of this section. Accepts a params object that can have the following properties:

client

required

A @prismicio/client client instance configured for your Prismic repository.

req

If enableAutoPreviews() is called in an API route, pass the route’s req object.

previewData

If enableAutoPreviews() is called in a Next.js API that provides a context object, such as getStaticProps() or getServerSideProps(), pass the API’s previewData which comes from Next.js’ context object.

Here is a full example of a reusable createClient() function that uses enableAutoPreviews():

Copy
// prismicio.js

import * as prismic from '@prismicio/client'
import { enableAutoPreviews } from '@prismicio/next'

const repositoryName = 'your-repo-name'
const endpoint = prismic.getEndpoint(repositoryName)

export const createClient = ({ req, previewData }) => {
  const client = prismic.createClient(endpoint)

  enableAutoPreviews({ client, req, previewData })

  return client
}

The createClient() function can now be used throughout your app with automatic preview support.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.