Medusa 2.0 Public Preview Release

Today, we’re excited to share a Preview Release of Medusa 2.0.

The following document covers resources, guides, and things to know about the first preview release of Medusa 2.0. It will help you get started and give you a high-level overview of your new Medusa 2.0 application and what’s still to be done.

The preview release is not ready for production and is only intended for experimentation and development of new projects.

The release candidate later this year will include more fully-fledged resources for 2.0, including an overview of breaking changes, migration guides, and much more that will ensure a smoother onboarding.

We advise against upgrading your project to 2.0 at this point, as we are still working on documentating the best possible path.

These release notes are only intended to help you start and introduce you to your new Medusa 2.0 project. For a more in-depth exploration of the major upgrade, refer to our new documentation.

We are publishing this release to solicit early user and community feedback. Please file Issues for bug reports and/or submit Discussions with input or questions.

We thank you all very much in advance.

Get started

To get started using the preview release, run the following command:

npx create-medusa-app@preview

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.

The folder structure of Medusa projects has changed:

my-project
 ├── src
 │   ├── admin
 │   ├── api
 │   ├── jobs
 │   ├── subscribers
-│   ├── services
-│   ├── models
-│   ├── migrations
-│   ├── loaders
+│   ├── modules
+│   │   └── my-module
+│   │       ├── loaders
+│   │       ├── migrations
+│   │       ├── models
+│   │       ├── index.ts
+│   │       └── service.ts
+│   ├── workflows
 └── medusa-config.ts

The modules folder replaces a lot of folders from a 1.0 project and will contain most business logic customizations in your Medusa 2.0 application. We highly encourage you to read the section of our docs covering this new concept in detail.

The workflows folder holds your custom workflows. Workflows are a fundamental concept in cross-module operations and a core element of Medusa 2.0. Read more about workflows here.

Additionally, medusa-config.js has been cleaned up and improved with a new type-safe utility function for defining the config for your Medusa project. The file can also now live as both a JS and TS file.

export default defineConfig({
  projectConfig: {
    http: {
      storeCors: "<STORE_CORS>",
      adminCors: "<ADMIN_CORS>",
      authCors: "<AUTH_CORS>"
    },
    redisUrl: "<REDIS URL>",
    databaseUrl: "<DATABASE_URL>",
  },
  admin: {
    backendUrl: "https://my-medusa-server.medusajs.app",
  },
})

You are now ready to explore all the new features in the preview release. However, we recommend reading through our documentation to fully understand what is new in 2.0 and how it differs from 1.0.

Additionally, you can find references and code snippets for our tools in our Learning Resources.

Keeping up with preview releases

We release preview versions every three hours. We recommend setting the version of your Medusa dependencies to preview, so you can regularly update without knowing specific version numbers.

All your Medusa dependencies in package.json should look something like this:

{
  "dependencies": {
    "@medusajs/medusa": "preview",
    "@medusajs/pricing": "preview",
    "@medusajs/product": "preview",
    ...
  }
}

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

What’s new?

Medusa 2.0 is a huge upgrade, in fact, the biggest upgrade since we open-sourced the project four years ago. The upgrade comes with many new features and improvements, some of which are still work-in-progress. In the following sections, we will briefly cover these features and the parts of the product still subject to change. A more detailed changelog will be released as part of the release candidate and, subsequently, the official release later this year.

Admin dashboard

Our admin dashboard has been completely overhauled, improving its overall look and feel to provide end-users with a more cohesive and consistent experience.

Additionally, we have migrated away from Webpack to Vite, which improves the developer experience with features like HMR and allows us and our users to tap into a rich and flourishing community and plugin ecosystem.

Read more about the admin dashboard and its extension capabilities here.

A few admin flows have yet to be built. This is primarily around returns, exchanges, claims, and order edits. We expect to finalize these in the coming weeks.

Modules architecture

Our modules foundation has been re-architected to entirely decouple modules from one another, enabling greater composability, a new standalone usage mode, and a more approachable incremental adoption of Medusa.

Read more about the architecture refactor in our 2.0 announcement from earlier this year.

New commerce features

We saw reworking the module's architecture as an opportunity to rethink the feature set of some of the business domains in Medusa 1.x. As a result, we are excited to introduce a range of advanced capabilities across a series of modules. Here are a few noteworthy improvements:

• Stock location: Build omnichannel experiences with new stock location features, including “Buy online, pick up in-store” options.
• Inventory: Compose multi-part variants and share inventory across products with our new inventory management features
• Authentication: Enable authentication with external providers, such as Google, with our new authentication and user management features
• Promotion: Create granular promotions with our new rules engine. Use conditions to create bundled discounts, buy-get, spend-get, temporary campaigns, and more

Many other modules have also seen improvements. Browse through all of them in our learning resources.

Data modeling language

A core feature of Medusa is the ability to extend the default commerce application with additional business logic to cater to a specific use case, natively integrate with third-party providers, replace existing domains, and more.

At the core of extensions in Medusa 2.0 are modules, and at the core of modules are data models. Data models define the concepts living within your application. In our commerce modules, you find orders, products, customers, promotions, etc. By introducing your own data models, you extend this semantic layer of your application, enabling you to build features and custom workflows by integrating existing and new concepts. Because data models are at the core of every customization, we decided to make them easier to work with.

We are excited to announce a new data modeling language in Medusa 2.0 that will improve the experience of defining and working with data in your application. You can read more about the new feature here.

Below is a simple example of what data models will look like in 2.0:

Long-running Workflows

We are excited to extend our existing workflow capabilities with Long-running Workflows for processing long-running operations in the background. Instead of synchronously receiving a workflow's result, Long-running Workflows are subscribed to for status changes and execution progress. Additionally, the Long-running Workflows comes with an API for programmatically moving from one step to the next. These features make Long-running Workflows a great fit for use cases that require a human-in-the-loop or operations with a varying long-running execution time.

For example, we use Long-running Workflows extensively to build the infrastructure provisioning of Medusa Cloud.

Alongside the Long-running Workflows, we are also introducing a new admin section for managing them. Here, you can see currently executing and completed workflows, providing full transparency into your long-running operations.

Medusa 2.0 comes with much more than what is highlighted in this post. We will cover everything in-depth in the official release notes.

These release notes are published as a GitHub Discussion as well for comments and questions on the preview release.