First-Class TypeScript Integration, Refreshed APIs & More: New Development Kits, Now in Beta

Written by Lucie in Announcement on October 11,2021

To develop with Prismic we offer a variety of development kits to help you query our API and template content from it. We have kits for PHP, Ruby, and many others. Most importantly, we have kits for JavaScript and its derivative technologies. This post is about those kits and their future, refreshed versions.

TL;DR: Give a try to our new core kits by installing @prismicio/client@beta and @prismicio/helpers@beta. Your feedback is very much appreciated here to help us before the stable release in November.

Prismic JavaScript Ecosystem

Our current JavaScript kits fall into three categories:

  1. @prismicio/client and prismic-dom are our main, core JavaScript kits. They are used to query and template your repository content.
  2. @prismicio/vue, @prismicio/react, and others are higher-level JavaScript kits integrating with specific frameworks.
  3. Finally, kits like @nuxtjs/prismic and gatsby-source-prismic integrate deeper with the meta-frameworks they're named after.

These kits were doing OK and performed the jobs for which they were made. They were also aging and getting behind JavaScript's latest standards: TypeScript support was poor or non-existent, some APIs were legacy, bundle size was significant. With that in mind, we thought there were a lot of opportunities in refreshing those kits, so we started this process earlier this year.

Today we're happy to announce the release in beta of our new main JavaScript kits: @prismicio/client as a refreshed client and @prismicio/helpers as the new prismic-dom. This beta phase is scheduled to last for about a month before the stable release in the neighborhood of November.

What's New?

As teased in the title, the main highlights are:

  • First-class TypeScript integration: Proper TypeScript support was requested by many and we heard your call! Moving forward all our kits will now be fully typed and documented through TSDoc. This provides both JavaScript and TypeScript users with powerful Intellisense and in-editor documentation. For the latter, it also enables easier and stronger integration.
  • Refreshed APIs: Let's face it, there were some odd things with our kits. For example, why are there three ways to init the client? Well, we won't dive into the whats and whys here but we hope we did a great job of rethinking those. The new APIs should align better with your needs when developing with Prismic, more about them below.
  • Better performance and bundle size: Performance and optimization were also among of our focuses. Rich text fields serialization is about 50 times faster now. Installing all our core kits now costs you only 5kb of gzipped content compared to more than 10 before, and that's before you tree-shake them (as this is now possible 🎉)!

@prismicio/client, your refreshed client

The client library has been reworked from the ground up. Notable changes include the addition of many new query helpers: getByType(), getByTag() and many others. These new helpers should reduce the need to use query predicates for most cases.

Another important change is the ability to provide your own fetch implementation through the new fetch option. This can help you solve challenges when working in specific environments like Cloudflare Workers or allow you to implement your own caching strategy:

import * as prismic from "@prismicio/client";
import fetch from "node-fetch";

const endpoint = prismic.getEndpoint("my-repository-name");
const client = prismic.createClient(endpoint, { fetch });

const pages = await client.getByType("page");

For comprehensive details, check out the client technical documentation.

@prismicio/helpers, the new prismic-dom

prismic-dom has been moved to @prismicio/helpers. Helpers offers a more straightforward interface. This kit simply exposes four functions: asDate(), asLink(), asHTML(), asText().

A few of the novelties are that asLink() can now resolve documents. asHTML() also supports a new kind of serializer: a map serializer that maps node types to shorter serializer functions:

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

const linkResolver = (doc) => `/${doc.uid}`;

const htmlSerializer = {
heading1: ({ children }) => `<h1 class="my-class">${children.join("")}</h1>`,
heading2: ({ children }) => `<h2 class="my-class">${children.join("")}</h2>`,
heading3: ({ children }) => `<h3 class="my-class">${children.join("")}</h3>`,
};

prismicH.asHTML(doc.data.text, linkResolver, htmlSerializer);

For comprehensive details, check out the helpers technical documentation.

How to Try the New Kits and Give Your Feedback

The beta is the opportunity for you to try our new kits. Your feedback on them, positive or negative, is very much appreciated. To try the new @prismicio/client:

Similarly for @prismicio/helpers:

Our Next Steps

As announced, the beta of @prismicio/client and @prismicio/helpers is meant to last about a month before the stable release in November. Our goal with it is to catch the remaining gotchas and to make sure our work aligns correctly with your needs.

Following these two kit releases will be the new @prismicio/react and @prismicio/vue kits. Their implementation is already done, and our team is in the process of documenting them. If that's your jam, stay tuned on our Twitter for any future announcements! 👀

Lucie Haberer

Lucie Haberer

A Developer Experience Engineer, Lucie is way too much into Nuxt.js but don't tell her, that's pointless. She also managed somehow to publish a package to NPM while giving a talk at a conference.