@prismicio/client v7 Migration Guide

Overview

This is a guide for upgrading a project that uses @prismicio/client v6 and/or @prismicio/helpers v2 and/or @prismicio/types v0.

@prismicio/client v7 combines all the above into one package, offering a leaner API with a smaller footprint on your project. Because of that, @prismicio/helpers and @prismicio/types are now considered deprecated. The following instructions walk you through upgrading to the updated package.

Benefits of upgrading

• One single package now covers core Prismic usage (compared to 3 required before)
• Deprecated APIs from @prismicio/client v5 and v6 were removed
• Deprecated APIs from @prismicio/helpers v2 were removed
• Deprecated APIs from @prismicio/types v0 were removed
• Improved code-splitting and tree shaking

Update packages in package.json

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

{
  "dependencies": {
    "@prismicio/client": "^7.0.0"
  }
}

Remove @prismicio/helpers and @prismicio/types from your package.json if they were being used. @prismicio/client v7 includes all functionality previously provided by @prismicio/helpers and @prismicio/types.

  {
    "dependencies": {
-     "@prismicio/helpers": "^2.0.0"
-     "@prismicio/types": "^0.2.0"
    }
  }

Update your installed packages with npm.

npm install

Handling breaking changes

The following changes are required when upgrading to @prismicio/client v7.

Replace @prismicio/helpers imports with @prismicio/client

Replace imports for @prismicio/helpers with @prismicio/client. As a convention, all code examples will use import * as prismic when importing @prismicio/client, but this can be modified depending on your preferences.

- import * as prismicH from "@prismicio/helpers";
+ import * as prismic from "@prismicio/client";

If you were using the previous import * as prismicH convention with @prismicio/helpers and switched to the new one, don’t forget to update old references.

- prismicH.asDate(document.data.timestamp);
+ prismic.asDate(document.data.timestamp);

Replace @prismicio/types imports with @prismicio/client

Replace imports for @prismicio/types with @prismicio/client. As a convention, all code examples will use import * as prismic when importing @prismicio/client, but this can be modified depending on your preferences.

- import * as prismicT from "@prismicio/types";
+ import * as prismic from "@prismicio/client";

If you were using the previous import * as prismicT convention with @prismicio/types and switched to the new one, don’t forget to update old references.

- let page: prismicT.PrismicDocument;
+ let page: prismic.PrismicDocument;

Migrate from removed deprecated APIs

APIs that were deprecated in @prismicio/client v5 and v6 were removed. If you didn’t migrate from them previously, you now need to.

- prismic.getEndpoint();
+ prismic.getRepositoryEndpoint();

- prismic.predicates;
- prismic.Predicates;
- prismic.predicate;
+ prismic.filter;

- client.query();
+ client.get();

// For `.get` and any other query methods
- client.get({ predicates: ... });
+ client.get({ filters: ... });

// For `.get` and any other query methods
- client.get({ orderings: "[my.product.price desc]" });
- client.get({ orderings: { field: "my.product.price", direction: "desc" } });
+ client.get({ orderings: [{ field: "my.product.price", direction: "desc" }] };

- client.graphqlFetch();
+ client.graphQLFetch();

Similarly, APIs that were deprecated in @prismicio/helpers v2 were removed. If you didn’t migrate from them previously, you now need to.

- prismicH.Elements;
+ prismic.Element;

Finally, APIs that were deprecated in @prismicio/types v0 were also removed. If you didn’t migrate from them previously, you now need to.

- prismicT.RelationField;
+ prismic.ContentRelationshipField;

- prismicT.FilledLinkToDocumentField;
+ prismic.FilledContentRelationshipField;

New features

Previously, @prismicio/helpers v2 helper functions accepted options as positional parameters:

asSomething(field, option1, option2, ..., optionN)

To standardize and help our API grow better, we have collected those options as named parameters in an options object:

asSomething(field, options);

While the old helper functions signatures will still work with @prismicio/client v7, they are now considered deprecated and will be removed in a future major.

The following steps are optional but recommended.

Migrate asLink() calls to the new signature

If you were using asLink() with a link resolver, you can convert it to the new signature.

- prismic.asLink(field, linkResolver)
+ prismic.asLink(field, { linkResolver })

Migrate asHTML() calls to the new signature

If you were using asHTML() with a link resolver or a rich text serializer, you can convert it to the new signature.

- prismic.asHTML(field, linkResolver)
+ prismic.asHTML(field, { linkResolver })

- prismic.asHTML(field, null, serializer)
+ prismic.asHTML(field, { serializer })

- prismic.asHTML(field, linkResolver, serializer)
+ prismic.asHTML(field, { linkResolver, serializer })

Migrate asText() calls to the new signature

If you were using asText() with a custom separator, you can convert it to the new signature.

- prismic.asText(field, separator)
+ prismic.asText(field, { separator })