@prismicio/react - v2 Migration Guide

This is a guide for upgrading a project using prismic-reactjs v1 to @prismicio/react v2.

Overview

This is a guide for upgrading a project using prismic-reactjs v1 to @prismicio/react v2.

In addition to a new package name, @prismicio/react v2 provides a more focused, more React-like set of components and hooks that facilitate rendering Prismic content.

The following instructions walk you through upgrading to the updated package.

Benefits of upgrading

Declaratively render slice zones
Easier Rich Text field rendering customization
Handle internal and external links with a smart link component
Fetch Prismic content using hooks
First-class TypeScript support

Update packages in package.json

Update your package.json to use the latest version of @prismicio/react.

{
  "dependencies": {
    "@prismicio/react": "^2.0.0"
  }
}

Remove prismic-reactjs from your package.json. @prismicio/react v2 replaces the previous prismic-reactjs package.

  {
    "dependencies": {
-     "prismic-reactjs": "^2.2.6"
    }
  }

Update your installed packages with npm.

npm install

Handling breaking changes

The following changes are required when upgrading to @prismicio/react v2.

Replace `<RichText>` with `<PrismicRichText>`

The <RichText> component has been replaced by a new component called <PrismicRichText>. The new component renders Rich Text and Title fields like the previous component, but with different props.

Rename the render prop to field. The field prop accepts a Rich Text or Title field.

  <PrismicRichText
-   render={document.data.myRichTextField}
+   field={document.data.myRichTextField}
  />

Rename the htmlSerializer prop to components. The components prop accepts an HTML Serializer, like the previous component, but also accepts a simpler object form instead (see Convert HTML Serializer function to an object in the New Features section below).

  <PrismicRichText
    field={document.data.description}
