Skip to content

Releases: medusajs/medusa

v1.12.2

11 Jul 18:45
@olivermrbl olivermrbl
v1.12.2
9fe430b
Compare
Choose a tag to compare
v1.12.2

Highlights

Simplified entity extensions

We've simplified the steps to extend an entity so you no longer need to 1) override the entity's repository (step 4 from our guide) and 2) override the models in a custom entry point file.

Our documentation on Extending an Entity has been updated to reflect these changes.

Simplified validator extensions

We've simplified the steps to extend the API payload validation so you no longer have to create a util to perform an override and include it in a loader.

Our documentation will be updated very soon to reflect these changes.

To extend a validator, import and use a new util registerOverriddenValidators.

 import { registerOverriddenValidators } from "@medusajs/medusa"
 import { AdminPostProductsReq as MedusaAdminPostProductsReq } from "@medusajs/medusa/dist/api/routes/admin/products/create-product"
 import { IsString } from "class-validator"
 
 class AdminPostProductsReq extends MedusaAdminPostProductsReq {
    @IsString()
    test: string
 }
 
 registerOverriddenValidators(AdminPostProductsReq)

Features

  • feat(create-medusa-app): support admin onboarding experience by @shahednasser in #4339
  • feat(medusa-plugin-sendgrid): Add error messages by @pevey in #4384
  • feat(medusa): Allow to register extended validators seemlesly by @adrien2p in #4397
  • feat(medusa): Improve error messaging in plugin loader by @olivermrbl in #4410
  • feat(medusa-react,medusa-js): Allow custom headers by @pevey in #4409
  • feat(medusa, types): Improve DX of model extensions (#4398) by @riqwan in #4398
  • feat: Remote Joiner by @carlos-r-l-rodrigues in #4098
  • feat(medusa, stripe, paypal): Add update payment session support to the abstract payment processor API by @adrien2p in #4442
  • feat(create-medusa-app): remove .git directory in the project by @shahednasser in #4493

Bugs

  • fix(product, types): correct path for migration files + fix types on products service module by @riqwan in #4348
  • fix(medusa, utils): fix the way selects are consumed alongside the relations by @adrien2p in #4389
  • fix(medusa-react): fix wrong admin reservations query key by @josetr in #4441

Chores

  • chore(medusa): Concurrently get the items and count instead of sequentially by @adrien2p in #4367
  • chore(gatsby-source-medusa): Cleanup plugin setup by @adrien2p in #4419
  • chore(medusa-dev-cli): Cleanup plugin setup by @adrien2p in #4421
  • chore(medusa-cli): Cleanup plugin setup by @adrien2p in #4420
  • chore(create-medusa-app): Cleanup the main script for readability and maintainability by @adrien2p in #4369

Full Changelog: v1.12.1...v1.12.2

Contributors

riqwan, pevey, and 5 other contributors
Assets 2
Loading

v1.12.1

18 Jun 11:29
@olivermrbl olivermrbl
v1.12.1
d88a57f
Compare
Choose a tag to compare
v1.12.1

Highlights

Added invite option to Medusa CLI

We've added support for inviting users to @medusajs/medusa-cli.

Invites are generated using the following command:

medusa user -e [email protected] --invite

The command generates and outputs the token to use for signup. You should see the below in your terminal:

Invite token: some_token
Open the invite in Medusa Admin at: [your-admin-url]/invite?token=some_token

Replacing [your-admin-url] with the URL of your Medusa Admin and appending the /invite?token-some_token will allow the invited user to signup.

The URL end result should look like this: https://myadmin.com/invite?token=some_token

Filtering reservations

Advanced filter capabilities have been added to the Reservations overview in Medusa Admin.

reservations-filters.mp4

Node flags in develop command

We've added support for passing all node flags to our develop command from @medusajs/medusa-cli.

E.g. medusa develop -- --preserve-symlinks

Prefix for core Redis client

You can now configure the core Redis client with prefixes using the following project configuration:

const projectConfig = {
  redis_url: REDIS_URL,
  redis_prefix: "shared"
};

Features

  • feat(medusa, inventory, stock-location): Remove unnecessary transaction usage in the modules and the list product end points by @adrien2p in #4232
  • feat(admin-ui): Rename allocation to reservation by @pKorsholm in #4133
  • feat(medusa): variants expand inventory_items by @pKorsholm in #4203
  • feat(medusa,medusa-cli): Added an invite option to the create user command, and allow seeding publishable api keys by @shahednasser in #4192
  • feat(create-medusa-app): update command for a better onboarding experience by @shahednasser in #4215
  • feat(admin-ui): Filter reservations by @pKorsholm in #4115
  • feat(medusa): Preserve node flags in develop command by @liamjcooper in #1860
  • feat(medusa): add redis_prefix in configModule.projectConfig by @dwene in #4268

Bugs

  • fix(medusa-fulfillment-manual): Missing retrieveDocuments override by @josipmatichr in #4221
  • fix(medusa): Order edit missing transaction when consuming the inventory module by @adrien2p in #4211
  • fix(medusa-plugin-brightpearl): Add bp from sales channel of order where possible by @pKorsholm in #4160
  • fix(create-medusa-app): remove seed command from create-medusa-app and improve success message by @shahednasser in #4247
  • fix(admin-ui): flickering Timeline by @fPolic in #4231
  • fix(create-medusa-app): handle todos by @shahednasser in #4262
  • fix(medusa): getAvailableContext should first check if the inventory service is present by @adrien2p in #4293
  • fix(medusa): Remove items.refundable from the order default store fields by @adrien2p in #4294
  • fix(medusa): Query parser issues with large array by @adrien2p in #4213
  • fix(medusa): medusa develop does not take execArgv into account properly by @adrien2p in #4338

Chores

  • chore(medusa,medusa-cli): Clean up new command + fix CI by @olivermrbl in #4214
  • chore(medusa): Improve database loader error handling by @adrien2p in #4254
  • chore: Clean up deps, devDeps, and peerDeps across all packages by @olivermrbl in #4276

New Contributors

Full Changelog: v1.12.0...v1.12.1

Contributors

tsvetann, scalpo, and 10 other contributors
Assets 2
Loading

v1.12.0

30 May 10:15
@olivermrbl olivermrbl
v1.12.0
d61d0d4
Compare
Choose a tag to compare
v1.12.0

Highlights

Breaking changes
In our quest to improve performance, a public method in the PriceSelectionStrategy has been updated to support bulk calculations of variant prices. Specifically, the following signatures have changed:

// Before
calculateVariantPrice(variantId: string, context: PriceSelectionContext): Promise<PriceSelectionResult>
// Now
calculateVariantPrice(data: { variantId: string; quantity?: number; }[], context: PriceSelectionContext): Promise<Map<string, PriceSelectionResult>>

Additionally (non-breaking), the following DB indexes have been added:

idx_money_amount_variant_id ON money_amount (variant_id);
idx_money_amount_region_id ON money_amount (region_id);
idx_product_option_value_variant_id ON product_option_value (variant_id);
idx_product_option_value_option_id ON product_option_value (option_id);

idx_gin_product_title ON product USING gin (title gin_trgm_ops);
idx_gin_product_description ON product USING gin (description gin_trgm_ops);
idx_gin_product_variant_title ON product_variant USING gin (title gin_trgm_ops);
idx_gin_product_variant_sku ON product_variant USING gin (sku gin_trgm_ops);
idx_gin_product_collection ON product_collection USING gin (title gin_trgm_ops);

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/utils. These should be imported from @medusajs/medusa.

Support for SQLite dropped
SQLite support was initially added to reduce friction for developers trying Medusa for the first time. It runs on most operating systems without installation, allowing you to start a Medusa starter without preparing a Postgres database.

Though, as we've added features that use more advanced database concepts, we've seen that SQLite has started to cause more harm than good. And frankly, we've not prioritized maintaining the support, as removing it was always part of our plans. SQLite still allows developers to get started very quickly. However, as soon as you start using our admin system or set up the storefront starter, issues caused by the limitations of SQLite arise. These issues are primarily centered around transaction management. A concept used extensively in our core and poorly supported by SQLite.

Therefore, as of this release, SQLite is no longer supported. The pros simply do not outweigh the cons at this point.

What does this mean for your setup?

In the highly unlikely case that you are using SQLite, this will be a breaking change. So, you'll need to set up Postgres for your Medusa server as part of bumping to this version. You can find a guide in our documentation on how to do this.

If you are not using SQLite, these changes will not affect your setup.

Reservation management
With the introduction of our Inventory Module, we added the notion of reservations. Right now, reservations are, from a store administrator perspective, limited to order items and cannot really be used outside the context of an order - unless you consume the API directly.

In this release, we ship the first elements to more extensive reservation management, including an overview of all reservations and the ability to search and edit existing reservations. The feature is still WIP, so we will hide the UI behind a new feature flag, reservations, that you can enable as any other feature flag, if you want to start playing around with the feature now.

Features

Bugs

  • fix(medusa-payment-stripe): Added withTransaction to capturePaymentIfNecessary by @DidierGuyon in #3930
  • fix(medusa): downgrade papaparse version by @fPolic in #4174
  • fix(admin-ui): Ensure that default invite link uses BASE if set by @kasperkristensen in #4173
  • fix(admin-ui): Ensure order of variant options matches order of product options by @kasperkristensen in #4178
  • fix(admin-ui): Delete variant by @olivermrbl in #4163
  • fix(inventory): Use correct table name in migration by @pKorsholm in #4155
  • fix(medusa): migrations cli should also pull from ${plugin}/dist by @dwene in #3956
  • fix(admin-ui): Omit purchasable variant prop on duplicate by @olivermrbl in #4180

Chores

New Contributors

Full Changelog: v1.11.0...v1.12.0

Contributors

tomekpur, dwene, and 8 other contributors
Assets 2
Loading

v1.11.0

16 May 09:19
@olivermrbl olivermrbl
v1.11.0
5a42c11
Compare
Choose a tag to compare
v1.11.0

Features

In 1.10.0, we changed the mechanism for loading relations in Typeorm from join to query, which meant that instead of firing one large query with joins, we fire separate queries for each requested relation. This was added to improve performance and eliminate an issue with heavy memory usage. Read more about it in the release notes for 1.10.0.

Unfortunately, we found the query strategy to come with unexpected issues related to database connection management. In short, 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 (and potential future ones), we've decided to ditch the query strategy. Instead, we are bringing back our (own) custom query strategies for Carts, Products, and Orders to maintain highly performant APIs while mitigating the risk of unexpected memory and/or database connection problems.

This also means we'll be moving away from our Typeorm fork, as the fix related to the query strategy is now irrelevant. You should update your project to use the official Typeorm package.

In your package.json, replace our forked version with the latest from Typeorm:

"typeorm": "^0.3.16"

This is in addition to bumping all you Medusa-related packages to their latest versions.

Bugs

  • fix(medusa-oas-cli): Add separator after tmpdir base by @pevey in #3924

Chores

Full Changelog: v1.10.1...v1.11.0

Contributors

riqwan, pevey, and 2 other contributors
Assets 2
Loading

v1.10.1

09 May 13:55
@olivermrbl olivermrbl
v1.10.1
27ff5a7
Compare
Choose a tag to compare
v1.10.1

Features

Version 1.10.1 introduces database schema changes that require you to run migrations. The inventory item and reservation item entities have been extended with additional properties. After upgrading to 1.10.1, run the following command:

medusa migrations run
  • feat(client-types, types, medusa, inventory): Inventory item and reservation item datamodel updates by @pKorsholm in #3971
  • feat(medusa): handle product categories in import/export strategies by @fPolic in #3842
  • feat(admin-ui): Manage inventory toggle by @pKorsholm in #4041

Bugs

  • fix(medusa): has-changes by @dwene in #4023
  • fix(search): add missing default product relations by @patpich in #4008
  • fix(medusa-payment-stripe): Catch on idempotency key retrieve if not found by @adrien2p in #4025
  • fix(medusa): ShippingOptionService.list method param type by @patpich in #4018
  • fix(medusa-plugin-contentful): Cleanup contentful plugin by @pKorsholm in #3990
  • fix(medusa): Validate customer_id when completing a cart by @fPolic in #3967
  • fix(admin-ui): Template download path by @kasperkristensen in #4050
  • fix(admin-ui): ensure that sales channel names are always an array by @riqwan in #4049

Chores

  • chore(utils): update class-validator to 0.14.0 by @pevey in #4032

New Contributors

Full Changelog: v1.10.0...v1.10.1

Contributors

patpich, riqwan, and 6 other contributors
Assets 2
Loading

v1.10.0

04 May 08:56
@olivermrbl olivermrbl
v1.10.0
731f05d
Compare
Choose a tag to compare
v1.10.0

Breaking changes

Performance improvements
To improve performance of Cart and Product retrieval, we've 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.

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, we decided to fix the issue in Typeorm, which can be found in this PR. It is still yet to be merged, so for now, we have published a forked version of Typeorm that includes the fix. This is the breaking change of this release.

To make sure your project works as expected, you will need to use our forked version in your project until Typeorm accepts our PR and publishes a new version.

In your package.json, replace the Typeorm version with the following:

"typeorm": "npm:@medusajs/typeorm@next"

Features

Listing products
In #4010, we've introduced checks in our Product API ensuring that product pricing and availability are only set if they are requested.

The impacted endpoints are:

GET /store/products
GET /store/products/:id

GET /admin/products
GET /admin/products/:id

By default, these properties will be set on the product and product variants, but if you specify the expand query param on your request, you might not receive product pricing and availability. To include those, add variants and variant prices to the expand. It will look like this:

GET /store/products?expand="variants,variants.prices"

Bugs

Event Bus
In v1.9.0, we changed the events system to only fire an event if it had any subscribers. This spawned a bug around wildcard subscribers that we missed in our testing. Wildcard subscribers are supposed to run on all events and are created like so:

eventBusService.subscribe("*", someMethodToHandleEvent)

To make up for this mistake, we've rolled back the changes introduced in 1.9.0 and will go back to the drawing board at some point in the future.

Chores

New Contributors

Full Changelog: v1.9.0...v1.10.0

Contributors

rajshrimohanks, vladimirpekez, and 6 other contributors
Assets 2
Loading

v1.9.0

26 Apr 17:19
@olivermrbl olivermrbl
v1.9.0
b41b630
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.
Compare
Choose a tag to compare
v1.9.0

Breaking changes

A minor breaking change has been introduced to the events system. The EventBusModule interface has been updated with a new method, retrieveSubscribers. The method is used in the core EventBusService to fetch subscribers to a given event upon emitting one or multiple events. If no subscribers exist to an event, we do not insert a staged job in the database which means the event will not be sent for processing in the event bus module.

Features

  • feat(medusa): Add purchasable prop on variants when setting availability by @pKorsholm in #3811
  • feat(admin-ui): Implement allocations on draft orders by @StephixOne in #3753
  • feat(medusa-file-s3,medusa-file-minio): Upgrade to TypeScript by @dwene in #3740
  • feat(medusa, medusa-plugin-brightpearl): Inventory management for Brightpearl by @pKorsholm in #3192
  • feat(medusa-plugin-meilisearch): Update meilisearch library dependency by @pevey in #3898
  • feat(admin-ui): Add Sales Channel filter by @olivermrbl in #3897
  • feat(medusa): Middleware to add default SC on query if no SC already exist on it by @StephixOne in #3694

Bugs

  • fix(admin-ui): password reset flip rendering condition by @nowseemee in #3864
  • fix(inventory): Add missing context arguments by @olivermrbl in #3863
  • fix(medusa): Add missing relations when creating return by @olivermrbl in #3870
  • fix(medusa): Bulk create variant + pass transaction to the inventory service context methods by @adrien2p in #3835
  • fix(medusa): Correct inventory quantity calculation by @pKorsholm in #3881
  • fix(medusa-plugin-ip-lookup): Remove outdated Typeorm usage by @olivermrbl in #3884
  • fix(admin-ui): Check for undefined categories by @olivermrbl in #3886
  • fix(inventory): Minor fixes to upserting inventory items by @olivermrbl in #3883
  • fix(medusa,medusa-fulfillment-webshipper): Add default values in Webshipper service by @olivermrbl in #3879
  • fix(admin-ui): Add guard for null product_id by @pKorsholm in #3894
  • fix(medusa,utils): Searching indexing product subscriber by @olivermrbl in #3905
  • fix(admin): display correct items in the timeline after OE by @fPolic in #3895
  • fix(medusa): category list api bug where limit skews results by @riqwan in #3914
  • fix(medusa): Reduce joins in cart retrieval by @olivermrbl in #3909

Chores

  • chore: Bump package versions to address security vulnerabilities by @pevey in #3845

New Contributors

Full Changelog: v1.8.2...v1.9.0

Contributors

StephixOne, nowseemee, and 7 other contributors
Assets 2
Loading

v1.8.2

14 Apr 09:26
@olivermrbl olivermrbl
v1.8.2
0f51e3a
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.
Compare
Choose a tag to compare
v1.8.2

Features

  • feat(oas): new medusa-oas docs for Redocly and circular references by @patrick-medusajs in #3745
  • feat(medusa,utils): add server level configurable http compression by @riqwan in #3785
  • feat(medusa): allow category list api to be filtered by handle by @riqwan in #3825

Bugs

Docs

New Contributors

Contributors

naumovskamarija, riqwan, and 2 other contributors
Assets 2
Loading

v1.8.1

12 Apr 09:43
@olivermrbl olivermrbl
v1.8.1
3efe13e
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.
Compare
Choose a tag to compare
v1.8.1

Features

  • feat(tests): harmonize and clean-up yarn test commands convention by @patrick-medusajs in #3695
  • feat(medusa, admin-ui): add description field to product categories by @riqwan in #3768

Bugs

  • fix(react): Fix input type on useAdminUpdateReservation mutation hook by @StephixOne in #3732
  • fix(admin-ui): display SC update notification by @fPolic in #3755
  • fix(medusa-react): update customer hook payload type by @fPolic in #3752
  • fix(admin-ui): "cancel fulfillment" notification text by @fPolic in #3750
  • fix(medusa): export product prices in human-readable format by @fPolic in #3739
  • fix(medusa): Throw on line item generation if variant does not have a price by @adrien2p in #3766
  • fix(medusa-plugin-economic,medusa-plugin-mailchimp,medusa-plugin-restock-notification,medusa-plugin-sendgrid,medusa-plugin-wishlist): Temporarily remove payload validation in some plugins by @StephixOne in #3763
  • fix(medusa): Add totals when retrieving order by cart id by @olivermrbl in #3777
  • fix(medusa): validate customer for group discount by @fPolic in #3797

Chores

  • chores(medusa): cleanup registrations life time by @adrien2p in #3699
  • chore(medusa): Migrate product type repository by @adrien2p in #3727
  • chore(medusa): Migrate product tag repository by @adrien2p in #3726
  • chore(medusa): Migrate payment collection repository api by @adrien2p in #3724
  • chore(medusa): migrate SalesChannel / ProductCategory repository by @riqwan in #3728
  • chore(medusa, utils): rename buildLegacyFieldsListFrom to objectToStringPath by @riqwan in #3738
  • chore(medusa): Migrate price list repository by @adrien2p in #3725
  • chore(medusa): Upgrade ioredis-mock by @olivermrbl in #3704
  • chore: Bump Typeorm by @olivermrbl in #3778

New Contributors

Contributors

StephixOne, thephpguy, and 6 other contributors
Assets 2
Loading

v1.8.0

04 Apr 16:52
@olivermrbl olivermrbl
v1.8.0
66c59d5
Compare
Choose a tag to compare
v1.8.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.

Introduction

Today, we’re excited to announce the release of Medusa 1.8.

This release comes with many new features while introducing architectural changes contributing toward making Medusa more modular and portable to new, modern environments.

We’ve added multi-warehouse capabilities and support for nested categories, introduced a new payment processor interface (and migrated the most used plugins Stripe and Paypal), moved Medusa Admin to our mono-repository, and revamped it to be shipped as an npm package (like all other packages), expanded our OpenAPI Spec tooling and added dedicated types packages for client applications, upgraded Typeorm, and created a range of new modules leveraging our Modules API.

The overall theme of this release has been modularity. All changes introduced in 1.8 are dedicated to making Medusa a toolbox for developers to create rich commerce applications. We are enabling a future for commerce businesses where they can focus on innovation and differentiating – without having to worry about re-platforming or hacky workarounds.

Our packages are all open-source, free, and extensible.

Get Started

It's recommended to use yarn when updating the following dependency to avoid any unexpected errors.

To get started using Medusa 1.8, you can create a new project using our Quickstart guide or follow the steps outlined below:

First, upgrade your version of Typeorm:

yarn add [email protected]

The dependency on Typeorm has been upgraded from 0.2.31 to 0.3.11, that comes with significant breaking changes. Follow Typeorm's upgrade guide to refactor your custom code.

Install the 1.8 version of the core:

yarn add @medusajs/medusa@latest

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 must install and use those modules to ensure your application works as expected.

Install the new Redis cache module with the following command:

yarn add @medusajs/cache-redis@latest

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

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

Then, add both modules to the exported configuration in 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"
      }
    }
  }
}

