@prismicio/next - 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.

Installation

Install packages

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

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.)

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:

src/app/layout.tsx

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>
  );
}

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:

src/app/api/preview/route.js

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 });
}

/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:

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

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

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

Usage

`<PrismicNextImage>`

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

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

<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.

<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.

// 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.

// 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.

// 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.

<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.

<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>`

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.

// With a link field
<PrismicNextLink field={doc.data.linkField} />

// With a link field and custom children
<PrismicNextLink field={document.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.

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

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

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

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

import { linkResolver } from "@/prismicio";

<PrismicNextLink
  field={doc.data.linkField}
  linkResolver={linkResolver}
/>;

`<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.

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()`

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

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()`

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()`

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():

// pages/api/preview.js

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

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

`enableAutoPreviews()`

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():

// 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

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

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

import { linkResolver } from "@/prismicio";

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

@prismicio/next - v1

Overview

Dependencies and requirements

Installation

Install packages

Create an optional link resolver

Add <PrismicPreview> to your app

Create preview routes

Usage

<PrismicNextImage>

<PrismicNextLink>

<PrismicPreview>

setPreviewData()

redirectToPreviewURL()

exitPreview()

enableAutoPreviews()