@prismicio/next Technical Reference - v1

Overview

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

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.

Are you using Next v12 or lower?

@prismicio/next v1 is compatible with Next.js 13 and later.

If you are using Next.js 12, see the @prismicio/next v0.1 docs.

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

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 your app

Add support for Prismic Previews to your Next.js app by adding the <PrismicPreview> component to the root of your app. 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:

App Router
Pages Router

App Router

src/app/layout.tsx

Copy

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

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <PrismicPreview repositoryName={repositoryName} />
      </body>
    </html>
  )
}

Pages Router

src/pages/_app.js

Copy

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.

Create preview routes

Create two routes to handle previews: /api/preview and /api/exit-preview.

/api/preview starts Next.js Draft Mode when using the App Router or Preview Mode when using the Pages Router. It also redirects content writers from Prismic to their previewed document’s webpage. Create the route with the following file:

App Router
Pages Router

App Router

src/app/api/preview/route.js

Copy

import { redirectToPreviewURL } from "@prismicio/next";
import { createClient } from "@/prismicio";

/**
 * @param {import("next/server").NextRequest} request
 */
export async function GET(request) {
  const client = createClient();

  return await redirectToPreviewURL({ client, request });
}

Pages Router

src/pages/api/preview.js

Copy

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

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

  await setPreviewData({ req, res })

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

/api/exit-preview ends Next.js Draft Mode or Preview Mode when content writers end their preview session. Create the route with the following file:

App Router
Pages Router

App Router

src/app/api/exit-preview/route.js

Copy

import { exitPreview } from "@prismicio/next";

export async function GET() {
  return await exitPreview();
}

Pages Router

src/pages/api/exit-preview.js

Copy

import { exitPreview } from "@prismicio/next";

export async function handler(req, res) {
  return await exitPreview({ req, res });
}

Usage

`<PrismicNextImage>`

Copy

import { PrismicNextImage } from '@prismicio/next'

A custom next/image React component that renders an optimized image from a Prismic image field.

Copy

<PrismicNextImage field={doc.data.imageField} />

It automatically forwards the image’s URL and dimensions to next/image. It accepts all next/image props except src.

If the image field is empty, the component will render null by default. Use the fallback prop to render a custom value when a field is empty.

Copy

<PrismicNextImage
  field={doc.data.imageField}
  fallback={<p>The field is empty!</p>}
/>

The image CDN which Prismic serves all images through, imgix, allows image transformations using URL parameters. imgix URL parameters can be provided to <PrismicNextImage> using the imgixParams prop.

Copy

// Renders a grayscale image
<PrismicNextImage field={doc.data.imageField} imgixParams={{ sat: -100 }} />

See imgix's Image URL API Reference for a full list of what's available, including saturation changes, cropping, and blurring.

By default, <PrismicNextImage> uses a Prismic-specific imgix next/image loader. Most apps will not need to change the default loader.

To use Next.js’s built-in Image Optimization API, provide loader={undefined} to the component.

Copy

// Use Next.js's built-in Image Optimization API
<PrismicNextImage field={doc.data.imageField} loader={undefined} />

Like the base next/image component, custom loaders can be provided to the loader prop.

Copy

// Use a custom loader
<PrismicNextImage field={doc.data.imageField} loader={yourCustomLoader} />

Image transformations made via the imgixParams prop will be applied before passing the image URL to the loader.

The component automatically applies the image field’s alt text to the rendered <img> element. To customize the alt text, use the alt prop.

Copy

<PrismicNextImage field={doc.data.imageField} alt='' />

To provide a fallback alt text to be used if the image field does not contain alt text, use the fallbackAlt prop.

Copy

<PrismicNextImage field={doc.data.imageField} fallbackAlt='' />

The alt and fallbackAlt props only accept an empty string ('') to let you declare an image as decorative. Any other value is invalid. See the “alt must be an empty string” article for more details.

`<PrismicNextLink>`

Copy

import { PrismicNextLink } from '@prismicio/next'

A custom next/link React component that renders a link from a Link field or Prismic document. It accepts all next/link props except href.

Copy

// With a Link field
<PrismicNextLink field={doc.data.linkField}>Click me!</PrismicNextLink>

// With a Prismic document
<PrismicNextLink document={doc}>Click me!</PrismicNextLink>

It automatically forward’s the link’s URL and target attribute to next/link.

Links to external URLs will automatically include rel="noreferrer". This behavior can be overridden using the rel prop.

Copy

// Set an explicit rel in all cases
<PrismicNextLink field={doc.data.linkField} rel="author">
  Click me!
</PrismicNextLink>

// Use a function to determine the rel
<PrismicNextLink
  field={doc.data.linkField}
  rel={({ href, isExternal, target }) =>
    isExternal ? 'noreferrer nofollow' : undefined
  }
>
  Click me!
</PrismicNextLink>

// Remove rel in all cases
<PrismicNextLink field={doc.data.linkField} rel={undefined}>
  Click me!
</PrismicNextLink>

If your Next.js app uses a link resolver, the Link Resolver function can be provided to the linkResolver prop.

Copy

import { linkResolver } from '@/prismicio'

<PrismicNextLink
  field={doc.data.linkField}
  linkResolver={linkResolver}
>
  Click me!
</PrismicNextLink>

`<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 '@prismicio/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():

pages/api/preview.js

Copy

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'

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

  enableAutoPreviews({ client, req, previewData })

  return client
}

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

Link Resolvers in the App Router

@prismicio/next v1.1 and later includes support for Next.js’ App Router. Apps built using the App Router use React Server Components by default, which behave differently than apps built using the Pages Router.

If your app uses a link resolver, we recommend creating a wrapper component for <PrismicNextLink> in your project containing the link resolver. Using your wrapper component will remove the need to pass the link resolver function to every <PrismicNextLink> in your app.

The following example shows a typical wrapper for <PrismicNextLink>.

src/components/PrismicNextLink.tsx

Copy

import {
  PrismicNextLink as BasePrismicNextLink,
  PrismicNextLinkProps,
} from '@prismicio/next'

import { linkResolver } from '@/prismicio'

export const PrismicNextLink = (props: PrismicNextLinkProps) => {
  return <BasePrismicNextLink linkResolver={linkResolver} {...props} />
}

We recommend you do the same for @prismicio/react’s <PrismicRichText> component.

src/components/PrismicRichText.tsx

Copy

import {
  PrismicRichText as BasePrismicRichText,
  PrismicRichTextProps,
} from '@prismicio/react'

import { linkResolver } from '@/prismicio'

export const PrismicRichText = (props: PrismicRichTextProps) => {
  return <BasePrismicRichText linkResolver={linkResolver} {...props} />
}

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.

@prismicio/next Technical Reference - v1

Overview

Dependencies and requirements

Are you using Next v12 or lower?

Installation

Install packages

Create an optional link resolver

Add <PrismicPreview> to your app

Create preview routes

Usage

<PrismicNextImage>

<PrismicNextLink>

<PrismicPreview>

setPreviewData()

redirectToPreviewURL()

exitPreview()

enableAutoPreviews()

Link Resolvers in the App Router

Add `<PrismicPreview>` to your app

`<PrismicNextImage>`

`<PrismicNextLink>`

`<PrismicPreview>`

`setPreviewData()`

`redirectToPreviewURL()`

`exitPreview()`

`enableAutoPreviews()`