Replace your-redis-url with the URL to your Redis instance.

Finally, run migrations to ensure your database is up to date with our schema changes:

medusa migrations run

You are now set up to start using 1.8.

There are plenty of other features and improvements to leverage in your project. Those are covered in the following sections.

But before that, here’s a non-exhaustive overview of what’s new in Medusa 1.8:

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

What’s new in 1.8?

Feature flags

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
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

Modules

The terms modules and Modules API are used extensively throughout these release notes, so we want to preface the features overview with a short explanation of the concept. Refer to the product announcement and our documentation for more elaborate walkthroughs.

As mentioned, the overall theme of this release has been modularity. We have started breaking up our monolithic core into modules. These modules are isolated bundles of code encapsulating a specific domain. Domain in this context refers to an area in your application that is logically coherent e.g. users, products, cart, etc.

The modules separate the concerns in Medusa at an architectural level and pave the way for more extensibility and customizability of your setup. Furthermore, the modules live separately from the core, allowing developers to run them independently from the main application.

As such, applying these architectural changes across all domains will make almost any part of Medusa entirely replaceable and capable of running on infrastructure in isolation from each other e.g. in a serverless environment, on edge, etc.

In 1.8, the usage of our Modules API is rather simple. We are introducing four modules; events, caching, inventory, and stock location. Initially, these modules live up to one of the two characteristics mentioned. They are entirely replaceable.

