January 4, 2022·3 min read

Updated JavaScript Client and Helpers

We just published major updates to several of our core JavaScript packages (with TypeScript support!). The updated @prismicio/client and @prismicio/helpers packages feature refreshed APIs, built-in documentation using TSDoc, and a bunch of new helpful functions.

There are breaking changes in these updates. To help you update your projects, each package has its own Migration Guide (linked below in each section of this blog post) walking you through the necessary changes.

If you’re using Prismic with JavaScript, regardless of the framework or environment you’re working with, you’re going to want to check out these updates.

👉 TL;DR

@prismicio/client v6 is smaller and more intuitive to use.
@prismicio/helpers v2 is faster and more helpful throughout your project.
Detailed documentation and autocomplete are baked-in to the updated packages (thanks to TSDoc).
For TypeScript users, @prismicio/types contains TypeScript types for everything Prismic.
Check out each package’s Migration Guide to learn how to update.

Learn more about each package in their landing pages or read on for a quick summary.

@prismicio/client

This package is the primary tool used to query for a Prismic repository’s content in JavaScript/TypeScript projects.

Here’s what the refreshed client looks like in action:

import * as prismic from '@prismicio/client'

// Create a client
const repositoryName = 'your-repo-name'
const endpoint = prismic.getEndpoint(repositoryName)
const client = prismic.createClient(endpoint)

// Query for all Page documents
const pages = await client.getAllByType('page')

// Or query for a specific document
const blogPost = await client.getByUID('blog_post', 'hello-world')

New features in @prismicio/client v6

~25% smaller bundle size
More intuitive API names and options
New queryByType() and queryByTag() methods
Fetch all documents with getAll* queries
First-class TypeScript support

A Migration Guide is available to help you update and fix breaking changes.

Learn more about the new client here:

API Reference: @prismicio/client Technical Reference
How to upgrade: @prismicio/client v6 Migration Guide

@prismicio/helpers

This package is a collection of small functions to manipulate and work with Prismic content in JavaScript/TypeScript projects.

@prismicio/helpers v2 merges the now-deprecated prismic-dom package into a single, focused set of helpers.

Here’s a quick preview of some of the helpers:

import * as prismicH from '@prismicio/helpers'

// Get HTML from a Rich Text field
const html = prismicH.asHTML(document.data.description)

// Or plain text from the same field
const text = prismicH.asText(document.data.description)

// Check if an Image field contains an image
if (prismicH.isFilled.image(document.data.optionalImage)) {
  return (
    <img
      src="${document.data.optionalImage.url}"
      alt="${document.data.optionalImage.alt}"
    />
  )
}

// Get the URL of a Link field
const url = prismicH.asLink(document.data.link)

New features in @prismicio/helpers v2

~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

A Migration Guide is available to help you update and fix breaking changes.

Learn more about the new helpers here:

API Reference: @prismicio/helpers v2 Technical Reference
How to upgrade: @prismicio/helpers v2 Migration Guide

@prismicio/types

This package contains TypeScript types for all kinds of Prismic data, such as fields, documents, API responses, and more. All refreshed Prismic JavaScript libraries use these types to ensure everything works as expected.

Here’s a quick preview of how you could use the types in your project:

import * as prismicT from '@prismicio/types'

// Build a type for each Custom Type
type PrismicPage = prismicT.PrismicDocument<{
  title: prismicT.TitleField
  ogImage: prismicT.ImageField
  backgroundColor: prismicT.SelectField<'red', 'green', 'blue'>
}>

// Type your documents when querying with @prismicio/client
const page = client.getByUID<PrismicPage>('page', 'home')

(Psst… we’re experimenting with ways to automatically generate these types for you. Keep an eye out for an announcement! 👀)

How to give feedback or report bugs

As always, if you have any questions or run into issues with the new packages, please feel free to reach out for help with the methods below.

❓ Ask a question

Open a new topic on our community forum with your question explaining what you want to achieve. Our support team will get back to you shortly.

🐛 Report a bug

Open an issue on the package’s GitHub repository explaining your application's setup and the bug you're encountering.

@prismicio/client: Report a bug
@prismicio/helpers: Report a bug

💬 Suggest an improvement

Open an issue on the package’s GitHub repository explaining your improvement or feature so we can discuss and learn more.

@prismicio/client: Suggest an improvement
@prismicio/helpers: Suggest an improvement

🧑‍💻 Submit code changes

For small fixes, feel free to open a pull request on the package’s GitHub repository with a description of your changes. For large changes, please first open an issue so we can discuss if and how the changes should be implemented.