@prismicio/next - v2

Overview

@prismicio/next is the official Prismic package for creating Next.js websites.

With this package, you can:

Set up Prismic previews.
Display Prismic images using next/image.
Display Prismic links using next/link.

Install

@prismicio/next is automatically installed when bootstrapping a project with @slicemachine/init.

npx @slicemachine/init@latest

It can also be manually installed in any Next.js project:

npm install --save @prismicio/next @prismicio/client

@prismicio/client is a peer dependency and must be installed.

Use with the Pages Router

@prismicio/next supports the App Router (recommended) and the Pages Router.

To use @prismicio/next with the Pages Router, import components and helpers using the @prismicio/next/pages entry.


import { PrismicPreview } from "@prismicio/next/pages";

The /pages entry provides Pages Router-specific implementations.

API

`<PrismicNextImage>`

Displays an optimized image from an image field using next/image.

<PrismicNextImage field={slice.primary.image} />

Prop	Description	Default
`field`	`ImageField` An image field to display.
`imgixParams`optional	`object` An object of imgix URL parameters.
`alt`optional	`""` Declare an image as decorative.
`fallbackAlt`optional	`""` Declare an image as decorative if the image field does not have alt text.
`fallback`optional	`ReactNode` Rendered if the image is empty.	`null`
`loader`optional	`function` Use a custom `next/image` loader. Images are served via imgix by default.
`...rest`optional	All `next/image` props are supported except `src`.

`<PrismicNextLink>`

Displays a link from a link field or Prismic document using next/link.

<PrismicNextLink field={slice.primary.link} />

Prop	Description	Default
`field`	`LinkField` A link field to link. Only one of `field`, `document`, or `href` can be used.
`document`	`PrismicDocument` A Prismic document to link. Only one of `field`, `document`, or `href` can be used.
`href`	`string` A URL to link. Only one of `field`, `document`, or `href` can be used.
`rel`optional	`undefined \| string \| function` A `ref` attribute. A function can be passed to determine the value based on the link.
`linkResolver`optional	`function` A link resolver function used to determine a URL from the `field` or `document` prop. If it returns a value, it takes priority over a route resolver.
`...rest`optional	All `next/link` props are supported.

`<PrismicPreviews>`

Adds support for content previews by including the Prismic toolbar and event listeners. Webpages are automatically refreshed when a new content draft is saved.

<PrismicPreview repositoryName="example-prismic-repo" />

Prop	Description	Default
`repositoryName`	`string` The Prismic repository name.
`updatePreviewURL`optional	`string` The URL fetched when draft content is updated.	`/api/preview`
`exitPreviewURL`optional	`string` The URL fetched when exiting a preview session.	`/api/exit-preview`

`enableAutoPreviews()`

Configures a Prismic client to automatically fetch draft content during a preview session.

enableAutoPreviews({ client });

Argument	Description	Default
`client`	`Client` A Prismic client.

`redirectToPreviewURL()`

Redirects a content writer to a previewed document’s URL. This function should only be called in a Route Handler.

redirectToPreviewURL({ client, request });

Argument	Description	Default
`client`	`Client` A Prismic client.
`request`	`NextRequest` The `request` object from a Route Handler.
`linkResolver`optional	`function` A link resolver function used to determine a document’s URL. If it returns it value, it takes priority over a route resolver.
`defaultURL`optional	`string` The default redirect URL if a URL cannot be determined for the previewed document.	`/`

`exitPreview()`

Ends a Prismic preview by exiting Draft Mode. This function should only be called in a Route Handler.

exitPreview();

`setPreviewData()`

Sets data in Next.js’ Preview Mode cookie needed to support content previews. This function should only be called in an API Route.

setPreviewData({ req, res });

Argument	Description	Default
`req`	`NextApiRequest` The `req` object from an API Route.
`res`	`NextApiResponse` The `res` object from an API Route.

`createLocaleRedirect()`

Upgrade from v1

Follow these steps to upgrade an existing project to @prismicio/next v2.

Install @prismicio/next v2
```
npm install @prismicio/next@^2
```

Replace `CreateClientConfig` in `prismicio.ts`

CreateClientConfig is deprecated when using the App Router; the previewData and req options do not apply.

Use @prismicio/client’s ClientConfig instead.

prismicio.ts

import { CreateClientConfig } from "@prismicio/next"; 
import { ClientConfig } from "@prismicio/client"; 

export function createClient(
  config: CreateClientConfig = {}, 
  config: ClientConfig = {}, 
) {
  const client = prismic.createClient(repositoryName, {
    // ...
    ...config,
  });

  prismicNext.enableAutoPreviews({ client, previewData, req }); 
  prismicNext.enableAutoPreviews({ client }); 

  return client;
}

Update imports when using the Pages Router
This step is only necessary for websites using the Pages Router.
Change all imports from @prismicio/next to @prismicio/next/pages.
```
import { PrismicNextImage } from "@prismicio/next"; 

import { PrismicNextImage } from "@prismicio/next/pages"; 
```
Replace createLocaleRedirect()
This step is only necessary for websites using createLocaleRedirect().
See Replace createLocaleRedirect() for upgrade instructions