A module comes with a definition containing information about its configuration and capabilities. These definitions can be found in the new Modules SDK package, @medusajs/modules-sdk, in the file definitions.ts.

Let's take the event bus module definition as an example to describe the properties:

{
    key: "eventBus",
    registrationName: "eventBusModuleService",
    defaultPackage: "@medusajs/event-bus-local",
    label: "EventBusModuleService",
    canOverride: true,
    isRequired: true,
    defaultModuleDeclaration: {
      scope: MODULE_SCOPE.INTERNAL,
      resources: MODULE_RESOURCE_TYPE.SHARED,
    },
  },
Property Description
key The key to register a module in your medusa-config.js. As you did with the event bus module in the Get Started section above.
registrationName The name of the main service of the module and its registration in the Awilix dependency container.
defaultPackage If the module comes with a default package, it will be added directly in the definition. If there's no default package, this value is false.
label Readable label to identify the module
canOverride If true, the module is replaceable
isRequired If true, the module is required
defaultModuleDeclaration.scope The module can be internal or external. An internal module communicates with other services part of the same application. An external module communicates with other services via a separate protocol e.g. HTTP, rpc, etc.
defaultModuleDeclaration.resources The module can share resources with the core. A module that shares resources with the core uses the same database connection in the core. A module that does not share resources with the core establishes a separate connection or uses a different data store.

