v1.8.0-rc.0

Preface

You will find that version 1.8 introduces breaking changes, which might cause you to wonder; why is this not considered a major version?

As we've mentioned in the past, we are currently not following strict semantic versioning. Instead, we use minor versions for breaking changes and patches for all else - and we will continue to do so for the time being.

We apologize in advance for the inconvenience this may cause to your setup.

---

Release Candidate for 1.8

We’re excited to share the Release Candidate (RC) of Medusa 1.8. By definition, release candidates are unstable, so we recommend not using this version in production. We are publishing this pre-release to gather feedback from users and the general developer community and to identify bugs and minor improvements to the stuff we've built.

Our 1.8 release comes with many new features while introducing architectural changes contributing toward making Medusa more modular and portable to new, modern environments. Now is your chance to give these changes a spin.

We welcome feedback, questions, and bug reports. Please use Issues for bug reports and the dedicated GitHub Discussion (for this RC) for all else.

In the 1.8 release notes, we will cover all new improvements and features in depth. In the following RC notes, we only briefly outline the high-level changes that are directly affecting your setup.

Get Started

If you are new to Medusa, please follow our Quickstart guide to set up your project before proceeding with the following steps.

To get started using the pre-release of Medusa 1.8, the first thing you need to do is upgrade Typeorm to their latest version:

yarn add typeorm@latest

Then install the RC version of our core:

yarn add @medusajs/medusa@rc

Aside from upgrading the core, you will need to perform a couple of additional steps, as we’ve changed the core package to rely on our Modules API for cache and events rather than having that functionality baked in. This opens up our cache and events systems to other technologies - more on that in the 1.8 release notes.

Install the new Redis cache module with the following command:

yarn add @medusajs/cache-redis@rc

Install the new Redis event bus module with the following command:

yarn add @medusajs/event-bus-redis@rc

Both modules need configuration. In medusa-config.js add the following to your project configuration:

module.exports = {
  projectConfig: {
    database_url: DATABASE_URL,
    ...
  },
  plugins,
  // Add modules configuration
  modules: {
    eventBus: {
      resolve: "@medusajs/event-bus-redis",
      options: {
        redisUrl: "your-redis-url"
      }
    },
    cacheService: {
      resolve: "@medusajs/cache-redis",
      options: {
        redisUrl: "your-redis-url"
      }
    }
  }
};

Finally, run migrations:

medusa migrations run

You are now set up to start using the RC.

Here’s a quick overview of what’s new in the RC:

• Multi-warehouse
• Nested Categories
• Medusa Admin plugin
• Payment Processors
• Event Bus module
• Cache module
• OAS Tooling and client types packages
• Types and Utils packages
• Search plugins update
• Performance improvements
• Typeorm upgrade

This is not an exhaustive overview. Refer to the concrete changes at the bottom of the notes for a more detailed overview.

Features and Improvements

You'll find the following feature flags in 1.8:

Name	Flag	Description	Default value
Order Editing	order_editing	Allows you to edit Orders after having been placed	true
Product Categories	product_categories	Organize your products to provide customers with a better browsing experience as they navigate your catalog.	false
Publishable Keys	publishable_api_keys	Define scopes for your request to retrieve specific resources	true
Sales Channels	sales_channels	Group your products in and receive Orders from different channels	true
Tax-inclusive Pricing	tax_inclusive_pricing	Specify prices with tax included	false

Features

Multi-warehouse

We are releasing multi-warehouse capabilities in 1.8.

Expand into multiple warehousing locations with our new Inventory and Stock Location modules.

The multi-warehouse features will be enabled by installing and configuring the two modules:

yarn add @medusajs/inventory@rc @medusajs/stock-location@rc

module.exports = {
  projectConfig: {
    database_url: DATABASE_URL,
    ...
  },
  plugins,
  modules: {
    inventoryService: "@medusajs/inventory",
    stockLocationService: "@medusajs/stock-location",
  },
};

And run migrations:

medusa migrations run

After setting up the modules, a new set of settings in Medusa Admin will be available to use.

A more in-depth description will be part of 1.8.

Nested Categories

We are releasing a Product Categories API in 1.8.

Organize your products to provide customers with a better browsing experience as they navigate your catalog.

The feature is released under a feature flag. You can enable it by adding the following to your project configuration in medusa-config.js:

module.exports = {
  projectConfig: {
    database_url: DATABASE_URL,
    ...
  },
  plugins,
  modules,
  featureFlags: {
    product_categories: true
  }
};

And run migrations:

medusa migrations run

