121 lines
5.1 KiB
Plaintext
121 lines
5.1 KiB
Plaintext
import { config } from "../../../config/index"
|
|
|
|
export const metadata = {
|
|
title: `${pageNumber} Updating Medusa`,
|
|
}
|
|
|
|
# {metadata.title}
|
|
|
|
In this chapter, you'll learn about updating your Medusa application and packages.
|
|
|
|
export const releaseNoteText = `Read the [Release Notes](${config.version.releaseUrl}).`
|
|
|
|
<Note type="soon" title="Tip">
|
|
|
|
Medusa's current version is v{config.version.number}. {releaseNoteText}
|
|
|
|
</Note>
|
|
|
|
## 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.
|
|
|
|
<Note>
|
|
|
|
This doesn't apply to the design-system packages, including `@medusajs/ui`, `@medusajs/ui-presets`, and `@medusajs/ui-icons`. These packages are versioned independently. However, you don't need to install and manage them separately in your Medusa application, as they are included in the `@medusajs/admin-sdk`. If you're using them in a standalone project, such as a storefront or custom admin dashboard, refer to [this section in the Medusa UI documentation](!ui!/installation/standalone-project#updating-ui-packages) for update instructions.
|
|
|
|
</Note>
|
|
|
|
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:
|
|
|
|
```bash
|
|
npx medusa -v
|
|
```
|
|
|
|
This will show you the installed version of Medusa and the [Medusa CLI tool](!resources!/medusa-cli), 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](https://github.com/medusajs/medusa/releases).
|
|
|
|
You can also star the [Medusa repository on GitHub](https://github.com/medusajs/medusa) 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](https://github.com/medusajs/medusa/releases) 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:
|
|
|
|
```bash npm2yarn
|
|
npm install
|
|
```
|
|
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash npm2yarn
|
|
npm install
|
|
```
|
|
|
|
Finally, run the migrations to sync link changes:
|
|
|
|
```bash
|
|
npx medusa db:migrate
|
|
```
|
|
|
|
---
|
|
|
|
## Understanding Codebase Changes
|
|
|
|
In the Medusa codebase, our team uses the following [TSDoc](https://tsdoc.org/) 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:
|
|
|
|
```bash npm2yarn
|
|
npm install
|
|
```
|