-   htmlSerializer={
+   components={
      (type, node, text, children, key) => {
        // Your serializer
      }
    }
  />

Remove the serializeHyperlink prop. By default, <PrismicRichText> will render links using <PrismicLink>. The behavior of <PrismicLink> can be customized with the following props:

internalLinkComponent: The component rendered for internal links.
externalLinkComponent: The component rendered for external links.

  <PrismicRichText
    field={document.data.description}
-   serializeHyperlink={customLink}
+   internalLinkComponent={({ href, ...props }) => (
+     <Link to={href} {...props} />
+   )}
  />

It can also be customized in a centralized location in <PrismicProvider> (see Configure components in <PrismicProvider> in the New Features section below).

To completely replace the component used for links, use the components prop to return a React component for the hyperlink block type.

<PrismicRichText
  field={document.data.description}
  components={{
    hyperlink: ({ children, node }) => {
      /* Your custom link component */
    },
  }}
/>

Replace `RichText.asText()` with `<PrismicText>` or `asText()`

The RichText.asText() function has been replaced by a React component called <PrismicText>. If your app uses RichText.asText() within a component’s return value, you can replace it with the new component.

- import { RichText } from 'prismic-reactjs'
+ import { PrismicText } from '@prismicio/react'

  <p>
-   {RichText.asText(document.data.description)}
+   <PrismicText field={document.data.description} />
  </p>

If your app uses RichText.asText() to convert a Rich Text or Title field to a string outside a component’s return value, you can replace it with @prismicio/helpers’s asText() function. Note that you will need to install @prismicio/helpers if you don’t already have it installed.

- import { RichText } from 'prismic-reactjs'
+ import * as prismicH from '@prismicio/helpers'

  const App = () => {
-   const description = RichText.asText(document.data.description)
+   const description = prismicH.asText(document.data.description)

    // The rest of your component...
  }

Replace `Link.url()` with `<PrismicLink>` or `asLink()`

The Link.url() function has been replaced by a React component called <PrismicLink>. If you app uses Link.url() within a component’s return value, you can replace it with the new component.

- import { Link } from 'prismic-reactjs'
+ import { PrismicLink } from '@prismicio/react'

- <a href={Link.url(document.data.link)}>Click me</a>
+ <PrismicLink field={document.data.link}>Click me</PrismicLink>

If your app uses Link.url() to convert a Link field to a URL string outside a component’s return value, you can replace it with @prismicio/helpers’s asLink() function. Note that you will need to install @prismicio/helpers if you don’t already have it installed.

- import { Link } from 'prismic-reactjs'
+ import * as prismicH from '@prismicio/helpers'

  const App = () => {
-   const url = Link.url(document.data.link)
+   const url = prismicH.asLink(document.data.link)

    // The rest of your component...
  }

Replace `Date()` with `asDate()`

The Date() function has been removed from the React library. Replace it with @prismicio/helpers’s asDate() function. It accepts the same arguments and returns the same JavaScript Date object as the previous Date() function.

- import { Date } from 'prismic-reactjs'
+ import * as prismicH from '@prismicio/helpers'

- Date(document.data.date)
+ prismicH.asDate(document.data.date)

Replace `Elements` with `Element`

If your app uses an HTML Serializer, replace the Elements import with the Element import (note that the “s” has been removed). The renamed object contains the same values but requires a different import name.

- import { Elements } from 'prismic-reactjs'
+ import { Element } from '@prismicio/react'

New features

While migrating to @prismicio/react v2, you may also want to make use of new features included in the upgraded library.

The following steps are optional but recommended.

Configure components in `<PrismicProvider>`

Certain components in @prismicio/react can be customized in a central <PrismicProvider> component at the top of your app’s component tree. This lets you define how components are rendered throughout your whole app.

The following components and hooks can be configured in the provider:

<PrismicLink>: Define your app’s Link Resolver and internal and external link components.
<PrismicRichText>: Define your app’s standard collection of components for Rich Text rendering.
All data-fetching hooks: Define the Prismic API client used to fetch content from your Prismic repository.

See the @prismicio/react Technical Reference for more details.

Use `<PrismicLink>` to render links

<PrismicLink> provides a way to render all links in your app. It supports Prismic Link fields and standard URLs. It can automatically render different components for internal and external links (helpful when you have a client-site router that needs a special <Link> component).

<PrismicLink field={document.data.myLinkField}>
  Click me
</PrismicLink>

See the @prismicio/react Technical Reference for more details on what <PrismicLink> can do.

Convert HTML Serializer function to an object

<PrismicRichText> supports the function form of an HTML Serializer through the components prop. It now also supports a simpler, more condensed object form. It serves the same purpose as the function form but with less code.

<PrismicRichText
  field={document.data.myRichTextField}
  components={{
    heading1: ({ children }) => (
      <Heading>{children}</Heading>
    ),
    paragraph: ({ children }) => (
      <p className="paragraph">{children}</p>
    ),
  }}
/>

See the @prismicio/react Technical Reference for more details on writing an object HTML Serializer.

Declaratively render slice zones

Apps typically contain a .map() function with a switch statement to render slice zones. To simplify the process of rendering a slice zone, a <SliceZone> component has been added to the library. It accepts a list of slices and a component for each slice type and renders it accordingly.

<SliceZone
  slices={document.data.body}
  components={{
    text: TextSlice,
    images: ImagesSlice,
  }}
/>

See the @prismicio/react Technical Reference for more details on rendering slice zones.

Add the Prismic Toolbar with `<PrismicToolbar>`

The Prismic Toolbar is essential to support content previews in your app. This is typically done by adding a <script> element in the <head> of your app. To simplify this setup, a <PrismicToolbar> component has been added to the library. It just needs your Prismic repository name to render the appropriate <script> element.

<PrismicToolbar repositoryName="repo-name" />

TypeScript

@prismicio/react is written in TypeScript with TypeScript users in mind. All components and hooks exported by the updated package include types so you will benefit without any changes to your code.

The package exports a collection of types that may be useful throughout your projects.

See the @prismicio/react TypeScript documentation for a list of the available types.

@prismicio/react - v2 Migration Guide

Overview

Benefits of upgrading

Update packages in package.json

Handling breaking changes

Replace <RichText> with <PrismicRichText>

Replace RichText.asText() with <PrismicText> or asText()

Replace Link.url() with <PrismicLink> or asLink()

Replace Date() with asDate()

Replace Elements with Element