Skip to content

Releases: medusajs/medusa

v2.0.4

12 Nov 09:25
Compare
Choose a tag to compare

Highlights

Improved pluralization of MedusaService types

Warning

Breaking change: If you have created data models using the uncountable nouns and special rules below, you might be affected.

We've updated the type helper used to generate types for the methods of the MedusaService. It now has two conditional checks when converting a singular value to a plural value at the types level.

  • First, it checks for uncountable nouns in a dictionary.
  • Second, it looks for special rules for certain words like tooth, man, etc.

You can find the reference of uncountable nouns and special rules here.

Bugs

  • breaking: pluralize type helper to account for uncountable nouns and special rules by @thetutlage in #10011
  • fix(types): Add AdminBatchUpdateProductVariant type by @kasperkristensen in #10009
  • fix(medusa, types): filter product by external_id by @fPolic in #10010
  • fix(dashboard): handle deleted products/variants in the order domain by @fPolic in #9841
  • fix(dashboard): Load product variant edit page and fix product detail query key by @kasperkristensen in #10029

Documentation

Chores

Other Changes

Full Changelog: v2.0.3...v2.0.4

v2.0.3

11 Nov 10:21
5c22c57
Compare
Choose a tag to compare

Highlights

Replaced email with sub for Google entity ID

The Google authentication provider incorrectly used the email as the entity_id, which is an issue in case a Google account has multiple emails attached to it. This release fixes that and switches the usage to the sub field as a globally unique identifier.

If you have been using the Google authentication provider, the easiest way to migrate existing data is to hot patch @medusajs/auth-google using https://www.npmjs.com/package/patch-package so that when validating the callback, both the email and sub fields are used to retrieve the user, but only the sub is written.

See this PR for more.

Patched security issue

This release contains an important security fix for the email-password authentication provider. Please update your project as soon as possible.

The security issue was found in the password reset flow when using the email-password authentication provider. By obtaining a password reset token, it was possible to update the provider_metadata of other users’ provider identities by including a specific payload in the password reset request. To minimize risk to affected users, we will not disclose the structure of the payload.

Bugs

Documentation

Chores

Other Changes

New Contributors

Full Changelog: v2.0.2...v2.0.3

v2.0.2

06 Nov 20:57
Compare
Choose a tag to compare

This version fixes a range of bugs reported in the 2.0.0 release.

Highlights

Fixed mismatch with tax rate rule override

We identified a mismatch between how tax rate rule overrides were referenced in the dashboard and in the tax engine. When created through the dashboard, the overrides were created with an attribute key in plural form, but our tax engine expects them to be in the singular form.

For example, if you defined a tax rate rule override for a Product Collection, the dashboard would pass product_collections upon creating the override while the tax engine would look for product_collection.

Additionally, we fixed an issue with missing product type IDs on cart and order line items, which would mean tax calculations were not performed for product types.

These bugs were fixed in #9796 and #9951

Required actions

  • Re-create your tax rate rule overrides
  • Run migrations
npx medusa db:migrate

Features

Bugs

  • fix(dashboard): Allow float values for product prices by @kasperkristensen in #9859
  • fix(core-flows, dashboard): adjust stock levels when doing partial fulfilments by @fPolic in #9736
  • fix(dashboard): tax override reference by @fPolic in #9796
  • fix: consider --host flag and HOST env variable by @thetutlage in #9912
  • fix: disable admin when running integration tests by @thetutlage in #9915
  • fix(dashboard): truncate price cell titles by @fPolic in #9715
  • fix(utils): Mikro orm repository update many to many should detach all items by default by @adrien2p in #9917
  • fix(workflows-sdk): Paralellize steps rollback issue with config by @adrien2p in #9921
  • fix(dashboard): Allow using enter key to create newline in Textarea by @kasperkristensen in #9913
  • fix(types): Prev limit wrong values by @adrien2p in #9935
  • fix(utils/dml): set-relationship graphql generator from DML wrong managed belongsTo by @adrien2p in #9932
  • fix(telemetry): Pointing and resolving packages wrongly by @adrien2p in #9939
  • fix: Support relative path in SDK by @sradevski in #9942
  • fix(medusa): POST carts/[id]/complete missing early return by @SGFGOV in #9914
  • fix: Default to a relative path for the admin backend URL by @sradevski in #9947
  • fix: log cause property from the error by @thetutlage in #9944
  • fix(core-flows,medusa): Include region_id in shipping option retrieval by @olivermrbl in #9929
  • fix: do not set default host to localhost by @thetutlage in #9957
  • fix(types): add display_id to OrderDTO by @fPolic in #9953

