@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 @prismcio/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 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 install
The 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 })
Was this article helpful?
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.