@prismicio/next - v0.1

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

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:

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

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.

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.

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