A more in-depth description will be part of 1.8.

Medusa Admin as a plugin

In 1.8, we will move Medusa Admin to our core repository to live as a plugin, @medusajs/admin. You install it directly into your Medusa project.

There are two ways of using the new admin plugin; serve it on the server or use its build tooling to deploy it on a hosting platform e.g. Vercel or Netlify.

The following steps demonstrate how to start using the admin plugin on the server. Install it with the following command:

yarn add @medusajs/admin@rc

Add it to your plugins in medusa-config.js:

module.exports = {
  projectConfig: {
    database_url: DATABASE_URL,
    ...
  },
  modules,
  featureFlags,
  plugins: [
    ...
    "@medusajs/admin"
    ]
};

Add and run the build script:

// package.json

"scripts": {
  "build:admin": "medusa-admin build"
}
...

yarn build:admin

Upon starting the server after these steps, Medusa Admin will live on the path /app on your server URL.

Event Bus module

The Redis event bus has been moved from the core into a module, allowing you to build a custom implementation using a different technology from Redis.

To install the Redis event bus, you first install the new package:

yarn add @medusajs/event-bus-redis@rc

The new events system is leveraging our Module API, so you must configure it in your project configuration in medusa-config.js:

module.exports = {
  projectConfig: {
    database_url: DATABASE_URL,
    ...
  },
  plugins,
    featureFlags,
    modules: {
      eventBus: {
	resolve: "@medusajs/event-bus-redis",
	options: {
          redisUrl: "your-redis-url"
	}
      }
    }
};

After configuring the Event Bus module, you can start your server as if nothing has changed.

Cache module

The cache mechanism has similarly been moved from the core into a module, allowing you to build a custom implementation using a different technology from Redis.

To install the Redis cache module, you first install the new package:

yarn add @medusajs/cache-redis@rc

Similar to the Event Bus module, you must configure it in your project configuration in medusa-config.js:

module.exports = {
  projectConfig: {
    database_url: DATABASE_URL,
		...
  },
  plugins,
  featureFlags,
  modules: {
    cacheService: {
      resolve: "@medusajs/cache-redis",
      options: {
        redisUrl: "your-redis-url"
      }
    }
  }
};

After configuring the Cache module, you should be able to start your server as if nothing has changed.

Payment Processor API

This release thoroughly cleans up our payment plugin domain and introduces a fresh new interface for building integrations with payment providers; the Payment Processor API:

export interface PaymentProcessor {
  /**
   * Return a unique identifier to retrieve the payment plugin provider
   */
  getIdentifier(): string

  /**
   * Initiate a payment session with the external provider
   */
  initiatePayment(
    context: PaymentProcessorContext
  ): Promise<PaymentProcessorError | PaymentProcessorSessionResponse>

  /**
   * Update an existing payment session
   * @param context
   */
  updatePayment(
    context: PaymentProcessorContext
  ): Promise<PaymentProcessorError | PaymentProcessorSessionResponse | void>

  /**
   * Refund an existing session
   * @param paymentSessionData
   * @param refundAmount
   */
  refundPayment(
    paymentSessionData: Record<string, unknown>,
    refundAmount: number
  ): Promise<
    PaymentProcessorError | PaymentProcessorSessionResponse["session_data"]
  >

  /**
   * Authorize an existing session if it is not already authorized
   * @param paymentSessionData
   * @param context
   */
  authorizePayment(
    paymentSessionData: Record<string, unknown>,
    context: Record<string, unknown>
  ): Promise<
    | PaymentProcessorError
    | {
        status: PaymentSessionStatus
        data: PaymentProcessorSessionResponse["session_data"]
      }
  >

