This section contains guides for migrating from Vendure v3 to v4. Follow the steps below in order. Each step ends with how to check it is done before you move on.
| Change | Affects | Guide |
|---|---|---|
| Roles are granted per Channel through role assignments. Customers no longer hold a Customer role. | Database, plugins, Admin API clients, multi-channel storefronts | Role assignments |
| TypeORM v1 is the default dependency. TypeORM 0.3 is still supported. | Plugins with custom entities, queries or migrations | TypeORM v1 |
Upgrade to the latest v3 release first, following Updating Vendure, and run any migrations it needs.
Done when: your project runs on the latest v3 release.
After you go live on v4, restoring this backup is the only way back to v3.
Done when: you have a backup you have tested restoring.
Set every @vendure/* package in your package.json to the same v4 version, including @vendure/cli and @vendure/dashboard, then install:
Done when: the install succeeds and every @vendure/* package has the same v4 version.
Do this before the database migration: generating the migration loads your Vendure config and plugins, so they must compile against v4.
// TODO(vendure-v4): comment the codemods leave.Done when: rg "TODO\(vendure-v4\)" finds nothing, and npx tsc --noEmit passes.
Run the read-only previews against your production data. See Previewing the data migrations.
Done when: you have read each preview report and acted on any section marked "action needed".
Generate and run the v4 migration. It copies the role grants and keeps the v3 tables, then drops them: in the same migration if you stop v3 first, or in a later one for a rolling deployment. See Database migration.
Done when: the migration has run, each data-migration helper logged its result, and Vendure v4 starts. For a rolling deployment, also once the migration that drops the v3 tables has run.
See Storefront migration.
Done when: your storefront works against v4 on every Channel your Customers use.
Architecture reviews, custom plugin work, migrations, ongoing support. Get a hand from the team that builds Vendure.
Talk to the team