docs: create docs workspace (#5174)
* docs: migrate ui docs to docs universe * created yarn workspace * added eslint and tsconfig configurations * fix eslint configurations * fixed eslint configurations * shared tailwind configurations * added shared ui package * added more shared components * migrating more components * made details components shared * move InlineCode component * moved InputText * moved Loading component * Moved Modal component * moved Select components * Moved Tooltip component * moved Search components * moved ColorMode provider * Moved Notification components and providers * used icons package * use UI colors in api-reference * moved Navbar component * used Navbar and Search in UI docs * added Feedback to UI docs * general enhancements * fix color mode * added copy colors file from ui-preset * added features and enhancements to UI docs * move Sidebar component and provider * general fixes and preparations for deployment * update docusaurus version * adjusted versions * fix output directory * remove rootDirectory property * fix yarn.lock * moved code component * added vale for all docs MD and MDX * fix tests * fix vale error * fix deployment errors * change ignore commands * add output directory * fix docs test * general fixes * content fixes * fix announcement script * added changeset * fix vale checks * added nofilter option * fix vale error
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,73 @@
|
||||
---
|
||||
description: 'Actions Required for Vite Update'
|
||||
sidebar_label: '(Repository) Vite'
|
||||
slug: /upgrade-guides/admin/admin-vite
|
||||
sidebar_custom_props:
|
||||
iconName: 'computer-desktop-solid'
|
||||
---
|
||||
|
||||
# Updating Medusa Admin from Gatsby to Vite
|
||||
|
||||
Medusa Admin has been updated to Vite. Learn about breaking changes since the update.
|
||||
|
||||
:::warning
|
||||
|
||||
This guide applies if you're using an old version of the admin repository and you're adding the latest changes of the repository. However, this repository is now deprecated and it's highly recommended to switch to using an admin plugin instead. You can learn more in [the upgrade guide](./1-0-0.md)
|
||||
|
||||
:::
|
||||
|
||||
## Overview
|
||||
|
||||
Medusa Admin previously was built using Gatsby. As of a recent update, the Admin is now migrated to Vite 3.
|
||||
|
||||
This introduced breaking changes related to environment variables used and the published directory. Read below for actions required following this update.
|
||||
|
||||
---
|
||||
|
||||
## Required Node.js Version
|
||||
|
||||
<!-- vale docs.Numbers = NO -->
|
||||
|
||||
Following the change to Vite 3, the required Node.js version for the Admin has changed. [Vite 3](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) requires versions 14.8+ or 16+ of Node.js.
|
||||
|
||||
<!-- vale docs.Numbers = YES -->
|
||||
|
||||
---
|
||||
|
||||
## Changed Environment Variables
|
||||
|
||||
Previously, the Medusa Admin used the environment variables `GATSBY_MEDUSA_BACKEND_URL` or `GATSBY_STORE_URL` to store the Medusa backend’s URL.
|
||||
|
||||
After the update to Vite, the environment variable name changed to `MEDUSA_BACKEND_URL`.
|
||||
|
||||
The Medusa admin remains backward compatible, which means you can still use the same environment variables. However, it is advised to make the change to the new variable.
|
||||
|
||||
### Actions Required
|
||||
|
||||
Change your `GATSBY_MEDUSA_BACKEND_URL` or `GATSBY_STORE_URL` environment variables to be `MEDUSA_BACKEND_URL`:
|
||||
|
||||
```bash
|
||||
MEDUSA_BACKEND_URL=<YOUR_BACKEND_URL>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Changed Publish Directory
|
||||
|
||||
Previously, the build output of the Medusa Admin was placed in the `dist` directory. After this update, the build output is placed in the `public` directory.
|
||||
|
||||
For local usage and development, this shouldn’t have an effect. However, this is a breaking change if you deployed Medusa admin.
|
||||
|
||||
### Actions Required
|
||||
|
||||
If you deployed your Medusa admin, you must change the Publish directory in your hosting.
|
||||
|
||||
For Netlify, you can do that by following these steps:
|
||||
|
||||
1. On your Medusa admin dashboard, click on “Site settings”.
|
||||
2. From the sidebar, choose “Build & deploy”.
|
||||
3. Find the “Build settings” section and click on the “Edit settings” button.
|
||||
4. Change the “Publish directory” field to `public`.
|
||||
5. Click on the Save button.
|
||||
|
||||
This should trigger a new deployment of your Medusa admin. If not, you must redeploy it manually for changes to take effect.
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
description: "Migrate from the GitHub repository to the NPM package."
|
||||
sidebar_label: 'v1.0.0'
|
||||
sidebar_custom_props:
|
||||
iconName: 'computer-desktop-solid'
|
||||
---
|
||||
|
||||
# Medusa Admin: v1.0.0
|
||||
|
||||
Medusa Admin has been moved from being hosted on a GitHub repository to being published as an NPM package that can be installed in the same project as the Medusa backend. This upgrade guide will help you find the right resources to make the upgrade.
|
||||
|
||||
:::note
|
||||
|
||||
If you made customizations to the admin and you want to preserve these customization, then it's recommended not to update to use the new admin plugin. You can learn more in [this section](#preserving-customizations-in-the-admin).
|
||||
|
||||
:::
|
||||
|
||||
## Overview
|
||||
|
||||
The Admin is now composed of two packages `@medusajs/admin` and `@medusajs/admin-ui`. The `@medusajs/admin` package is the plugin that can be installed in the Medusa server project. The `@medusajs/admin-ui` package is the UI that is served by the plugin.
|
||||
|
||||
This guide will cover three cases where the move might affect your current setup:
|
||||
|
||||
- Updating your existing project to use the plugin
|
||||
- Replacing your already deployed admin with the plugin
|
||||
- Preserving customizations in the plugin
|
||||
|
||||
## Actions required
|
||||
|
||||
### Updating your existing project to use the plugin
|
||||
|
||||
As mentioned, Medusa Admin is now distributed via NPM and installed as a plugins. To replace your existing admin, you first need to install the plugin in your Medusa server project.
|
||||
|
||||
Follow the [admin quickstart guide](../../admin/quickstart.mdx) to learn how to set up the plugin with the Medusa backend.
|
||||
|
||||
### Deploy the New Admin Plugin
|
||||
|
||||
The move to an NPM package has implications for the workflow to deploy the Admin. The plugin offers to ways to deploy the admin, either by serving the Admin directly from the Medusa server, or by deploying the Admin to a separate hosting platform.
|
||||
|
||||
To host the Admin directly from your Medusa server, you can follow the [Admin Quickstart Guide](../../admin/quickstart.mdx).
|
||||
|
||||
You can learn how to deploy the Admin to a host through the [Vercel Deployment Guide](../../deployments/admin/deploying-on-vercel.mdx). The process is similar for other Git based hosting platforms.
|
||||
|
||||
### Preserving Customizations in the Admin
|
||||
|
||||
If you have made customizations to the Admin, it is recommend that you keep your current setup and wait for the next minor release of Medusa Admin, that will introduce a more seamless way to extend the UI. Migrating customizations to the new admin plugin is not supported, and will require manually patching any changes or forking the Admin plugin. The current Admin repository will still receive critical bug fixes while in maintenance, but it will not be updated with new features. If you can forego the latest features introduced in 1.8 you can continue to use the standalone admin repository for now.
|
||||
|
||||
While it's generally not recommended, if you want to maintain your customizations while upgrading to the latest version of Medusa Admin, you have two options:
|
||||
|
||||
1. Fork the @medusajs/admin plugin and @medusajs/admin-ui, and manually patch in your customizations.
|
||||
2. Use the medusa-admin eject -o <output_directory> command to eject the Admin UI from the plugin and use it as a separate project. This way, you can make your customizations and deploy them to a separate hosting platform.
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
description: "Migrate to v7.0.0 of the admin that supports Admin Extensions"
|
||||
sidebar_label: 'v7.0.0'
|
||||
sidebar_custom_props:
|
||||
iconName: 'computer-desktop-solid'
|
||||
---
|
||||
|
||||
# Medusa Admin: v7.0.0
|
||||
|
||||
Version 7.0.0 introduces Admin Extensions, which were previously available as a `beta` version. By upgrading to this version, you'll be able to create admin [widgets](../../admin/widgets.md), [UI routes](../../admin/routes.md), and [setting pages](../../admin/setting-pages.md).
|
||||
|
||||
This version also introduces a breaking change to the `path` configuration of the admin plugin.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa backend to update the admin plugin:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/admin@7.0.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Path Configuration
|
||||
|
||||
Previously, the `path` configuration of the admin plugin set in `medusa-config.js` expected the path to not include a backslash `/` at its beginning or its end.
|
||||
|
||||
Starting from v7.0.0 of `@medusajs/admin`, the `path` configuration is required to start with a `/`, but not end with one.
|
||||
|
||||
For example, if you've set the admin configuration as follows:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/admin",
|
||||
/** @type {import('@medusajs/admin').PluginOptions} */
|
||||
options: {
|
||||
path: "admin",
|
||||
// ...
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
You should change the value of `path` to `/admin`:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/admin",
|
||||
/** @type {import('@medusajs/admin').PluginOptions} */
|
||||
options: {
|
||||
path: "/admin",
|
||||
// ...
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"position": 3,
|
||||
"collapsed": true,
|
||||
"link": null,
|
||||
"label": "Medusa Admin"
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
hide_table_of_contents: true
|
||||
description: 'Upgrade guides on how to update the Medusa backend along with other Medusa components to the latest version.'
|
||||
---
|
||||
|
||||
import DocCard from '@theme/DocCard';
|
||||
import getFirstCategoryItem from '@site/src/utils/get-first-category-item';
|
||||
|
||||
# Upgrade Guides
|
||||
|
||||
Find in this page the upgrade guides that require necessary steps when upgrading to a new version.
|
||||
|
||||
## Backend
|
||||
|
||||
<DocCard
|
||||
item={getFirstCategoryItem('Backend')}
|
||||
/>
|
||||
|
||||
## Admin Dashboard
|
||||
|
||||
<DocCard
|
||||
item={getFirstCategoryItem('Admin Dashboard')}
|
||||
/>
|
||||
|
||||
## Medusa React
|
||||
|
||||
<DocCard
|
||||
item={getFirstCategoryItem('Medusa React')}
|
||||
/>
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.10.0'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.10.0
|
||||
|
||||
Version 1.10.0 of Medusa introduces performance improvement related to Typeorm and the removal of the `retrieveSubscribers` previously added to the event bus service.
|
||||
|
||||
## Overview
|
||||
|
||||
### Typeorm Performance Improvement
|
||||
|
||||
To improve performance of Cart and Product retrieval, our team has changed the `relationLoadStrategy` in Typeorm from join to query. This means relations are loaded using separate database queries rather than many joins in a single large query. This change also significantly reduces memory usage, as it will produce a much smaller result set to store in memory.
|
||||
|
||||
Unfortunately, Typeorm's query-strategy does not work well in concert with transactions, which is extensively used across our codebase. The separate queries to fetch relations on entities will run outside of an initiated transaction, because it uses a different query runner. This leads to incorrect results in cases where you request entities previously created in an ongoing transaction. Those changes will not have persisted to the database at the time of querying, and will therefore be "invisible" to other query runners.
|
||||
|
||||
Instead of compromising on the performance of our API, our team decided to fix the issue in Typeorm, which can be found in [this PR](https://github.com/typeorm/typeorm/pull/9990) on Typeorm's repository. It is still yet to be merged, so, for now, our team has published a forked version of Typeorm that includes the fix. This is the breaking change of this release.
|
||||
|
||||
### retrieveSubscribers Removal
|
||||
|
||||
The `retrieveSubscribers` was introduced in a previous version to ensure that events are triggered only if a subscriber was listening to that event. However, the approach implemented caused unanticipated issues with the triggering of events.
|
||||
|
||||
So, this method has been removed from the event bus service. If you've implemented this event in your custom event bus service, this should cause no issues, but your `retrieveSubscribers` method will not be used anymore.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa Backend to update the core:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa@1.10.0
|
||||
```
|
||||
|
||||
If you are using our local event bus, run the following command to update the event system:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/event-bus-local@1.9.1
|
||||
```
|
||||
|
||||
It's also recommended to update any other Medusa plugins or packages you have installed.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Change Typeorm Package
|
||||
|
||||
To make sure your project works as expected, you'll need to use our forked Typeorm version in your project until Typeorm merges our PR and publishes a new version.
|
||||
|
||||
In your `package.json`, replace the Typeorm version with the following:
|
||||
|
||||
```json
|
||||
"typeorm": "npm:@medusajs/typeorm@next"
|
||||
```
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.10.1'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.10.1
|
||||
|
||||
Version 1.10.1 of Medusa introduces database schema changes that require you run the migrations command.
|
||||
|
||||
## Overview
|
||||
|
||||
This release contains a migration that extends the `ReservationItem` and `InventoryItem` entities with additional properties.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa Backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa@1.10.1
|
||||
```
|
||||
|
||||
To avoid unexpected issues with dependencies, it is also recommended to update all other Medusa plugins or packages you have installed.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Run Migrations
|
||||
|
||||
After updating your Medusa server and before running it, run the following command to run the latest migrations:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.11.0'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.11.0
|
||||
|
||||
Version 1.11.0 of Medusa reverts changes related to Typeorm and the underlying mechanism for querying relations on entities.
|
||||
|
||||
## Overview
|
||||
|
||||
### Typeorm query strategy
|
||||
|
||||
In v1.10.0 of the Medusa core package, the mechanism for loading relations in Typeorm was changed from `join` to `query`, which meant that instead of firing one large query with joins, separate queries for each requested relation are fired. This was added to improve performance and eliminate an issue with heavy memory usage. Read more about it in [the release notes of 1.10.0](https://github.com/medusajs/medusa/releases/tag/v1.10.0).
|
||||
|
||||
Unfortunately, the `query` strategy came with unexpected issues related to database connection management. It turned out, the `query` strategy obtains a new database connection for each separate query – instead of reusing the already established connection – leading to a drained connection pool and eventually unresponsive applications.
|
||||
|
||||
To eliminate these issues, it has been decided to ditch the query strategy. Instead, custom query strategies are introduced for Carts, Products, and Orders to maintain highly performant APIs while mitigating risk of unexpected memory and/or database connection problems.
|
||||
|
||||
Additionally, the core no longer relies on our Typeorm fork, because the fix related to the query strategy is now irrelevant. You should update your project to use the official Typeorm package
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa Backend to update the core:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa@1.11.0
|
||||
```
|
||||
|
||||
It's also recommended to update any other Medusa plugins or packages you have installed.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Change Typeorm Package
|
||||
|
||||
To make sure your project works as expected, you should move back to the official Typeorm package.
|
||||
|
||||
In your `package.json`, you should use the following Typeorm version:
|
||||
|
||||
```json
|
||||
"typeorm": "^0.3.16"
|
||||
```
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.12.0'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.12.0
|
||||
|
||||
Version 1.12.0 of Medusa comes with database changes that require you run the migrations command and a minor breaking change to the `PriceSelectionStrategy`.
|
||||
|
||||
## Overview
|
||||
|
||||
This release contains migrations that introduce a range of new database indexes that will improve performance of your setup.
|
||||
|
||||
Additionally, it brings minor breaking changes to the `PriceSelectionStrategy`. The method `calculateVariantPrice` now supports bulk calculating variant prices.
|
||||
|
||||
Specifically, the following signature has changed:
|
||||
|
||||
```ts
|
||||
// Before
|
||||
class MyStrategy extends
|
||||
AbstractPriceSelectionStrategy {
|
||||
// ...
|
||||
calculateVariantPrice(
|
||||
variantId: string,
|
||||
context: PriceSelectionContext
|
||||
): Promise<PriceSelectionResult> {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
// Now
|
||||
class MyStrategy extends
|
||||
AbstractPriceSelectionStrategy {
|
||||
// ...
|
||||
calculateVariantPrice(data: {
|
||||
variantId: string;
|
||||
quantity?: number;
|
||||
}[],
|
||||
context: PriceSelectionContext
|
||||
): Promise<Map<string, PriceSelectionResult>> {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Finally, a clean up of our `@medusajs/utils` have also led to potential breaking changes. The clean-up resulted in the following:
|
||||
|
||||
- The packages `class-validator` and `class-transformer` have been removed from `@medusajs/utils`.
|
||||
|
||||
- The `TransactionBaseService` has been removed from `@medusajs/utils`. This class should be imported from `@medusajs/medusa`.
|
||||
|
||||
- The utilities `build-query`, `db-aware-column`, `base-entity`, and `soft-deletable-entity` have been removed from `@medusajs/medusa`. These should be imported from @medusajs/medusa.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa Backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa@1.12.0
|
||||
```
|
||||
|
||||
To avoid unexpected issues with dependencies, it is also recommended to update all other Medusa plugins or packages you have installed.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Run Migrations
|
||||
|
||||
After updating your Medusa server and before running it, run the following command to run the latest migrations:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
|
||||
### Change PriceSelectionStrategy method
|
||||
|
||||
If you've created a custom price selection strategy, or have using the `PriceSelectionStrategy`'s `calculateVariantPrice` method in your custom code, make sure to update its definition or usage based on the new signature:
|
||||
|
||||
```ts
|
||||
class MyStrategy extends
|
||||
AbstractPriceSelectionStrategy {
|
||||
// ...
|
||||
calculateVariantPrice(data: {
|
||||
variantId: string;
|
||||
quantity?: number;
|
||||
}[],
|
||||
context: PriceSelectionContext
|
||||
): Promise<Map<string, PriceSelectionResult>> {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can learn more in the [Price Selection Strategy](../../modules/price-lists/price-selection-strategy.md#calculatevariantprice-method) documentation.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.13.0'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.13.0
|
||||
|
||||
Version 1.13.0 of Medusa introduces database schema changes that require you run the migrations command.
|
||||
|
||||
## Overview
|
||||
|
||||
This release contains a migration that changes the relationship between Shipping Profile and Product to Many-to-Many.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa Backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa@1.13.0
|
||||
```
|
||||
|
||||
To avoid unexpected issues with dependencies, it is also recommended to update all other Medusa plugins or packages you have installed.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Run Migrations
|
||||
|
||||
After updating your Medusa server and before running it, run the following command to run the latest migrations:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.15.0'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.15.0
|
||||
|
||||
Version 1.15.0 of Medusa comes with improvements to the Import and Export features, leading to several breaking changes.
|
||||
|
||||
## Overview
|
||||
|
||||
This release contains breaking changes in the Import/Export and File Service domains.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa Backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa@1.15.0
|
||||
```
|
||||
|
||||
To avoid unexpected issues with dependencies, it is also recommended to update all other Medusa plugins or packages you have installed. For this release in particular, you must update file service plugins to ensure they work as expected.
|
||||
|
||||
---
|
||||
|
||||
## File Services
|
||||
|
||||
The file service streaming API to upload to public/private buckets has been updated to be consistent across all plugins.
|
||||
|
||||
### File Service Interface
|
||||
|
||||
The following types specific to file services have moved from `@medusajs/medusa` to `@medusajs/types`:
|
||||
|
||||
```ts
|
||||
export type FileServiceUploadResult = {
|
||||
url: string
|
||||
key: string
|
||||
}
|
||||
|
||||
export type FileServiceGetUploadStreamResult = {
|
||||
writeStream: stream.PassThrough
|
||||
promise: Promise<any>
|
||||
url: string
|
||||
fileKey: string
|
||||
[x: string]: unknown
|
||||
}
|
||||
|
||||
export type GetUploadedFileType = {
|
||||
fileKey: string
|
||||
isPrivate?: boolean
|
||||
[x: string]: unknown
|
||||
}
|
||||
|
||||
export type DeleteFileType = {
|
||||
fileKey: string
|
||||
[x: string]: unknown
|
||||
}
|
||||
|
||||
export type UploadStreamDescriptorType = {
|
||||
name: string
|
||||
ext?: string
|
||||
isPrivate?: boolean
|
||||
[x: string]: unknown
|
||||
}
|
||||
```
|
||||
|
||||
Also, previously, the `getUploadStreamDescriptor` method of file services didn't require a specific option to specify whether a file should be uploaded to a private or public bucket. For example, if you used the MinIO plugin, you passed the `usePrivateBucket` option, whereas with the S3 and Spaces plugins, you passed the `acl` option.
|
||||
|
||||
With this update, the option is now specified within the signature of the method in the `IFileService` interface that all file services extend. The `getUploadStreamDescriptor` now accepts as part of its option the `isPrivate` option:
|
||||
|
||||
<!-- eslint-skip -->
|
||||
|
||||
```ts
|
||||
getUploadStreamDescriptor({
|
||||
// ... other options
|
||||
isPrivate // boolean value
|
||||
}): Promise<FileServiceGetUploadStreamResult>
|
||||
```
|
||||
|
||||
### File Service Plugins
|
||||
|
||||
Following the updates in the previous section, all the official plugins (MinIO, S3, and Spaces) now implement the new `getUploadStreamDescriptor` signature. The `isPrivate` option is optional and defaults to `true`.
|
||||
|
||||
For example, here's a comparison of how you previously specified whether a file should be uploaded to a private or public bucket, and how you must do it now:
|
||||
|
||||
<!-- eslint-skip -->
|
||||
|
||||
```ts
|
||||
// before
|
||||
// MinIO
|
||||
fileService.getUploadStreamDescriptor({..., usePrivateBucket: false})
|
||||
// S3 & Spaces
|
||||
fileService.getUploadStreamDescriptor({..., acl: "public-read"})
|
||||
|
||||
// after
|
||||
fileService.getUploadStreamDescriptor({..., isPrivate: true}) // private bucket (default)
|
||||
fileService.getUploadStreamDescriptor({..., isPrivate: false}) // public bucket
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Import/Export
|
||||
|
||||
The following method signatures in the Price List and Product import batch job strategies have been updated:
|
||||
|
||||
<!-- eslint-skip -->
|
||||
|
||||
```ts
|
||||
// before
|
||||
downloadImportOpsFile(batchJobId: string, op: OperationType)
|
||||
deleteOpsFiles(batchJobId: string)
|
||||
|
||||
// after
|
||||
downloadImportOpsFile(batchJob: BatchJob, op: OperationType)
|
||||
deleteOpsFiles(batchJob: BatchJob)
|
||||
```
|
||||
|
||||
Mainly, both the `downloadImportOpsFile` and `deleteOpsFiles` methods now requires the batch job instance as the first parameter. Previously, they required only the ID of the batch job.
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.16.0'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.16.0
|
||||
|
||||
Version 1.16.0 of Medusa introduces breaking changes to database schemas.
|
||||
|
||||
## Overview
|
||||
|
||||
This release contains a migration that changes the relationship between the `MoneyAmount` and `ProductVariant` entities from Many-to-One to Many-to-Many.
|
||||
|
||||
Additionally, the following foreign key constraints have been dropped:
|
||||
|
||||
:::note
|
||||
|
||||
These changes are only relevant if you are using the feature flag `isolate_product_domain`. Please be careful about enabling this flag, as it will introduce experimental and work-in-progress changes.
|
||||
|
||||
:::
|
||||
|
||||
- `ProductTaxRate` to `Product`
|
||||
- `ProductTypeTaxRate` to `ProductType`
|
||||
- `ClaimItem` to `ProductVariant`
|
||||
- `DiscountConditionProduct` to `Product`
|
||||
- `DiscountConditionProductCollection` to `ProductCollection`
|
||||
- `DiscountConditionProductTag` to `ProductTag`
|
||||
- `DiscountConditionProductType` to `ProductType`
|
||||
- `DiscountRule` to `Product`
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in your project:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa@1.16.0
|
||||
```
|
||||
|
||||
To avoid unexpected issues with dependencies, it is also recommended to update all other Medusa plugins or packages you have installed.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Run Migrations
|
||||
|
||||
After updating your Medusa server and before running it, run the following command to run the latest migrations:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.3.0'
|
||||
---
|
||||
|
||||
# v1.3.0
|
||||
|
||||
Version 1.3.0 of Medusa introduces new features including the addition of Line Item Adjustments and a more advanced Promotions API, as well as a change in loading environment variables into your Medusa backend. The changes do not affect the public APIs and require only running necessary data migrations.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Both the actions required for this update need you to set the following environment variables:
|
||||
|
||||
```bash
|
||||
TYPEORM_CONNECTION=postgres
|
||||
TYPEORM_URL=<DATABASE_URL>
|
||||
TYPEORM_LOGGING=true
|
||||
TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js
|
||||
TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
|
||||
```
|
||||
|
||||
These environment variables are used in the data migration scripts in this upgrade. Make sure to replace `<DATABASE_URL>` with your PostgreSQL database URL.
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
In previous versions of Medusa, The backend automatically loads all environment variables in the `.env` file at the root of the Medusa backend.
|
||||
|
||||
This new update removes loading it automatically and gives developers the freedom in how to load their environment variables. All environment variables will be loaded by default from the system’s environment variables.
|
||||
|
||||
### Actions Required
|
||||
|
||||
If you use a `.env` file to load environment variables on your backend, you need to load the variables manually in `medusa-config.js`.
|
||||
|
||||
You can add the following code snippet at the top of the file which uses the [dotenv](https://www.npmjs.com/package/dotenv) package to load the environment variables based on the current Node environment:
|
||||
|
||||
```jsx
|
||||
const dotenv = require("dotenv")
|
||||
|
||||
let ENV_FILE_NAME = ""
|
||||
switch (process.env.NODE_ENV) {
|
||||
case "production":
|
||||
ENV_FILE_NAME = ".env.production"
|
||||
break
|
||||
case "staging":
|
||||
ENV_FILE_NAME = ".env.staging"
|
||||
break
|
||||
case "test":
|
||||
ENV_FILE_NAME = ".env.test"
|
||||
break
|
||||
case "development":
|
||||
default:
|
||||
ENV_FILE_NAME = ".env"
|
||||
break
|
||||
}
|
||||
|
||||
try {
|
||||
dotenv.config({ path: process.cwd() + "/" + ENV_FILE_NAME })
|
||||
} catch (e) {
|
||||
// handle error
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Line Item Adjustments
|
||||
|
||||
This new version of Medusa allows store operators to adjust line items in an order or a swap which provides more customization capabilities.
|
||||
|
||||
It introduces a new entity `LineItemAdjustment` which gives more flexibility to adjust the pricing of line items in a cart, order, or swap. A discount can be added, removed, or modified and the price will reflect on the total calculation of the cart, order, or swap.
|
||||
|
||||
This also introduces an optimization to the calculation of totals, as it is no longer necessary to calculate the discounts every time the totals are retrieved.
|
||||
|
||||
### Actions Required
|
||||
|
||||
This new version adds a new data migration script that will go through your list of existing orders and add line item adjustments for each of the line items in the order.
|
||||
|
||||
For that reason, it’s essential to run the data migration script after upgrading your backend and before starting your Medusa backend:
|
||||
|
||||
```bash
|
||||
node ./node_modules/@medusajs/medusa/dist/scripts/line-item-adjustment-migration.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Discount Conditions
|
||||
|
||||
This new version of Medusa holds advanced promotions functionalities to provide store operators with even more customization capabilities when creating discounts. You can now add even more conditions to your discounts to make them specific for a set of products, collections, customer groups, and more.
|
||||
|
||||
This change required creating a new entity `DiscountCondition` which belongs to `DiscountRule` and includes a few relationships with other entities to make the aforementioned feature possible.
|
||||
|
||||
### Actions Required
|
||||
|
||||
To ensure your old discount rules play well with the new Promotions API and schema, this version includes a migration script that will go through your existing discount rules, create discount conditions for these rules, and move the former direct relationship between discount rules and products to become between discount conditions and products.
|
||||
|
||||
For that reason, it’s essential to run the data migration script after upgrading your backend and before starting your Medusa backend:
|
||||
|
||||
```bash
|
||||
node ./node_modules/@medusajs/medusa/dist/scripts/discount-rule-migration.js
|
||||
```
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.3.0'
|
||||
---
|
||||
|
||||
# v1.3.6
|
||||
|
||||
Following the addition of feature flags in version v1.3.3 and the addition of the Sales Channels API in v1.3.5, v1.3.6 introduces a data migration script that moves all products into the Default Sales Channel.
|
||||
|
||||
:::note
|
||||
|
||||
In version 1.3.6, Sales Channels are available but guarded by [feature flags](../../development/feature-flags/toggle.md). If you don’t have Sales Channels enabled, you don’t need to follow the steps detailed in this migration script.
|
||||
|
||||
:::
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before performing the actions mentioned in this guide, you must set the following environment variables:
|
||||
|
||||
```bash
|
||||
TYPEORM_CONNECTION=postgres
|
||||
TYPEORM_URL=<DATABASE_URL>
|
||||
TYPEORM_LOGGING=true
|
||||
TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js
|
||||
TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
|
||||
```
|
||||
|
||||
These environment variables are used in the data migration scripts in this upgrade. Make sure to replace `<DATABASE_URL>` with your PostgreSQL database URL.
|
||||
|
||||
---
|
||||
|
||||
## Sales Channels
|
||||
|
||||
Sales Channels were introduced in v1.3.5 guarded by a [feature flag](../../development/feature-flags/toggle.md). By enabling Sales Channels, developers and users can associate products and other entities with a specific Sales Channel.
|
||||
|
||||
However, if you upgraded Medusa to v1.3.5 and enabled Sales Channels, you must add every product to at least one Sales Channel manually. Otherwise, products can’t be added to carts in different Sales Channels.
|
||||
|
||||
v1.3.6 introduces a data migration script that automates this process for you by moving all your products into a default Sales Channel. This ensures that you can use the Sales Channels feature without it affecting the user experience in your store.
|
||||
|
||||
### Actions Required
|
||||
|
||||
If you’ve enabled Sales Channels, it’s essential to run the data migration script after upgrading your backend and before starting your Medusa backend:
|
||||
|
||||
```bash
|
||||
node ./node_modules/@medusajs/medusa/dist/scripts/sales-channels-migration.js
|
||||
```
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.3.8'
|
||||
---
|
||||
|
||||
# v1.3.8
|
||||
|
||||
Updating your Medusa backend to version `1.3.8` may cause issues when using NPM. Please refer to this guide for more details on how to resolve it.
|
||||
|
||||
## Update Using Yarn
|
||||
|
||||
It's highly recommended to use [yarn](https://yarnpkg.com/) when working with Medusa. Updating with yarn should resolve any issues you might run into during the update.
|
||||
|
||||
---
|
||||
|
||||
## Resolving Update Issues with NPM
|
||||
|
||||
### Update All Medusa Dependencies
|
||||
|
||||
If you face any errors during your update to version `1.3.8`, make sure to update all Medusa dependencies you’re using on your backend. This includes `medusa-interfaces`, `@medusajs/medusa-cli`, or any of Medusa’s official plugins.
|
||||
|
||||
You can update to the latest version of these using the `@latest` version tag. For example:
|
||||
|
||||
```bash
|
||||
npm install medusa-interfaces@latest
|
||||
```
|
||||
|
||||
### Use Legacy Peer Dependencies Option
|
||||
|
||||
:::caution
|
||||
|
||||
This solution can be used as a workaround and should be used with caution to avoid any issues while using Medusa.
|
||||
|
||||
:::
|
||||
|
||||
If all fails, you can use the `--legacy-peer-deps` option while updating Medusa:
|
||||
|
||||
```bash
|
||||
npm install @medusajs/medusa@latest --legacy-peer-deps
|
||||
```
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.6.1'
|
||||
---
|
||||
|
||||
# v1.6.1
|
||||
|
||||
Updating your Medusa backend to version `1.6.1` requires running migrations on your backend.
|
||||
|
||||
## Overview
|
||||
|
||||
As the new version `1.6.1` make changes to the database schema, it is required to run new migrations before you start your backend.
|
||||
|
||||
Without running the migrations, you might have trouble accessing and using the Medusa admin.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
After updating your backend, run migrations with the following command:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.7.0'
|
||||
---
|
||||
|
||||
# v1.7.0
|
||||
|
||||
Version `1.7.0` of Medusa introduces a breaking change in the [CustomerService](../../references/services/classes/CustomerService.md).
|
||||
|
||||
## Overview
|
||||
|
||||
In this new version, the method [`retrieveByEmail` in the Customer Service](../../references/services/classes/CustomerService.md#retrievebyemail) has been deprecated in favor of other methods. Read the actions required below to learn which methods to use instead.
|
||||
|
||||
In addition, after introducing the Claim Order feature, this version of Medusa introduces changes in the database that allows two customers having the same email based on the value of the `has_account` field. This change requires running migrations after the update.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Run Migrations
|
||||
|
||||
Run the following command to run migrations:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
|
||||
### Change Used Methods
|
||||
|
||||
Instead of using `customerService.retrieveByEmail`, you should now use the methods `customerService.retrieveRegisteredByEmail` or `customerService.retrieveUnregisteredByEmail`.
|
||||
|
||||
The `customerService.retrieveRegisteredByEmail` method allows you to retrieve a registered customer by email:
|
||||
|
||||
```ts
|
||||
customerService.retrieveRegisteredByEmail("example@gmail.com")
|
||||
```
|
||||
|
||||
On the other hand, the `retrieveUnregisteredByEmail` method allows to retrieve guest customers by email:
|
||||
|
||||
```jsx
|
||||
customerService.retrieveUnregisteredByEmail("example@gmail.com")
|
||||
```
|
||||
|
||||
To retrieve a customer by email regardless of whether they are registered or not, you can use the `customerService.list` method instead:
|
||||
|
||||
```ts
|
||||
customerService.list({
|
||||
email: "example@gmail.com",
|
||||
})
|
||||
```
|
||||
@@ -0,0 +1,137 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.7.1'
|
||||
---
|
||||
|
||||
# v1.7.1
|
||||
|
||||
Version `1.7.1` of Medusa introduces the `JobSchedulerService` which changes how scheduled/cron jobs are created.
|
||||
|
||||
## Overview
|
||||
|
||||
Version `1.7.1` of Medusa introduces a new service `JobSchedulerService` that handles all logic and functionality related to created scheduled (previously named cron jobs).
|
||||
|
||||
With this introduction, the previous use of `EventBus` to create a cron job has been deprecated of using the `JobSchedulerService`.
|
||||
|
||||
In addition, this version features some fixes to gift cards that requires running migrations, and changes to how payment providers are implemented.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Run Migrations
|
||||
|
||||
In the directory of your Medusa backend, run the following command after updating the backend:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
|
||||
### Run Migration Script
|
||||
|
||||
Following the fix gift cards calculation, you also need to run a migration script after updating the backend.
|
||||
|
||||
Start by adding the following environment variables in `.env`:
|
||||
|
||||
```bash
|
||||
TYPEORM_CONNECTION=postgres
|
||||
TYPEORM_URL=<DATABASE_URL>
|
||||
TYPEORM_USERNAME=<DATABASE_USERNAME>
|
||||
TYPEORM_PASSWORD=<DATABASE_PASSWORD>
|
||||
TYPEORM_DATABASE=<DATABASE_DATABASE>
|
||||
TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js
|
||||
TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
|
||||
```
|
||||
|
||||
Make sure to replace `<DATABASE_URL>`, `<DATABASE_USERNAME>`, `<DATABASE_PASSWORD>`, and `<DATABASE_DATABASE>` with your database connection details.
|
||||
|
||||
Then, run the following command in the root directory of your Medusa backend:
|
||||
|
||||
```bash
|
||||
node ./node_modules/@medusajs/medusa/dist/scripts/gift-card-tax-rate-migration.js
|
||||
```
|
||||
|
||||
### Change to JobSchedulerService
|
||||
|
||||
In your loader file that creates a cron job, replace the use of `eventBus` to `jobSchedulerService`:
|
||||
|
||||
```ts
|
||||
const myJob = async (container, options) => {
|
||||
const jobSchedulerService = container.resolve(
|
||||
"jobSchedulerService"
|
||||
)
|
||||
jobSchedulerService.create(
|
||||
"my-job",
|
||||
{},
|
||||
"0 0 * * *",
|
||||
async () => {
|
||||
// ...
|
||||
}
|
||||
)
|
||||
}
|
||||
|
||||
export default myJob
|
||||
```
|
||||
|
||||
You can learn more in the [How to Create a Scheduled Job](../../development/scheduled-jobs/create.md) documentation.
|
||||
|
||||
### Change to Payment Provider
|
||||
|
||||
This version of Medusa introduces a change in how payment providers are implemented. Mainly, the signature of the `createPayment` and `updatePayment` methods have changed, and the old signature is now deprecated.
|
||||
|
||||
Although this change is currently backwards compatible, it is recommended to change the signature of these methods to the following:
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
import { Cart, PaymentSessionData, PaymentContext, PaymentSessionResponse } from "@medusajs/medusa"
|
||||
// ...
|
||||
|
||||
class MyPaymentService extends AbstractPaymentService<TransactionBaseService> {
|
||||
// ...
|
||||
async createPayment(
|
||||
context: Cart & PaymentContext
|
||||
): Promise<PaymentSessionResponse> {
|
||||
// ...
|
||||
}
|
||||
|
||||
async updatePayment(
|
||||
paymentSessionData: PaymentSessionData,
|
||||
context: Cart & PaymentContext
|
||||
): Promise<PaymentSessionResponse> {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Where `context` in both `createPayment` and `updatePayment` is made up of the following properties:
|
||||
|
||||
```ts
|
||||
type PaymentContext = {
|
||||
cart: {
|
||||
context: Record<string, unknown>
|
||||
id: string
|
||||
email: string
|
||||
shipping_address: Address | null
|
||||
shipping_methods: ShippingMethod[]
|
||||
}
|
||||
currency_code: string
|
||||
amount: number
|
||||
resource_id?: string
|
||||
customer?: Customer
|
||||
}
|
||||
```
|
||||
|
||||
So, you can pass the previous `cart` parameter inside the new `context` parameter.
|
||||
|
||||
Furthermore, these methods are now expected to return `PaymentSessionResponse`. It is made up of the following properties:
|
||||
|
||||
```ts
|
||||
type PaymentSessionResponse = {
|
||||
update_requests: {
|
||||
customer_metadata: Record<string, unknown>
|
||||
}
|
||||
session_data: Record<string, unknown>
|
||||
}
|
||||
```
|
||||
|
||||
Where `session_data` would include the previously returned data from these methods. The property `update_requests` allows you to pass data from the payment provider plugin to the core to update internal resources. Currently, it can only be used to update the `metadata` field of the customer entity.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.7.12'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.7.12
|
||||
|
||||
Version 1.7.12 of Medusa introduces some database schema changes which require running the migrations command.
|
||||
|
||||
## Overview
|
||||
|
||||
This release contains a migration to ensure that the `product_variant_inventory` table is in its correct state. This is due to a mistake in a previous version where a column name was renamed in an already released migration. This could lead to errors if the migration was applied before the renaming of the column.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa Backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa@latest @medusajs/medusa-cli@latest medusa-interfaces@latest
|
||||
```
|
||||
|
||||
It's also recommended to update any other Medusa plugins or packages you have installed.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Run Migrations
|
||||
|
||||
After updating your Medusa server and before running it, run the following command to run the latest migrations:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.7.3'
|
||||
---
|
||||
|
||||
# v1.7.3
|
||||
|
||||
Version 1.7.3 of Medusa changes the feature flag value for Sales Channels and Publishable API Keys.
|
||||
|
||||
## Overview
|
||||
|
||||
Sales Channels and Publishable API Keys were introduced in previous versions of Medusa, but guarded by [feature flags](../../development/feature-flags/toggle.md) This meant that developers had to manually enable them to use them.
|
||||
|
||||
Version 1.7.3 of Medusa keeps the feature flags for these two features, but they’re now enabled by default. This requires running the necessary migrations to ensure your backend works as expected.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Run Migrations
|
||||
|
||||
After updating your Medusa backend and before running it, run the following command to run the latest migration:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
|
||||
### Run Migration Script for Sales Channels
|
||||
|
||||
With the introduction of Sales Channels, products are now associated with them. To avoid inconsistencies with how products are linked to Sales Channels, it’s strongly recommended to run a migration script right after running the Medusa backend the first time.
|
||||
|
||||
Start by adding the following environment variables:
|
||||
|
||||
```bash
|
||||
TYPEORM_CONNECTION=postgres
|
||||
TYPEORM_URL=<DATABASE_URL>
|
||||
TYPEORM_LOGGING=true
|
||||
TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js
|
||||
TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
|
||||
```
|
||||
|
||||
Make sure to replace `<DATABASE_URL>` with the connection URL of your database.
|
||||
|
||||
Then, run the following command in the root of your Medusa backend:
|
||||
|
||||
```bash
|
||||
node ./node_modules/@medusajs/medusa/dist/scripts/sales-channels-migration.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Disabling Feature Flags
|
||||
|
||||
Although this version enables Sales Channels and Publishable API Keys by default, you can still turn them off using feature flags. Learn more in [this documentation](../../development/feature-flags/toggle.md#disable-feature-flags)
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.7.6'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.7.6
|
||||
|
||||
Version 1.7.6 of Medusa introduces some database schema changes which require running the migrations command.
|
||||
|
||||
## Overview
|
||||
|
||||
The latest versions of Medusa introduce the first implementations of Product Categories. The API layer of this feature is guarded by a [feature flag](../../development/feature-flags/toggle.md), but the changes to the database schema are not.
|
||||
|
||||
This release introduces another migration for Product Categories. So, it is required to run migrations to ensure your backend works as expected.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa Backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa@latest @medusajs/medusa-cli@latest medusa-interfaces@latest
|
||||
```
|
||||
|
||||
It's also recommended to update any other Medusa plugins or packages you have installed.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Run Migrations
|
||||
|
||||
After updating your Medusa backend and before running it, run the following command to run the latest migrations:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
description: 'Actions required for v1.8'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.8
|
||||
|
||||
Medusa v1.8 comes with many new features while introducing architectural changes contributing toward making Medusa more modular and portable to new, modern environments.
|
||||
|
||||
This has led to breaking changes and this document will guide you through the required actions.
|
||||
|
||||
Please note that by upgrading to v1.8 of Medusa, you must also upgrade your admin to become a plugin as explained in the [admin upgrade guide](../admin/1-0-0.md). If you've made customizations to your admin, please refer to [this section of the admin upgrade guide](../admin/1-0-0.md#preserving-customizations-in-the-admin) before considering updating to v1.8 of Medusa.
|
||||
|
||||
## Required Actions
|
||||
|
||||
:::note
|
||||
|
||||
It's recommended to use yarn when updating the following dependency to avoid any unexpected errors.
|
||||
|
||||
:::
|
||||
|
||||
### Step 1: Update Typeorm
|
||||
|
||||
To get started using Medusa v1.8, you first need to upgrade your version of Typeorm:
|
||||
|
||||
```bash
|
||||
yarn add typeorm@0.3.11
|
||||
```
|
||||
|
||||
The dependency on Typeorm has been upgraded from 0.2.31 to 0.3.11, which comes with significant breaking changes. Follow Typeorm's upgrade guide to refactor your custom code.
|
||||
|
||||
### Step 2: Update Core Package
|
||||
|
||||
Install version 1.8 of the core:
|
||||
|
||||
```bash
|
||||
yarn add @medusajs/medusa@1.8.0
|
||||
```
|
||||
|
||||
### Step 3: Install Required Modules
|
||||
|
||||
The core engine doesn't come with a Redis caching mechanism and Redis events system any longer. Instead the core relies on the Module API for those two sub-systems.
|
||||
|
||||
As a result, you are required to install and use those modules to ensure your application works as expected.
|
||||
|
||||
Install the new Redis cache module with the following command:
|
||||
|
||||
```bash
|
||||
yarn add @medusajs/cache-redis@1.8.0
|
||||
```
|
||||
|
||||
Install the new Redis event bus module with the following command:
|
||||
|
||||
```bash
|
||||
yarn add @medusajs/event-bus-redis@1.8.0
|
||||
```
|
||||
|
||||
Then, add both modules to the exported configuration in `medusa-config.js`.
|
||||
|
||||
```js title=medusa-config.js
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: {
|
||||
eventBus: {
|
||||
resolve: "@medusajs/event-bus-redis",
|
||||
options: {
|
||||
redisUrl: "your-redis-url",
|
||||
},
|
||||
},
|
||||
cacheService: {
|
||||
resolve: "@medusajs/cache-redis",
|
||||
options: {
|
||||
redisUrl: "your-redis-url",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Make sure to replace `your-redis-url` with the connection URL to your Redis installation.
|
||||
|
||||
### Step 4: Run Migrations
|
||||
|
||||
Finally, you should run migrations to ensure your database is up to date with our schema changes:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.8.1'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.8.1
|
||||
|
||||
Version 1.8.1 of Medusa introduces database schema changes which require running the migrations command.
|
||||
|
||||
## Overview
|
||||
|
||||
This release introduces a new column named `description` on Product Categories. It is required to run migrations to ensure your backend works as expected.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa Backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa@1.8.1
|
||||
```
|
||||
|
||||
It's also recommended to update any other Medusa plugins or packages you have installed.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Run Migrations
|
||||
|
||||
After updating your Medusa backend and before running it, run the following command to run the latest migrations:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.9.0'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.9.0
|
||||
|
||||
Version 1.9.0 of Medusa introduces database schema changes which require running the migrations command. Additionally, it ships with a minor breaking change to the events system.
|
||||
|
||||
## Overview
|
||||
|
||||
This release introduces a new column `metadata` on Sales Channels. It is required to run migrations to ensure your backend works as expected.
|
||||
|
||||
This release also comes with a breaking change to the events system. It is required to update your event bus packages to ensure events are handled correctly.
|
||||
|
||||
In the core `EventBusService`, a check has been introduced to only insert staged jobs (in other words, fire events), if there are subscribers to it.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa Backend to update the core:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa@1.9.0
|
||||
```
|
||||
|
||||
Then, update your event bus dependency. If you are using an official package, run one of these two commands based on the package you have installed:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/event-bus-redis@1.8.3
|
||||
# or
|
||||
npm install @medusajs/event-bus-local@1.8.3
|
||||
```
|
||||
|
||||
It's also recommended to update any other Medusa plugins or packages you have installed.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Run Migrations
|
||||
|
||||
After updating your Medusa backend and before running it, run the following command to run the latest migrations:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"position": 1,
|
||||
"collapsed": false,
|
||||
"link": null,
|
||||
"label": "Backend"
|
||||
}
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
description: 'Actions Required for v4.0.2'
|
||||
sidebar_custom_props:
|
||||
iconName: 'react'
|
||||
---
|
||||
|
||||
# Medusa React: v4.0.2
|
||||
|
||||
Version 4.0.2 of Medusa React introduces a new update in its dependencies which can lead to breaking changes.
|
||||
|
||||
## Overview
|
||||
|
||||
Medusa React previously required installing React Query v3 as a peer dependency. This version changes the peer dependency requirement to [Tanstack Query](https://tanstack.com/query/latest/docs/react/overview) - the updated version of React Query.
|
||||
|
||||
This requires additional actions related to installing the new dependency and changing imports.
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Update Medusa Dependencies
|
||||
|
||||
To update to the latest version of Medusa React, run the following command in your custom storefront or admin to update both Medusa React and the core package:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-react@latest @medusajs/medusa@latest
|
||||
```
|
||||
|
||||
### Uninstall React Query v3
|
||||
|
||||
As React Query v3 is not required as a peer dependency anymore, uninstall it from your custom storefront or admin:
|
||||
|
||||
```bash npm2yarn
|
||||
npm uninstall react-query
|
||||
```
|
||||
|
||||
### Install Tanstack Query
|
||||
|
||||
Run the following command to install Tanstack Query:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @tanstack/react-query
|
||||
```
|
||||
|
||||
### Update Imports
|
||||
|
||||
Across your custom storefront or admin project, change all imports from `react-query` to `@tanstack/react-query`.
|
||||
|
||||
For example, update the import for `QueryClient` where you use it with Medusa Provider:
|
||||
|
||||
```ts
|
||||
import { QueryClient } from "@tanstack/react-query"
|
||||
|
||||
// this remains the same
|
||||
const queryClient = new QueryClient()
|
||||
```
|
||||
|
||||
### Fix No QueryClient set Errors
|
||||
|
||||
If you're using a Next.js storefront, you might face the following error after this update when you run your storefront:
|
||||
|
||||
```bash
|
||||
No QueryClient set
|
||||
```
|
||||
|
||||
This is due to an issue related to Tanstack Query shipping `esm` modules in its latest versions and how Next.js uses Webpack.
|
||||
|
||||
Although in future versions of `medusa-react` this issue will be fixed, you can add the following into `next.config.js` to fix this error:
|
||||
|
||||
```js
|
||||
const path = require("path")
|
||||
|
||||
/** @type {import('next').NextConfig} */
|
||||
const nextConfig = {
|
||||
// ... other configs
|
||||
webpack: (config, options) => {
|
||||
if (options.isServer) {
|
||||
config.externals = [
|
||||
"@tanstack/react-query",
|
||||
...config.externals,
|
||||
]
|
||||
}
|
||||
const reactQuery = path.resolve(
|
||||
require.resolve("@tanstack/react-query")
|
||||
)
|
||||
config.resolve.alias["@tanstack/react-query"] = reactQuery
|
||||
return config
|
||||
},
|
||||
}
|
||||
|
||||
module.exports = nextConfig
|
||||
```
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"position": 2,
|
||||
"collapsed": true,
|
||||
"link": null,
|
||||
"label": "Medusa React"
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"position": 4,
|
||||
"link": null,
|
||||
"label": "Modules"
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.2.0'
|
||||
sidebar_custom_props:
|
||||
iconName: 'server-stack-solid'
|
||||
---
|
||||
|
||||
# v1.2.0
|
||||
|
||||
Version 1.2.0 of the Product Module introduces minor breaking changes to the `ProductService`.
|
||||
|
||||
## Overview
|
||||
|
||||
This release contains breaking change to the methods `list` and `listAndCount` in the `ProductService` of the Product Module.
|
||||
|
||||
Specifically, the category filter that the service methods accept has changed from `category_ids` to `category_id`.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in your project:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/product@1.2.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Actions Required
|
||||
|
||||
### Change usage of Product Module
|
||||
|
||||
If you've applied the category filter to the `list` or `listAndCount` methods of the Product Module, you will need to change it as follows:
|
||||
|
||||
```ts
|
||||
// Before
|
||||
ProductService.list({
|
||||
category_ids: ["pcat_123", "pcat_456"],
|
||||
})
|
||||
ProductService.listAndCount({
|
||||
category_ids: ["pcat_123", "pcat_456"],
|
||||
})
|
||||
|
||||
// Now
|
||||
ProductService.list({
|
||||
category_id: ["pcat_123", "pcat_456"],
|
||||
})
|
||||
ProductService.listAndCount({
|
||||
category_id: ["pcat_123", "pcat_456"],
|
||||
})
|
||||
```
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"label": "Product Module",
|
||||
"customProps": {
|
||||
"reverse": true
|
||||
},
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"position": 3,
|
||||
"link": null,
|
||||
"label": "Plugins"
|
||||
}
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.0.0'
|
||||
sidebar_label: 'v1.0.0'
|
||||
---
|
||||
|
||||
# Algolia: v1.0.0
|
||||
|
||||
Version 1.0.0 of the official Algolia plugin comes with breaking changes to the plugin options that are passed to the Algolia service through `medusa-config.js`.
|
||||
|
||||
## Overview
|
||||
|
||||
In the new version of the Algolia search plugin, two new plugin configuration properties are introduced; `transformer` and `primaryKey`. As a result, the way indexes in Algolia are configured has changed. Additionally, the existing settings have been changed to follow a camel casing - though with backward compatibility.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa Backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-plugin-algolia@1.0.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Actions required
|
||||
|
||||
As you can see from the new object shape, the property `indexSettings` has been introduced to hold the settings specific to Algolia’s index options. This has been done to make space for the `transformer`.
|
||||
|
||||
Previously, you might have configured the Algolia plugin as seen below:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
application_id: "someId",
|
||||
admin_api_key: "someApiKey",
|
||||
settings: {
|
||||
// example
|
||||
products: {
|
||||
searchableAttributes: ["title", "description"],
|
||||
attributesToRetrieve: ["title", "description"],
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
In the above example, an index `products` has been configured with two options `searchableAttributes` and `attributesToRetrieve`. Updating to v1.0.0 requires you to nest these within the `indexSettings`. Additionally, the admin API key and application ID options should now be in camel case, as the snake-cased version will be deprecated.
|
||||
|
||||
The updated plugin options would look like so:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
applicationId: "someId",
|
||||
adminApiKey: "someApiKey",
|
||||
settings: {
|
||||
products: {
|
||||
indexSettings: {
|
||||
searchableAttributes: ["title", "description"],
|
||||
attributesToRetrieve: ["title", "description"],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
You can learn more about the new plugin options in the [Algolia plugin documentation](../../../plugins/search/algolia.md).
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"label": "Algolia",
|
||||
"customProps": {
|
||||
"reverse": true
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
description: 'Actions Required for v.1.0.0'
|
||||
sidebar_label: 'v1.0.0'
|
||||
---
|
||||
|
||||
# Meilisearch: v1.0.0
|
||||
|
||||
Version 1.0.0 of the official Meilisearch plugin comes with breaking changes to the plugin options that are passed to the Meilisearch service through `medusa-config.js`.
|
||||
|
||||
## Overview
|
||||
|
||||
In the new version of the Meilisearch search plugin, two new plugin configuration properties are introduced; `transformer` and `primaryKey`. As a result, the way indexes in Meilisearch are configured has changed.
|
||||
|
||||
---
|
||||
|
||||
## How to Update
|
||||
|
||||
Run the following command in the root directory of your Medusa Backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-plugin-meilisearch@1.0.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Actions required
|
||||
|
||||
As you can see from the new object shape, the property `indexSettings` has been introduced to hold the settings specific to Meilisearch’s index options. This has been done to make space for new settings like `transformer` and `primaryKey`.
|
||||
|
||||
Previously, your Meilisearch plugin configurations were something like this:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
config: {
|
||||
host: "https://search-api-example.com",
|
||||
apiKey: "some_key",
|
||||
},
|
||||
settings: {
|
||||
products: {
|
||||
searchableAttributes: ["title", "description"],
|
||||
attributesToRetrieve: ["title", "description"],
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
In the above example, an index `products` has been configured with the two options `searchableAttributes` and `attributesToRetrieve`. Updating to 1.0.0 requires you to nest these options within the `indexSettings`.
|
||||
|
||||
The updated plugin options would look like so:
|
||||
|
||||
```js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
config: {
|
||||
host: "https://search-api-example.com",
|
||||
apiKey: "some_key",
|
||||
},
|
||||
settings: {
|
||||
products: {
|
||||
indexSettings: {
|
||||
searchableAttributes: ["title", "description"],
|
||||
attributesToRetrieve: ["title", "description"],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
You can learn more about the new settings in the [MeiliSearch plugin documentation](../../../plugins/search/meilisearch.md)
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"label": "MeiliSearch",
|
||||
"customProps": {
|
||||
"reverse": true
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user