This guide provides guidance for updating the Vendure core framework to a newer version.
First, check the changelog for an overview of the changes and any breaking changes in the next version.
In your project's package.json file, find all the @vendure/... packages and change the version
to the latest. All the Vendure packages have the same version, and are all released together.
Then run npm install or yarn install depending on which package manager you prefer.
Vendure generally follows the SemVer convention for version numbering. This means that breaking API changes will only be introduced with changes to the major version (the first of the 3 digits in the version).
However, there are some exceptions to this rule:
Any instances of these exceptions will be clearly indicated in the Changelog. The reasoning for these exceptions is discussed in the Versioning policy RFC.
Major version upgrades (e.g. v1.x to v2.x) can include:
Every release will be accompanied by an entry in the changelog, listing the changes in that release. And breaking changes are clearly listed under a heading.
Database changes are one of the most common causes for breaking changes. In most cases, the changes are minor (such as the addition of a new column) and non-destructive (i.e. performing the migration has no risk of data loss).
However, some more fundamental changes occasionally require a careful approach to database migration in order to preserve existing data.
The key rule is never run your production instance with the synchronize option set to true. Doing so can cause inadvertent data loss in rare cases.
For any database schema changes, it is advised to:
If you are using a code-generation tool (such as graphql-code-generator) for your custom plugins or storefront, it is a good idea to re-generate after upgrading, which will catch any errors caused by changes to the GraphQL schema.
If you are using Vendure providers (services, JobQueue, EventBus etc.) in your custom plugins, you should look out for breakages caused by changes to those services. Major changes will be listed in the changelog, but occasionally internal changes may also impact your code.
The best way to check whether this is the case is to build your entire project after upgrading, to see if any new TypeScript compiler errors emerge.
Architecture reviews, custom plugin work, migrations, ongoing support. Get a hand from the team that builds Vendure.
Talk to the team