Documentation

Chores

New Contributors

Full Changelog: v2.0.1...v2.0.2

v2.0.1

25 Oct 15:24
Compare
Choose a tag to compare

This version fixes a range of bugs reported in the 2.0.0 release.

Features

  • feat(core-flows, dashboard, js-sdk): customer batch endpoint for managing customer groups by @fPolic in #9761
  • feat(dashboard, medusa, types): orders list on customer details page by @fPolic in #9790
  • feat: Allow customer metadata update by @docloulou in #9780

Bugs

Documentation

Important

The documentation for Medusa v1 has moved from https://docs.medusajs.com to https://docs.medusajs.com/v1.

Chores

New Contributors

Full Changelog: v2.0.0...v2.0.1

Medusa 2.0 Release Candidate #8

22 Oct 16:16
af3c6b0
Compare
Choose a tag to compare

Get started with a new project

To get started using the RC, run the following command:

npx create-medusa-app@rc

This command will create a new Medusa project with our redesigned admin and a 2.0-compatible Next.js storefront. The Medusa application and the Next.js storefront are separate projects in separate folders.

Update existing project

Ensure your Medusa dependencies in package.json are using the rc tag:

{
  "dependencies": {
    "@medusajs/admin-sdk": "rc",
    "@medusajs/framework": "rc",
    "@medusajs/medusa": "rc",
    "@medusajs/medusa-cli": "rc",
    ...
  }
}

To ensure an upgrade to a new version is completed correctly, run the following sequence of commands:

rm -rf node_modules
rm yarn.lock // or package-lock.json

yarn // If you are using yarn berry, you need to create the lock-file first

Features

Bugs

Documentation

Chores

Full Changelog: v2.0.0-rc.7...v2.0.0-rc.8

v2.0.0

23 Oct 07:04
Compare
Choose a tag to compare

Medusa v.2.0.0

We’re excited to announce the release of Medusa 2.0 to the world today. This major version has been over 16 months in the making, with more than 3500 pull requests merged, and represents an incredible engineering feat by our team.

Medusa 2.0 is a complete rewrite of our architecture and feature set with breaking changes to many areas of Medusa 1.0. While we recognize this may be disruptive for our users, we deemed these changes necessary to establish the proper foundation for our vision of the future of building applications with Medusa.

Since this is a complete rewrite and we have yet to finalize an upgrade guide, there is no point in covering all the breaking changes in this announcement. You can expect this to be covered in the upgrade guide, which is published within the next two months. This post focuses on what’s new in Medusa 2.0. We will briefly cover the new architecture and commerce features, but otherwise, leave it to the documentation to educate about all the new concepts. Our documentation has also been rewritten and will, aside from tutorials, guides, and references, offer an in-depth learning path, equipping you with the knowledge needed to build bespoke commerce applications with Medusa.

Package restructuring

First, let’s understand the packages you need to build applications with Medusa 2.0. These haven’t changed much from 1.0, aside from some restructuring for a more logical separation of concerns.

There are three core packages in Medusa 2.0, and these are installed in new projects by default:

  • @medusajs/medusa
  • @medusajs/framework
  • @medusajs/admin-sdk

@medusajs/medusa

