---
title: "@prismicio/helpers - v2 Migration Guide"
description: "This is a guide for upgrading a project using @prismicio/helpers v1 and/or prismic-dom v2 to @prismicio/helpers v2."
meta_title: "@prismicio/helpers v2 Migration Guide"
audience: developers
lastUpdated: "2025-11-06T01:07:50.000Z"
---

# 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

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

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

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

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

3. Update your installed packages with `npm`.

```bash
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.

```diff
- 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.

```diff
- 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.

```diff
- 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.

```diff
- 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.

```diff
- 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.

```diff
- 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.

```diff
  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**:

```tsx
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**:

```tsx
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()`.

```tsx
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.