---
title: "@prismicio/client v6 Migration Guide"
description: "This is a guide for upgrading a project using @prismicio/client v5 to @prismicio/client v6."
meta_title: "@prismicio/client v6 Migration Guide"
audience: developers
lastUpdated: "2025-11-06T01:07:50.000Z"
---

# Overview

This is a guide for upgrading a project using `@prismicio/client` v5 to `@prismicio/client` v6.

`@prismicio/client` v6 includes a refreshed API and more flexibility in usage. The following instructions walk you through upgrading to the updated package.

## Benefits of upgrading

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

# Update package in package.json

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

```json
{
  "dependencies": {
    "@prismicio/client": "^6.0.0"
  }
}
```

Update your installed packages with npm.

```bash
npm install
```

# Handling breaking changes

## Replace default import with named import

Replace imports for `@prismicio/client` from a default import (usually `Prismic`) to a named export. As a convention, all code examples will use `import * as prismic` when importing `@prismicio/client`, but this can be modified depending on your preferences.

```diff
- import Prismic from '@prismicio/client'
+ import * as prismic from '@prismicio/client'
```

## Create a client with `createClient()`

Replace all client creation methods with `createClient()`. All other methods of creating a client, including `client()`, `getApi()`, and `api()`, have been replaced by the single `createClient()` function.

```diff
- const client = Prismic.client(endpoint)
- const client = await Prismic.getApi(endpoint)
- const client = await Prismic.api(endpoint)
+ const client = prismic.createClient(endpoint)
```

`createClient()` accepts a Prismic Content API endpoint and an object with options. The endpoint string can be created using the new `getEndpoint()` function which ensures the API CDN is used for the best performance.

```tsx
const endpoint = prismic.getEndpoint("my-repo-name");
const client = prismic.createClient(endpoint);
```

## Provide a `fetch()` function if necessary