If you have been testing previews of Medusa 2.0, you know that we’ve gone through a few iterations of package management to figure out the most appropriate bundling of our commerce features. Eventually, we decided to stick with what we had in Medusa 1.0, a single package containing all commerce modules and the Rest API. Much of this code ships as separate npm packages (more about this in the section covering our modular architecture). However, they are all dependencies of @medusajs/medusa, which makes for a seamless upgrade path whenever new versions of underlying packages are published.

@medusajs/framework

We are excited to introduce a new package dedicated to our framework for customization. This package holds all the tooling needed to extend existing and/or introduce new functionality in Medusa projects. This includes API Routes, Workflows SDK, Modules SDK, Subscribers, Scheduled Jobs, Loaders, DML, and more. We will cover this in more depth in a later section.

@medusajs/admin-sdk

We have restructured our admin packages as part of the dashboard redesign. The commerce dashboard ships as @medusajs/dashboard and is a dependency of the core package @medusajs/medusa. The tooling to extend the dashboard, including UI Widgets and Routes, is now bundled in an Admin SDK package, @medusajs/admin-sdk.

Now that you understand the new packages, let’s move on to the most significant change in Medusa 2.0.


Architecture rewrite

The largest change from Medusa 1.0 to 2.0 is the rewrite of our core architecture. While architecture rewrites often have a tarnished reputation, we believe this decision aligns with how software engineering will evolve in the next decade. We will elaborate on this thinking in a separate blog post.

Complete isolation of domains

In Medusa 2.0, all business domains (services and data models) have been rewritten from scratch to eliminate interdependencies between them. To understand the reasoning behind this change, let’s briefly consider the previous architectural design.

In Medusa 1.0, services, e.g., Product and Cart, held most cross-domain business logic, and relationships between data models were defined via foreign keys in the database. The Cart service strictly depended on the Product service for many operations, e.g., adding a line item to the cart, and the line item data model references product variants via foreign keys. This pattern was applied to all domains in Medusa 1.0, and made it near-impossible to partially adopt our feature offering—it was all or nothing—a dealbreaker for some of our users, especially in the enterprise segment.

These interdependencies between domains significantly constrained the level of extensibility we could offer in the service layer. The only way to “extend” services was to override entire methods, which led to nasty upgrade paths whenever we upgraded those service methods with additional logic.

Medusa 2.0 eliminates all interdependencies between domains. Services are now pure in the sense that they only manage resources within their domain. All cross-domain functionality has been moved to extensible workflows, which will be covered in a later section. We’ve also eliminated all database-level dependencies, removing foreign keys between data models in different modules.

Architecture of Medusa 2.0

Medusa Architecture

Benefits of module isolation

We’ve already touched on some key benefits of module isolation. Over the past three years, we’ve seen a growing demand for incremental adoption, especially from large businesses. These businesses often have a sizeable existing tech stack with various integrations and custom applications. For them, a full migration can take years and cost millions. They need a platform that allows them to migrate their tech stack gradually while keeping the existing systems intact. Our new modular architecture makes that possible (and feasible).

Gradual adoption of modules

Medusa Architecture Gradual Adoption

A related benefit of module isolation is our new standalone mode. Not all companies need the full suite of features of a commerce platform. We’ve seen many requests for (and now usage of) standalone modules, which is a new “runtime” of modules in Medusa 2.0. Companies can install and use a few modules to build out their application. This is typically the preceding step to the gradual migration described above, where companies, over time, adopt more and more modules until they eventually leverage the full power of our platform.

For example, the Cart module can be used standalone to build a custom checkout flow:

import CartService from "@medusajs/cart"

const cart = await cartService.createCarts({
  email: "[email protected]",
  currency_code: "usd"
})

await cartService.addLineItem(cart.id. {
  title: "Custom item",
  unit_price: 1000,
  quantity: 1
})

In a common setup, line items in a cart are associated with products. However, that might not be the case for your use case. You may sell simpler goods that are not tied to a product variant or calculated price. All you need is plug-and-play cart management, and we offer you precisely that.

