---
title: "@prismicio/next - v0.1"
category: "api-references"
audience: developers
lastUpdated: "2025-11-06T01:07:50.000Z"
---

# Overview

`@prismicio/next` is the official Prismic package for creating web apps with Prismic and [Next.js](https://nextjs.org/).

#

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

```bash
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](https://prismic.io/docs/route-resolver.md).)

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

```tsx
// _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

## `<PrismicNextImage>`

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

A custom [`next/image`](https://nextjs.org/docs/api-reference/next/image) React component that renders an optimized image from a Prismic image field.

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

The image CDN which Prismic serves all images through, [imgix](https://imgix.com/), allows image transformations using URL parameters. imgix URL parameters can be provided to `<PrismicNextImage>` using the `imgixParams` prop.

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

See [imgix's Image URL API Reference](https://docs.imgix.com/apis/rendering) 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](https://nextjs.org/docs/api-reference/next/image#loader). Most apps will not need to change the default loader.

To use Next.js’s built-in [Image Optimization API](https://nextjs.org/docs/api-reference/next/image#built-in-loaders), provide `loader={undefined}` to the component.

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

Like the base `next/image` component, [custom loaders](https://nextjs.org/docs/api-reference/next/image#loader) can be provided to the `loader` prop.

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

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

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

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

<Table>
  <tbody>
    <tr>
      <TableCell>`req` required</TableCell> <TableCell>The API route’s req object.</TableCell>
    </tr>

    <tr>
      <TableCell>`res` required</TableCell> <TableCell>The API route’s res object.</TableCell>
    </tr>
  </tbody>
</Table>

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

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

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

<Table>
  <tbody>
    <tr>
      <TableCell>`req`</TableCell> <TableCell>The API route’s `req` object.</TableCell>
    </tr>

    <tr>
      <TableCell>`res`</TableCell> <TableCell>The API route’s `res` object.</TableCell>
    </tr>

    <tr>
      <TableCell>`client`</TableCell>

      <TableCell>
        A `@prismicio/client` client instance configured for your Prismic repository.
      </TableCell>
    </tr>

    <tr>
      <TableCell>`linkResolver`</TableCell>

      <TableCell>
        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](https://prismic.io/docs/route-resolver.md) for more information.
      </TableCell>
    </tr>
  </tbody>
</Table>

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

## `exitPreview()`

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

<Table>
  <tbody>
    <tr>
      <TableCell>`req` required</TableCell> <TableCell>The API route’s `req` object.</TableCell>
    </tr>

    <tr>
      <TableCell>`res` required</TableCell> <TableCell>The API route’s `res` object.</TableCell>
    </tr>
  </tbody>
</Table>

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

```tsx
// pages/api/preview.js

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

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

## `enableAutoPreviews()`

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

<Table>
  <tbody>
    <tr>
      <TableCell>`client` required</TableCell>

      <TableCell>
        A `@prismicio/client` client instance configured for your Prismic repository.
      </TableCell>
    </tr>

    <tr>
      <TableCell>`req`</TableCell>

      <TableCell>
        If `enableAutoPreviews()` is called in an API route, pass the route’s `req` object.
      </TableCell>
    </tr>

    <tr>
      <TableCell>`previewData`</TableCell>

      <TableCell>
        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.
      </TableCell>
    </tr>
  </tbody>
</Table>

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

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