  /**
   * Capture an existing session...

v1.7.15

Bugs

• fix(medusa): Variant update should include the id for the listeners to be able to identify the entity (#3539) @adrien2p

v1.7.14

Features

This release contains significant performance improvements in the Products domain. Please see this pull request for a detailed overview of the tests we have run, as well as the impact of the improvements.

• feat(medusa): Improve performance of Products domain (#3417) @adrien2p

Bugs

• fix(medusa): Issue on fixed total amount discount when using includes tax (#3472) @pepijn-vanvlaanderen

v1.7.13

Features

Bulk emit events
This release contains an improvement of the events system in Medusa. We've updated the EventBusService.emit method to now support bulk emitting a collection of events. This is useful in bulk upsert scenarios and significantly improves performance.

Note, these changes are backward compatible so that you can use emit to send a single event, as usual.

Single emit

await eventBusService.emit("product.created", { id: product.id }, { attempts: 4 })

Bulk emit

let events = [
  {
    eventName: "product.created",
    data: { id: product.id }
    opts: { attempts: 5 }
  }, 
  {
    eventName: "product.created",
    data: { id: product2.id }
    opts: { attempts: 3 }
  }
]

await eventBusService.emit(events)

• feat(medusa): Bulk emit events (#3407) @adrien2p

Chore

• chores(medusa): Improve draft order creation perf flow (#3431) @adrien2p

v1.7.12

Migrations & Upgrades

Overview

This release contains a migration to ensure that the product_variant_inventory table is in its correct state. We mistakenly modified a column name in an already released migration, which naturally can lead to issues if the first migration has already been applied.

The issue was reported in #3379.

Actions Required

After updating your Medusa server and before running it, run the following command to run the latest migrations:

medusa migrations run

Features

Global event options
This release contains an improvement of the events system in Medusa. Until now, the core EventBusService.emit calls have been closed for configuration. This changes in this release with the introduction of an option event_options, which is configurable in your project config in medusa-config.js.

Example:

module.exports = {
  projectConfig: {
    redis_url: REDIS_URL,
    database_url: DATABASE_URL,
    database_type: "postgres",
    store_cors: STORE_CORS,
    admin_cors: ADMIN_CORS,
    event_options: {
      removeOnComplete: 5
    }
  },
  plugins,
};

The available option is in Bull's documentation.

The attempts option on core emit calls is currently still fixed to 1.

Important: options passed in this config will be applied globally to all EventBusService.emit calls. You can still overwrite these options in your custom emit calls as they take precedence over the global options.

• feat(medusa): Add global job options for events (#3394) @olivermrbl

Bugs

• fix(medusa): Remove default job age option from EventBus (#3388) @olivermrbl
• fix(medusa): Create migration to ensure correct variant inventory column (#3384) @pKorsholm

v1.7.11

Bugs

• fix(medusa): Creating Product with Sales Channels disabled (#3357) @riqwan

v1.7.10

Features

• feat(medusa): Use Bull jobId option to identify duplicates (#3351) @olivermrbl

Bugs

• fix(medusa): Delete all payment sessions when cart total is 0 (#3346) @adrien2p

v1.7.9

Bugs

• fix(medusa): Fix regression in job scheduler service (#3335) @pepijn-vanvlaanderen

v1.7.8

Features

• feat(medusa): Configurable returnable_items on order decorate totals (#3276) @adrien2p

Bugs

• fix(medusa-js): Export resources classes and make client public (#3271) @kasperkristensen
• fix(medusa): Received quantity on return lines (#3267) @olivermrbl
• fix(oas): patch circular references in docs (#3285) @patrick-medusajs

Chores

• chore(medusa): Revert AbstractPaymentService deprecation (#3298)
• chore(docs): manually generated API reference to fix load issue (#3286) @shahednasser
• chore: changed trigger for docs generation actions (#3304) @shahednasser

v1.7.7

Features

• feat(medusa) - delete cascade modules associations (#3190) @carlos-r-l-rodrigues
• feat(oas) - accurate model OAS representation - F to O (#3210) @patrick-medusajs
• feat(medusa): Improve addShippingMethod on store cart route (#3222) @adrien2p
• feat(medusa): Allow empty fields/expand (#3220) @adrien2p
• feat(oas) - accurate model OAS representation - PA to PU (#3223) @patrick-medusajs
• feat(oas) - accurate model OAS representation - R to U (#3250) @patrick-medusajs

Bugs

• fix(medusa): Pass query transformer config in storefront controllers (#3219) @fPolic
• fix(medusa): Missing refund amount when creating claim (#3224) @olivermrbl
• fix(medusa-plugin-sendgrid): Undefined order in method to build GiftCard data (#3238) @olivermrbl
• fix(medusa): Missing withTransaction on calculateDiscountForLineItem (#3247) @adrien2p
• fix(medusa): Discount allocation precision issues (#3244) @adrien2p
• fix(medusa): Missing withTransaction on update in get-cart.ts (#3246) @adrien2p
• fix(medusa): Add missing scoped transaction on update currency endpoint (#3254) @josetr
• fix(medusa): Default sales channel on product create (#3249) @carlos-r-l-rodrigues
• fix(medusa): Refund amount on returns in claim flow (#3237) @olivermrbl

Chores

• chore: Update ignored files for npm (#3217) @adrien2p
• chore(medusa): New totals calc. in Swap creation (#3191) @adrien2p