Developers / @prismicio/client v7 Migration Guide

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

package.json
Copy
{
  "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.

package.json
Copy
  {
    "dependencies": {


    }
  }

Update your installed packages with npm.

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

Copy

 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.

Copy

 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.

Copy

 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.

Copy

 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.

Copy

 prismic.getRepositoryEndpoint();




 prismic.filter;


 client.get();

// For `.get` and any other query methods

 client.get({ filters: ... });

// For `.get` and any other query methods


 client.get({ orderings: [{ field: "my.product.price", direction: "desc" }] };


 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.

Copy

 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.

Copy

 prismic.ContentRelationshipField;


 prismic.FilledContentRelationshipField;

New features

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

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

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

Copy

 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.

Copy

 prismic.asHTML(field, { linkResolver })


 prismic.asHTML(field, { 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.

Copy

 prismic.asText(field, { separator })
Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.