In environments where a global `fetch()` function is not available, such as Node.js, provide a `fetch()` function when creating a client. [`node-fetch`](https://github.com/node-fetch/node-fetch) is a popular server-side `fetch()` implementation that is compatible. This replaces the existing `requestHandler` option with a more browser-friendly and more Web API-compatible approach.

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

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

Environments like the browser, [Next.js](https://nextjs.org/), [Cloudflare Workers](https://workers.cloudflare.com/), and [Remix](https://remix.run/) provide a global `fetch()` function and do not require passing your own.

## Replace network options with custom `fetch()` function

If your client requires custom network behavior, such as a proxy agent or a special cache, implement it using a custom `fetch()` function. A proxy agent, for example, can be implemented by using `node-fetch` and providing an `agent` option. A cache can be implemented by checking the URL for a cache hit before making a network request.

The exact migration steps will depend on your needs. You can perform any logic in the `fetch()` function provided that it returns a `Response` object containing the API response.

The following example integrates a custom cache:

```tsx
import * as prismic from "@prismicio/client";
import fetch from "node-fetch";
import QuickLRU from "quick-lru";

const endpoint = prismic.getEndpoint("qwerty");
const cache = new QuickLRU({
  maxSize: 1000, // 1000 entries
});

const client = prismic.createClient(endpoint, {
  fetch: async (url, options) => {
    // The cache key contains the requested URL and headers
    const key = JSON.stringify({ url, options });

    if (cache.has(key)) {
      // If the cache contains a value for the key, return it
      return cache.get(key);
    } else {
      // Otherwise, make the network request
      const res = await fetch(url, options);

      if (res.ok) {
        // If the request was successful, save it to the cache
        cache.set(key, res);
      }

      return res;
    }
  },
});
```

## Enable auto previews in server contexts

If your client is used in a server context, such as in an Express app or Next.js API route, call the `enableAutoPreviewsFromReq()` method to enable automatic preview support. It must be passed a Request-like object, such as one from Express or Next.js.

```diff
- const client = Prismic.client(endpoint, { req })
+ const client = prismic.createClient(endpoint)
+ client.enableAutoPreviewsFromReq(req)
```

`@prismicio/client` v5 supported this feature by providing a `req` option when creating the client. The `req` option is replaced by the `enableAutoPreviewsFromReq()` method.

## Replace `query()` with `get()`

Replace `query()` with `get()` by moving the query's predicates into a `predicate` option.

```diff
- const documents = client.query(
-   Prismic.Predicates.at('document.tags', 'food'),
-   { lang: 'fr-fr' }
- )
+ const documents = client.get({
+   predicates: prismic.predicate.at('document.tags', 'food'),
+   lang: 'fr-fr',
+ })
```

## Replace `Predicates` with `predicate`

If your queries use predicates, replace `Predicates` with `predicate`. The `predicate` object contains the same predicate functions as `Predicates` with new names to better match the API's predicate names.

```diff
- import { Predicates } from "@prismicio/client";
+ import * as prismic from "@prismicio/client";

- prismic.Predicates.gt('my.movie.rating', 3)
+ prismic.predicate.numberGreaterThan('my.movie.rating', 3)
```

The following predicates have been renamed:

* `dayOfMonth` → `dateDayOfMonth`
* `dayOfMonthAfter` → `dateDayOfMonthAfter`
* `dayOfMonthBefore` → `dateDayOfMonthBefore`
* `dayOfWeek` → `dateDayOfWeek`
* `dayOfWeekAfter` → `dateDayOfWeekAfter`
* `dayOfWeekBefore` → `dateDayOfWeekBefore`
* `month` → `dateMonth`
* `monthBefore` → `dateMonthBefore`
* `monthAfter` → `dateMonthAfter`
* `year` → `dateYear`
* `hour` → `dateHour`
* `hourBefore` → `dateHourBefore`
* `hourAfter` → `dateHourAfter`
* `gt` → `numberGreaterThan`
* `lt` → `numberLessThan`
* `inRange` → `numberInRange`
* `near` → `geopointNear`

## Replace `previewCookie` with `cookie.preview`

If you are using `previewCookie`, replace it with `cookie.preview`. The new import has the same value used to identify the Prismic preview cookie.

## Replace `getPreviewResolver()` with `resolvePreviewURL()`

In your app's preview resolver page, replace `getPreviewResolver()` with `resolvePreviewURL()`. The previous `getPreviewResolver()` method returned an object with a `resolve()` method that returned a URL string.

`resolvePreviewURL()` simplifies this by directly returning the URL string. It also automatically reads the `token` and `documentId` URL parameters.

```diff
- const url = new URL(window.location.href)
- const previewURL = await client
-   .getPreviewResolver(
-     url.searchParams.get('token'),
-     url.searchParams.get('documentId')
-   )
-   .resolve(linkResolver, '/')
+ const previewURL = await client.resolvePreviewURL({
+   linkResolver,
+   defaultURL: '/',
+ })
```

If `resolvePreviewURL()` is used in an Express server-like environment, call `enableAutoPreviewsFromReq()` before calling `resolvePreviewURL()`. This will enable the client to automatically read the `token` and `documentId` URL parameters.

```tsx
client.enableAutoPreviewsFromReq(req);
const previewURL = await client.resolvePreviewURL({
  linkResolver,
  defaultURL: "/",
});
```

If `resolvePreviewURL()` is used in a server environment without Express-like requests, provide the preview token and page ID manually using the `previewToken` and `documentID` parameters.

```tsx
const previewURL = await client.resolvePreviewURL({
  linkResolver,
  defaultURL: "/",
  previewToken: "example-preview-token",
  documentID: "example-document-id",
});
```

## Remove Experiment-related code

Prismic's Experiment feature is deprecated. As such, all Experiment-related APIs have been removed from the client. This includes the `Experiments` and `experimentCookie` exports.

## Update TypeScript types

`@prismicio/client` v6 uses TypeScript types from `@prismicio/types`. While `@prismcio/client` v5 did not publicly export TypeScript types, its internal types were usable by importing directly from the package's files.

TypeScript is now a first-class citizen in `@prismicio/client`, but most types should be imported from `@prismicio/types` instead. Note that this package must be installed separately.

```bash
npm install --save-dev @prismicio/types
```

A page can be typed like this using `@prismicio/types` rather than an internal `@prismicio/client` type:

```diff
- import { Document } from "@prismicio/client/document";
+ import { PrismicDocument } from "@prismicio/types";

- const document: Document = {
+ const document: PrismicDocument = {
    id: 'abc123',
    // The rest of the page...
  }
```

# New features

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

The following steps are optional but recommended.

## More query methods

Additional helpful query methods have been added that make querying content easier. This means you can spend less time figuring out query predicates.

The following new query methods are included:

* `getByType()`: Query pages of a given type.
* `getByTag()`: Query pages with a given tag.
* `getByEveryTag()`: Query pages that have all tags from a given list of tags.
* `getBySomeTags()`: Query pages that have at least one tag from a given list of tags.

See the [`@prismicio/client` Technical Reference](https://prismic.io/docs/technical-reference/prismicio-client.md) for a list of all query methods.

## Query all pages with recursive query methods

By default, query methods return paginated responses with up to 100 pages. There are many cases where you need all pages for a query that might exceed the 100 page limit.

New `getAll*` methods are included for most query methods that automatically fetch each page of a query. The following example shows how you can query for all pages of a given type.

```tsx
// If you have 300 Blog Post pages, this method will
// make multiple queries to fetch all Blog Posts.
const pages = await client.getAllByType("blog_post");
```

See the [`@prismicio/client` Technical Reference](https://prismic.io/docs/technical-reference/prismicio-client.md) for a list of all query methods.

## Declaratively query content from Releases

Querying content from a Release in `@prismicio/client` v5 is a manual process. It requires fetching a Release's ref and setting it as a query option. `@prismicio/client` v6 allows you to query content from a Release whether you have its ID or only its label.

```tsx
// If you have a Release's label
client.queryContentFromReleaseByLabel("My Release");

// Content is queried from "My Release"
const aboutPage = await client.getByUID("page", "about");
```

See the [`@prismicio/client` Technical Reference](https://prismic.io/docs/technical-reference/prismicio-client.md) for more details on the `queryContentFrom*` methods.

## TypeScript

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