Install Prismic
This article explains how to install and configure Prismic in a Next.js project. By the end of this page, you will have Prismic utilities installed in your app.
Versions
This guide uses Next.js v13, @prismicio/client v7, @prismicio/react v2, @prismicio/next v1, and slice-machine-ui v1.
If you already have a project that uses older packages, see the @prismicio/client v7 Migration Guide, @prismicio/client v6 Migration Guide, @prismicio/react v2 Migration Guide, next-slicezone Deprecation Guide, and slice-machine-ui v1 Migration Guide.
This guide assumes basic knowledge of React and Next.js. If you are new to development with either, see the official introductions for React and Next.js.
Before proceeding, you will need a Next.js project. You can quickly create a brand new project using the following create-next-app command. (Read the official documentation to learn more):
- npx
- npm
- Yarn
npx create-next-app@latestnpm create next-appyarn create next-appThis command will prompt an option to name your project. After that you'll be able to open your newly created Next.js app.
Once it's finished, you'll have a brand new Next.js project where you can install Slice Machine.
npx @slicemachine/init@latestWhat happens when you run @slicemachine/init
The command executes the following actions in your codebase:
- Creates a new Prismic repository (or lets you specify an existing one).
- Adds a
start-slicemachinescript topackage.json. - Creates a
slicemachine.config.jsonconfiguration file containing the name of your Prismic repository and the location of your Slice library. - Creates a
prismicio.js|tsfile at the root of your project to configure Prismic. - Detects your framework (Next.js).
- Installs dependencies:
@prismicio/client,@prismicio/react,@prismicio/next,slice-machine-ui, and@slicemachine/adapter-next. - Creates a
pages/slice-simulator.js|jsx|tsxfile to simulate Slices.
That might seem like a lot of dependencies. Don't worry, they each perform an important function:
@prismicio/clientis responsible for fetching data from the Prismic API@prismicio/reactrenders data from Prismic as React components@prismicio/nextenables previewing draftsslice-machine-uiis a local development tool for building Slices@slicemachine/adapter-nextis the Next.js adapter for Slice Machine
We also mentioned that the init command creates a slice-simulator.js file. What does that file do? The Slice simulator is a mini-app that simulates what your Slices will look like in production. The Slice simulator uses an iframe, which runs locally, to simulate your Slices. The mock data is provided by Slice Machine and is customizable (see What Is Slice Machine? for more information).
The init script creates a file called prismicio.js at the root of your project. This file contains configurations for your project.
The most important configuration is the routes array, which is your route resolver. Update the route resolver to match the routing structure of your Next.js app. To learn more about how to add configurations, see the documentation for the route resolver and @prismicio/client.
The prismicio.js file is prefilled with an example routes array:
const routes = [
{
type: 'homepage',
path: '/',
},
{
type: 'page',
path: '/:uid',
},
]In prismicio.js, customize the routes array to match the routing of your project. For each page type, add an object that describes the route for that page. Learn more about how the route resolver works.
- Pages Router
- App Router
import { PrismicPreview } from '@prismicio/next'
import { repositoryName } from '@/prismicio'
export default function App({ Component, pageProps }) {
return (
<>
<Component {...pageProps} />
<PrismicPreview repositoryName={repositoryName} />
</>
)
}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>
)
}Add two routes to your app: /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:
- Pages Router
- App Router
import { setPreviewData, redirectToPreviewURL } from '@prismicio/next'
import { createClient } from '@/prismicio'
export default async (req, res) => {
const client = createClient({ req })
await setPreviewData({ req, res })
await redirectToPreviewURL({ req, res, client })
}import { draftMode } from "next/headers";
import { redirectToPreviewURL } from "@prismicio/next";
import { createClient } from "@/prismicio";
export async function GET(request) {
const client = createClient();
draftMode().enable();
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:
- Pages Router
- App Router
import { exitPreview } from "@prismicio/next";
export async function handler(req, res) {
return await exitPreview({ req, res });
}import { exitPreview } from "@prismicio/next";
export async function GET() {
return await exitPreview();
}Finish setting up previews by configuring your Prismic repository:
- In your Prismic repository, go to Settings > Previews
- Ignore the step about including the Prismic Toolbar (
<PrismicPreview>adds the toolbar for you) - Click Create Preview
- You’ll be prompted to input a site name, a domain for your application, and an optional preview route. Fill out the fields with the following information:
Domain:http://localhost:3000
Preview Route:/api/preview
You now have Prismic utilities available throughout your project, and your project is set up to handle previews.
Now you can start creating Slices and custom types to model your project.
Was this article helpful?
Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.