NEW

Prismic offers an ideal solution to feature your e-commerce products in your promotional landing pages or inspirational content. View more

Updated JavaScript Client and Helpers

Written by Angelo Ashmore in engineering on January 04, 2022

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:

@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:

@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.

💬 Suggest an improvement

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

🧑‍💻 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.

We hope you like the changes we've made and are excited to hear what you think of them. 🚀

Profile picture

Angelo Ashmore

Developer Experience Engineer at Prismic focusing on Gatsby, React, and TypeScript, in no particular order.