Services as a lower-level primitive

A non-obvious benefit from our architecture rewrite is that services have become a more useful lower-level primitive. As described above, we've removed all cross-domain business logic from services, limiting them to managing resources within their modules. So, when you use the Cart service to create a cart, you only create a cart. This sounds obvious, but in monolithic architectures, it’s common to carry out cross-domain operations within single service methods. For example, you might create shipping methods or populate the region as part of creating the cart. Such actions are typically achieved via dependency injection, which, in Medusa 2.0, is not available across modules.

Having more “dumb” services enables a greater level of composability. Modules can integrate more seamlessly, and how you integrate them is entirely up to you and your use case. Consider our previous example. Imagine you're not selling traditional products but rather subscriptions or licenses. Our Cart service doesn’t care. As long as you provide the required details to create line items, the Cart service and all its related functions, including total computation, will work as expected. It will also continue to work seamlessly with other modules, e.g. you can apply promotions to your license products with little to no changes needed. This is an example of the power of services as lower-level primitives and elegant abstractions.

Read more about the architectural changes in our documentation.


New and improved commerce features

As part of rewriting our commerce modules, we reevaluated each feature set to identify improvements. This led to various updates and new modules we are excited to introduce today.

Promotions engine

Our new Promotion module, @medusajs/promotion, lets you set up advanced conditional promotion logic. You can compute discounts based on coupons, cart items, customers, or custom data models. Additionally, we’ve introduced new types of promotions, such as Buy X and Get Y promotions.

Read more about the Promotions module here.

Advanced inventory management

Our new Inventory and Stock Location modules, @medusajs/inventory and @medusajs/stock-location, significantly improve inventory management in Medusa. With our Stock Location module, you can keep inventory in multiple warehouses worldwide, including physical stores, and associate those locations with shipping zones to ensure your fulfillment processes are optimized for distance to customers. With our new Inventory module, your product variants can share inventory items, enabling new use cases such as product bundl...

Read more

Medusa 2.0 Release Candidate #7

18 Oct 14:25
1e0f618
Compare
Choose a tag to compare

Get started with a new project

To get started using the RC, run the following command:

npx create-medusa-app@rc

This command will create a new Medusa project with our redesigned admin and a 2.0-compatible Next.js storefront. The Medusa application and the Next.js storefront are separate projects in separate folders.

Update existing project

Ensure your Medusa dependencies in package.json are using the rc tag:

{
  "dependencies": {
    "@medusajs/admin-sdk": "rc",
    "@medusajs/framework": "rc",
    "@medusajs/medusa": "rc",
    "@medusajs/medusa-cli": "rc",
    ...
  }
}

To ensure an upgrade to a new version is completed correctly, run the following sequence of commands:

rm -rf node_modules
rm yarn.lock // or package-lock.json

yarn // If you are using yarn berry, you need to create the lock-file first

Highlights

Package restructuring

Warning

Breaking change

This release comes with the final package restructuring, mainly dealing with consistent package names.

The following packages have been renamed:

  • @medusajs/medusa-cli -> @medusajs/cli
  • @medusajs/stock-location-next -> @medusajs/stock-location
  • @medusajs/inventory-next -> @medusajs/inventory
  • @medusajs/file-local-next -> @medusajs/file-local
  • medusa-telemetry -> @medusajs/telemetry
  • medusa-test-utils -> @medusajs/test-utils

This is a breaking change, and to upgrade, please update your dependencies as follows:

  • Replace medusa-test-utils with @medusajs/test-utils in your project
  • Replace @medusajs/medusa-cli with @medusajs/cli in your project

Standardize provider ID generation

Warning

Breaking change

We have cleaned up some inconsistencies and legacy code in the provider domain, which has led to breaking changes.

  • Module providers should no longer have a static property PROVIDER – this has been replaced with identifier
  • Module providers should have a static property identifier describing the name of the provider
  • Module providers' container registration name have changed format

Before

