@prismicio/helpers - v2 Migration Guide

Overview

This is a guide for upgrading a project using @prismicio/helpers v1 and/or prismic-dom v2 to @prismicio/helpers v2.

For reference, here are the purposes for each package:

• @prismicio/helpers v1 - A small collection of content converters.
• prismic-dom v2 - A larger collection of content converters designed for HTML usage. It re-exports @prismicio/helpers.

@prismicio/helpers v2 replaces both libraries with a simpler, more focused API. The following instructions walk you through upgrading to the updated unified package.

Benefits of upgrading

• ~50% smaller bundle size than @prismicio/helpers v1 + prismic-dom v2
• ~40x faster Rich Text HTML serialization
• More intuitive Rich Text HTML customization
• Shorter, more idiomatic import names
• First-class TypeScript support

Update packages in package.json

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

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

• Remove prismic-dom from your package.json if it is being used. @prismicio/helpers v2 includes all functionality previously provided by prismic-dom.

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

• Update your installed packages with npm.

npm install

Handling breaking changes

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

Replace prismic-dom imports with @prismicio/helpers

Replace imports for prismic-dom with @prismicio/helpers. As a convention, all code examples will use import * as prismicH when importing @prismicio/helpers, but this can be modified depending on your preferences.

- import PrismicDOM from 'prismic-dom'
+ import * as prismicH from '@prismicio/helpers'

Replace Date() with asDate()

prismic-dom provides a Date() function to convert a document’s Date or Timestamp field value to a JavaScript Date object.

Replace this function with @prismicio/helpers’s asDate() function. It accepts the same argument and returns the same JavaScript Date object as the previous Date() function.

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

Replace Link.url() with asLink()

prismic-dom provides a Link.url() function to convert a document’s Link field value to a URL string.

Replace this function with @prismicio/helpers’s asLink() function. It accepts the same arguments and returns the same URL string as the previous Link.url() function.

- PrismicDOM.Link.url(document.data.link, linkResolver)
+ prismicH.asLink(document.data.link, linkResolver)

Replace RichText.asText() with asText()

prismic-dom provides a RichText.asText() function to convert a document’s Rich Text or Title field value to a plain text string.

Replace this function with @prismicio/helpers’s asText() function. It accepts the same argument and returns the same plain text string as the previous RichText.asText() function.

- PrismicDOM.RichText.asText(document.data.title)
+ prismicH.asText(document.data.title)

Replace RichText.asHtml() with asHTML()

prismic-dom provides a RichText.asHtml() function to convert a document’s Rich Text or Title field value to an HTML string.

Replace this function with @prismicio/helpers’s asHTML() function. It accepts the same arguments and returns the same HTML string as the previous RichText.asHTML() function.

- PrismicDOM.RichText.asHtml(document.data.description, linkResolver, htmlSerializer)
+ prismicH.asHTML(document.data.description, linkResolver, htmlSerializer)

Replace RichText.Elements with Element

prismic-dom’s RichText.asHtml() function accepts an HTML Serializer function that allows you control how a document’s Rich Text or Title field is converted to HTML. prismic-dom provides a RichText.Elements object to help determine the type of a Rich Text block within this function.

Replace this object with @prismicio/helpers’s Element object (note the change from “Elements” with an “s” to “Element” without an “s”). It contains the same values but requires a different import name and style.

- import PrismicDOM from 'prismic-dom'
- const Elements = PrismicDOM.RichText.Elements

+ import * as prismicH from '@prismicio/helpers'
+ const Element = prismicH.Element

Update children in HTML Serializers

When using an HTML Serializer with prismic-dom’s RichText.asHTML() function, a block’s children are given as an array of strings. A serializer typically will use children.join('') to convert it to a single string.

@prismicio/helpers performs this conversion for you automatically. Replace children.join('') with children since the argument is already a single string.

  function htmlSerializer(type, element, content, children, key) {
    switch (type) {
      case Element.paragraph: {
-       return `<p class="paragraph-class">${children.join('')}</p>`
+       return `<p class="paragraph-class">${children}</p>`
      }
    }
  }

New features

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

The following steps are optional but recommended.

Convert HTML Serializer function to an object

prismic-dom’s RichText.asHtml() function accepts an HTML Serializer function that allows you control how a document’s Rich Text or Title field is converted to HTML.

@prismicio/helpers’s asHTML() function accepts the same HTML Serializer function but also accepts an easier-to-write object version. With the object version, you can provide a list of block type names mapped to a function returning an HTML string.

Here is an HTML Serializer function:

import { Element } from "@prismicio/helpers";

function htmlSerializer(type, element, content, children) {
  switch (type) {
    case Element.paragraph: {
      return `<p class="paragraph-class">${children}</p>`;
    }
  }
}

Here is an HTML Serializer object:

const htmlSerializer = {
  // Arguments can be destructured for each block type
  paragraph: ({ children }) =>
    `<p class="paragraph-class">${children}</p>`,
};

Either HTML Serializer can be passed to asHTML().

import * as prismicH from "@prismicio/helpers";

prismicH.asHTML(
  document.data.description,
  linkResolver,
  htmlSerializer,
);
// => <p class="paragraph-class">Lorem ipsum…</p>

TypeScript

@prismicio/helpers is written in TypeScript with TypeScript users in mind. All functions 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/helpers TypeScript documentation for a list of the available types.