Updating Medusa

In this chapter, you'll learn about updating your Medusa application and packages.

Medusa Versioning#

When Medusa puts out a new release, all packages are updated to the same version. This ensures that all packages are compatible with each other, and makes it easier for you to switch between versions.

Medusa updates the version number major.minor.patch according to the following rules:

• patch: A patch release includes bug fixes and minor improvements. It doesn't include breaking changes. For example, if the current version is 2.0.0, the next patch release will be 2.0.1.
• minor: A minor release includes new features, fixes, improvements, and breaking changes. For example, if the current version is 2.0.0, the next minor release will be 2.1.0.
• major: A major release includes significant changes to the entire codebase and architecture. For those, the update process will be more elaborate. For example, if the current version is 2.0.0, the next major release would be 3.0.0.

Check Installed Version#

To check the currently installed version of Medusa in your project, run the following command in your Medusa application:

Terminal
❯npx medusa -v

This will show you the installed version of Medusa and the Medusa CLI tool, which should be the same.

Check Latest Version#

The documentation shows the current version at the top right of the navigation bar. When a new version is released, you'll find a blue dot on the version number. Clicking it will take you to the release notes on GitHub.

You can also star the Medusa repository on GitHub to receive updates about new releases on your GitHub dashboard. Our team also shares updates on new releases on our social media channels.

Update Medusa Application#

Before updating a Medusa application, make sure to check the release notes for any breaking changes that require actions from your side.

Then, to update your Medusa application, bump the version of all @medusajs/* dependencies in your package.json. Then, re-install dependencies:

npm
yarn
pnpm

This will update all Medusa packages to the latest version.

Running Migrations#

Releases may include changes to the database, such as new tables, updates to existing tables, updates after adding links, or data migration scripts.

So, after updating Medusa, run the following command to migrate the latest changes to your database:

Terminal
❯npx medusa db:migrate

This will run all pending migrations, sync links, and run data migration scripts.

Reverting an Update#

Before reverting an update, if you already ran the migrations, you have to first identify the modules who had migrations. Then, before reverting, run the db:rollback command for each of those modules.

For example, if the version you updated to had migrations for the Cart and Product Modules, run the following command:

Terminal
❯npx medusa db:rollback cart product

Then, revert the update by changing the version of all @medusajs/* dependencies in your package.json to the previous version and re-installing dependencies:

npm
yarn
pnpm

Finally, run the migrations to sync link changes:

Terminal
❯npx medusa db:migrate

Understanding Codebase Changes#

In the Medusa codebase, our team uses the following TSDoc tags to indicate changes made in the latest version for a specific piece of code:

• @deprecated: Indicates that a piece of code is deprecated and will be removed in a future version. The tag's message will include details on what to use instead. However, our updates are always backward-compatible, allowing you to update your codebase at your own pace.
• @version: Indicates the version when a piece of code was available from. A piece of code that has this tag will only be available starting from the specified version.

Update Plugin Project#

If you have a Medusa plugin project, you only need to update its @medusajs/* dependencies in the package.json file to the latest version. Then, re-install dependencies:

npm
yarn
pnpm