const key = `pp_[PROVIDER]_[id]`
  • id being the id specified in the module provider configuration in medusa-config.js
  • PROVIDER being the property described above, that has now been removed

After

const key = `pp_[identifier]_[id]`
  • id being the id specified in the module provider configuration in medusa-config.js
    • If this is not specified, we omit it from the registration key*
  • identifier being the property described above, that replaced PROVIDER

*Previously, we did not omit the id if it wasn't specified, which meant registration keys contained undefined. For example:

pp_stripe-ideal_undefined

Aside from having a new name in the dependency container, these changes will also affect the payment providers stored in the database. They are stored using the registration key described above, so consequently, they will be loaded anew the first time you boot up your application after upgrading to this version.

Let's consider an example provider configuration of Stripe with an explicit id:

{
  id: "stripe-usd",
  resolve: "@medusajs/payment-stripe",
  options: { ... }
}

If Stripe providers were enabled, they used to be stored with the following IDs in the database:

pp_stripe_stripe-usd
pp_stripe-ideal_stripe-usd
pp_stripe-bancontact_stripe-usd
...

Those IDs will now be:

pp_stripe_stripe-usd
pp_stripe-ideal_stripe-usd
pp_stripe-bancontact_stripe-usd
...

Let's consider an example provider configuration of Stripe without an explicit id:

{
  resolve: "@medusajs/payment-stripe",
  options: { ... }
}

If Stripe providers were enabled, they used to be stored with the following IDs in the database:

pp_stripe_undefined
pp_stripe-ideal_undefined
pp_stripe-bancontact_undefined
...

Those IDs will now be:

pp_stripe
pp_stripe-ideal
pp_stripe-bancontact
...

These changes will affect all created payment sessions on carts, as the provider specified upon creation no longer exists.

Form submission in Admin

Form submissions in Admin now require CMD + Enter on MacOS or CTRL + Enter on Windows. This makes for a more intentional action and prevents incorrect submissions.

Features

Bugs

Documentation

Chores

New Contributors

Full Changelog: v2.0.0-rc.6...v2.0.0-rc.7

Medusa Release Candidate #6

16 Oct 09:53
ddcb749
Compare
Choose a tag to compare

Get started with a new project

To get started using the RC, run the following command:

npx create-medusa-app@rc

This command will create a new Medusa project with our redesigned admin and a 2.0-compatible Next.js storefront. The Medusa application and the Next.js storefront are separate projects in separate folders.

Update existing project

Ensure your Medusa dependencies in package.json are using the rc tag:

{
  "dependencies": {
    "@medusajs/admin-sdk": "rc",
    "@medusajs/framework": "rc",
    "@medusajs/medusa": "rc",
    "@medusajs/medusa-cli": "rc",
    ...
  }
}

To ensure an upgrade to a new version is completed correctly, run the following sequence of commands:

rm -rf node_modules
rm yarn.lock // or package-lock.json

yarn // If you are using yarn berry, you need to create the lock-file first

Highlight

Resolved issue with module provider loading

See #9601 for more.

Bugs

Documentation

Full Changelog: v2.0.0-rc.5...v2.0.0-rc.6

Medusa Release Candidate #5

15 Oct 17:14
813efea
Compare
Choose a tag to compare

Get started with a new project

To get started using the RC, run the following command:

npx create-medusa-app@rc

This command will create a new Medusa project with our redesigned admin and a 2.0-compatible Next.js storefront. The Medusa application and the Next.js storefront are separate projects in separate folders.

Update existing project

Ensure your Medusa dependencies in package.json are using the rc tag:

{
  "dependencies": {
    "@medusajs/admin-sdk": "rc",
    "@medusajs/framework": "rc",
    "@medusajs/medusa": "rc",
    "@medusajs/medusa-cli": "rc",
    ...
  }
}

To ensure an upgrade to a new version is completed correctly, run the following sequence of commands:

rm -rf node_modules
rm yarn.lock // or package-lock.json