Modules are loaded similarly to plugins. Upon server start, we look for modules in your medusa-config.js and register them, given they are correctly configured.

In medusa-config.js, modules are registered as shown previously:

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

In the example above, we override the default event bus module with a Redis implementation. The resolve property of the module configuration can point to a package on npm or a local folder/file. The options are injected into the module upon initializing it. You can find more on this in our documentation.

What's to come

We are actively working toward making modules capable of booting up outside of the core in complete isolation hereby living up to the second of the two characteristics.

To give you an idea of what we are building, consider the following handler:

import { initialize } from "@medusajs/cart"
import { NextApiRequest, NextApiResponse } from "next"

const cartService = await initialize()

export default async (req: NextApiRequest, res: NextApiResponse) => {
  const { cart_id } = req.query
  const { quantity, variant_id } = req.body

  try {
    const cart = await cartService.addLineItem(cart_id, { quantity, variant_id })

    res.json({ cart })
  } catch (e) {
    res.status(400).json({ error: e.message })
  }
}

Now, please don't get caught up in the details. The above code snippet is not necessarily exactly what it will look like but merely an example to communicate the road ahead for modules.

This way of working with modules is exceptionally flexible. It equips developers with a powerful toolkit to build commerce applications similar to how you build other applications in...

Read more

Contributors

StephixOne, riqwan, and 14 other contributors
Assets 2
Loading