Set up 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.

Prerequisites

Before you get started, you will need a Next.js project initialized. If you don't have one, visit the Next.js docs to learn how to create one.

What package versions does this guide use?

This guide uses @prismicio/client version 6, @prismicio/react version 2, @prismicio/next version 1, and slice-machine-ui version 0.3.0.

If you already have a project that uses older packages, see the @prismicio/client v6 Migration Guide, @prismicio/react v2 Migration Guide, and next-slicezone Deprecation Guide.

Run setup command

In the root of your Next.js project, run the following command:

Copy
npx @slicemachine/init

This command will do the following:

  1. Create a new Prismic repository or let you specify an existing one.
  2. Add a slicemachine script to package.json.
  3. Create an sm.json configuration file containing your API endpoint and the location of your Slice library.
  4. Detect your framework (Next.js).
  5. Install dependencies: @prismicio/client, @prismicio/slice-simulator-react, @prismicio/react, and slice-machine-ui.

Next, install @prismicio/next:

Copy
npm install @prismicio/next

What do these dependencies do?

  • @prismicio/client is responsible for fetching data from the Prismic API
  • @prismicio/react renders data from Prismic as React components
  • @prismicio/next enables previewing functionality
  • slice-machine-ui is a local development environment for building Slices
  • @prismicio/slice-simulator-react provides an environment to simulate Slices as you build them

Configure Prismic

Create a file called prismicio.js at the root of your project. This file will contain configurations for your project. (To learn how to add other configurations, see the @prismicio/client Technical Reference.)

Paste in the following code:

prismicio.js
Copy
import * as prismic from '@prismicio/client'
import * as prismicNext from '@prismicio/next'
import sm from './sm.json'

/**
 * The project's Prismic repository name.
 */
export const repositoryName = prismic.getRepositoryName(sm.apiEndpoint)

// Update the routes array to match your project's route structure
/** @type {prismic.ClientConfig['routes']} **/
const routes = [
  {
    type: 'homepage',
    path: '/',
  },
  {
    type: 'page',
    path: '/:uid',
  },
]

/**
 * Creates a Prismic client for the project's repository. The client is used to
 * query content from the Prismic API.
 *
 * @param config {prismicNext.CreateClientConfig} - Configuration for the Prismic client.
 */
export const createClient = (config = {}) => {
  const client = prismic.createClient(sm.apiEndpoint, {
    routes,
    ...config,
  })

  prismicNext.enableAutoPreviews({
    client,
    previewData: config.previewData,
    req: config.req,
  })

  return client
}

In prismicio.js, customize the routes array to match the routing of your project. For each Custom Type that corresponds to a page in your app, add an object that describes the route for that page. Learn more about how the Route Resolver works.

Add <PrismicProvider> and <PrismicPreview>

<PrismicProvider> and <PrismicPreview> are components that wrap your entire app in /pages/_app.js. <PrismicProvider> provides Prismic utilities and settings. <PrismicPreview> enables previewing. Add them to your app like this:

pages/_app.js
Copy
import Link from 'next/link'
import { PrismicProvider } from '@prismicio/react'
import { PrismicPreview } from '@prismicio/next'
import { repositoryName } from '../prismicio'

export default function App({ Component, pageProps }) {
  return (
    <PrismicProvider internalLinkComponent={(props) => <Link {...props} />}>
      <PrismicPreview repositoryName={repositoryName}>
        <Component {...pageProps} />
      </PrismicPreview>
    </PrismicProvider>
  )
}

The internalLinkComponent prop specifies what component to use for internal links. This code snippet passes a Next.js link component.

You now have Prismic utilities available throughout your project, and your project is set up to handle previews (which you will finish configuring in a later step).

Now you can start creating Slices and Custom Types to model your project.

Create Slice Simulator page

Prismic provides an environment to simulate your Slices in development. This environment is generated by a page component located at /slice-simulator.

In your pages directory, create a file called slice-simulator.jsx. Inside, paste in this code:

pages/slice-simulator.js
Copy
import { SliceSimulator } from '@prismicio/slice-simulator-react'
import { SliceZone } from '@prismicio/react'

import { components } from '../slices'
import state from '../.slicemachine/libraries-state.json'

const SliceSimulatorPage = () => {
  return (
    <SliceSimulator
      sliceZone={({ slices }) => (
        <SliceZone slices={slices} components={components} />
      )}
      state={state}
    />
  )
}

export default SliceSimulatorPage

Then, open sm.json (at the root of your project), and add a property for the Slice Simulator URL:

sm.json
Copy
"localSliceSimulatorURL": "http://localhost:3000/slice-simulator",

Ensure that the port (in this case 3000) matches the port that you run your application on in development.

Further learning: What is the Slice Simulator?

The Slice Simulator is a mini-app that simulates what your Slices will look like in production, using mock data. 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 Slice Simulator allows you to preview what your Slices will look like in production, saving you development time. The Slice Simulator also allows Slice Machine to take screenshots of your Slices, which it sends to Prismic. Prismic uses the screenshots as labels for your Slices in the editor, so your content team can see exactly what the Slice will look like when they add it to a document.

Storybook?

Slice Machine still generates Storybook stories for you in your project, learn how to configure Storybook for your Next.js project here.


Was this article helpful?
Not really
Yes, Thanks

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.