yarn // If you are using yarn berry, you need to create the lock-file first

Highlights

Removing ourDir from admin settings

Warning

Breaking change

The outDir has been removed in favor of internally computing output directory for the admin dashboard.

The computation follows these rules

  • If admin is not disabled and the build command is run without the --admin-only flag, the admin output directory will be .medusa/server/public/admin and it will be served from that same location from the Medusa instance.
  • If admin is not disabled and the build command is run with the --admin-only flag, then the admin output directory will be .medusa/admin. This commands should be used for deploying the admin dashboard separately from the Medusa instance.
// medusa-config.ts

{
  // ...
  admin: {
-    outDir: 'some/path'
  }
}

Features

Bugs

  • fix(create-medusa-app): use db:migrate to run migrations by @shahednasser in #9565
  • fix(core-flows, link-module): product <> inventory delete cascades by @fPolic in #9528
  • fix: remove default value for the cluster flag by @thetutlage in #9570
  • fix(dashboard): reservation inventory details by @fPolic in #9535
  • feat(core-flows, product): options checks on product create/update by @fPolic in #9171
  • fix(utils): update medusa config resolution for consistency by @adrien2p in #9591
  • fix(utils): Reversed module package missing references by @adrien2p in #9589
  • fix(admin-vite-plugin): Normalize file paths and add tests by @kasperkristensen in #9595

Chores

Full Changelog: v2.0.0-rc.4...v2.0.0-rc.5

Medusa 2.0 Release Candidate #4

14 Oct 15:17
ebb16d6
Compare
Choose a tag to compare

Get started with a new project

To get started using the RC, run the following command:

npx create-medusa-app@rc

This command will create a new Medusa project with our redesigned admin and a 2.0-compatible Next.js storefront. The Medusa application and the Next.js storefront are separate projects in separate folders.

Update existing project

Ensure your Medusa dependencies in package.json are using the rc tag:

{
  "dependencies": {
    "@medusajs/admin-sdk": "rc",
    "@medusajs/framework": "rc",
    "@medusajs/medusa": "rc",
    "@medusajs/medusa-cli": "rc",
    ...
  }
}

To ensure an upgrade to a new version is completed correctly, run the following sequence of commands:

rm -rf node_modules
rm yarn.lock // or package-lock.json

yarn // If you are using yarn berry, you need to create the lock-file first

Highlights

Removed deprecated APIs

Warning

Breaking change

We are still cleaning up in preparation for v2.0 and this release removes a range of deprecated APIs.

Here is a list of everything:

Commands

  • seed: There was no implementation for the seed command in the first place.
  • migrations [action]: Removed in favor of db:migrate, db:rollback and db:generate.
  • links [action]: Removed in favor of db:sync-links.
  • start-cluster: Removed start-cluster command in favor of the --cluster flag on the start command.

Config options

  • Remove config option databaseType as it is not used anywhere.
  • Remove config option httpCompression in favor of compression property.
  • Remove allowedFields in favor of allowed property from the MedusaRequest.
  • Remove expand property in favor of allowed property from the RequestQueryFields.
  • Remove defaultFields and defaultRelations in favor of defaults property from the RequestQueryFields.
  • Remove allowedFields and allowedRelations in favor of allowed property from the RequestQueryFields.

Events build

  • Remove eventsEnum in favor of eventName property accepted by the moduleEventBuilderFactory. Also updated all the usages to use eventName.

ModelDTO

  • Remove unused properties singular and plural from ModelDTOConfig.

Models template

  • Remove unused properties create, update, singular, and plural from ModelsConfigTemplate.

Zod validator

  • Remove unused OptionalBooleanValidator in favor of booleanString.

Features

Bugs

Documentation

Chores

  • chore(framework): update TSDocs for medusa config by @shahednasser in #9559
  • chore(product): Update the events emitted from the product module by @adrien2p in #9557

Full Changelog: v2.0.0-rc.3...v2.0.0-rc.4