@prismicio/client v7 Migration Guide
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.
- One single package now covers core Prismic usage (compared to 3 required before)
- Deprecated APIs from
@prismicio/clientv5 and v6 were removed - Deprecated APIs from
@prismicio/helpersv2 were removed - Deprecated APIs from
@prismicio/typesv0 were removed - Improved code-splitting and tree shaking
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": {
}
}Update your installed packages with npm.
npm installThe following changes are required when upgrading to @prismicio/client v7.
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 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.
prismic.asDate(document.data.timestamp);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 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: prismic.PrismicDocument;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.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.
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.
prismic.ContentRelationshipField;
prismic.FilledContentRelationshipField;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.
If you were using asLink() with a link resolver, you can convert it to the new signature.
prismic.asLink(field, { linkResolver })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, { serializer })
prismic.asHTML(field, { linkResolver, serializer })If you were using asText() with a custom separator, you can convert it to the new signature.
prismic.asText(field, { separator })Can't find what you're looking for?
Need technical Support? Spot an error in the documentation? Get in touch with us on our Community Forum.