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

This page documents all APIs provided by @prismicio/next.

Install

@prismicio/next is installed when bootstrapping a Next.js 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

All components can be imported as a named import.

The following example imports PrismicNextImage:

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

`<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. See an example.

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

(field: ContentRelationshipField) => string | null | undefined

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.

`<PrismicPreview>`

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

parameter

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

parameter

Description

Default

client

Client

A Prismic client.

request

NextRequest

The request object from a Route Handler.

linkResolver

optional

(field: ContentRelationshipField) => string | null | undefined

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

parameter

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

@prismicio/next - v2

Overview

Install

Use with the Pages Router

API

`<PrismicNextImage>`

`<PrismicNextLink>`

`<PrismicPreview>`

`enableAutoPreviews()`

`redirectToPreviewURL()`

`exitPreview()`

`setPreviewData()`

`createLocaleRedirect()`

Upgrade from v1

Install `@prismicio/next` v2

Replace `CreateClientConfig` in `prismicio.ts`

Update imports when using the Pages Router

Replace `createLocaleRedirect()`