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.
This guide does not assume any prior knowledge of React and Next.js, but a basic understanding would be helpful. For an introduction, see the documentation 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@latestThis command will do the following:
- Create a new Prismic repository or let you specify an existing one.
- Add a slicemachine script to package.json.
- Create an sm.json configuration file containing your API endpoint and the location of your Slice library.
- Detect your framework (Next.js).
- Install dependencies: @prismicio/client, @prismicio/slice-simulator-react, @prismicio/react, @prismicio/next, and slice-machine-ui.
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
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:
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.
<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:
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.
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:
import { SliceSimulator } from "@prismicio/slice-simulator-react";
import { SliceZone } from "@prismicio/react";
import { components } from "../slices";
const SliceSimulatorPage = () => (
<SliceSimulator
sliceZone={({ slices }) => (
<SliceZone slices={slices} components={components} />
)}
state={{}}
/>
);
export default SliceSimulatorPage;Then, open sm.json (at the root of your project), and add a property for the Slice Simulator URL:
"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.
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.