Published by olivermrbl over 1 year ago
This release ships with the first iteration of our Bulk Editor, allowing you to edit your product variant prices in an Excel-like fashion.
https://github.com/medusajs/medusa/assets/59018053/14d126d2-bba0-4332-aff5-65b4e4c5d481
metadata
to StorePostCartsCartLineItemsItemReq
by @erikengervall #4230Full Changelog: https://github.com/medusajs/medusa/compare/v1.12.2...v1.12.3
Published by olivermrbl over 1 year ago
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.
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)
Full Changelog: https://github.com/medusajs/medusa/compare/v1.12.1...v1.12.2
Published by olivermrbl over 1 year ago
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
Advanced filter capabilities have been added to the Reservations overview in Medusa Admin.
https://github.com/medusajs/medusa/assets/59018053/ea750918-bd2e-4697-ac2b-26892e88786c
We've added support for passing all node flags to our develop
command from @medusajs/medusa-cli
.
E.g. medusa develop -- --preserve-symlinks
You can now configure the core Redis client with prefixes using the following project configuration:
const projectConfig = {
redis_url: REDIS_URL,
redis_prefix: "shared"
};
Timeline
by @fPolic in https://github.com/medusajs/medusa/pull/4231
Full Changelog: https://github.com/medusajs/medusa/compare/v1.12.0...v1.12.1
Published by olivermrbl over 1 year ago
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.
papaparse
version by @fPolic in https://github.com/medusajs/medusa/pull/4174
Full Changelog: https://github.com/medusajs/medusa/compare/v1.11.0...v1.12.0
Published by olivermrbl over 1 year ago
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.
ioredis
options by @olivermrbl in https://github.com/medusajs/medusa/pull/4073
Full Changelog: https://github.com/medusajs/medusa/compare/v1.10.1...v1.11.0
Published by olivermrbl over 1 year ago
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
customer_id
when completing a cart by @fPolic in https://github.com/medusajs/medusa/pull/3967
Full Changelog: https://github.com/medusajs/medusa/compare/v1.10.0...v1.10.1
Published by olivermrbl over 1 year ago
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"
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"
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.
Full Changelog: https://github.com/medusajs/medusa/compare/v1.9.0...v1.10.0
Published by olivermrbl over 1 year ago
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.
product_id
by @pKorsholm in https://github.com/medusajs/medusa/pull/3894
Full Changelog: https://github.com/medusajs/medusa/compare/v1.8.2...v1.9.0
Published by olivermrbl over 1 year ago
medusa-oas docs
for Redocly and circular references by @patrick-medusajs in https://github.com/medusajs/medusa/pull/3745
Published by olivermrbl over 1 year ago
Published by olivermrbl over 1 year ago
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.
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.
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:
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
|
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 your stack. For example, using Medusa in concert with a framework like Next.js will allow developers to build a full-stack application within a single project.
We are excited to share more on this as our development advances.
Now that we are familiar with the fundamentals of modules let's proceed with the new features in 1.8.
Expand into multiple warehouse locations with our new Inventory and Stock Location modules.
Installation
The multi-warehouse features will be enabled by installing and configuring the two modules:
yarn add @medusajs/inventory@latest @medusajs/stock-location@latest
module.exports = {
projectConfig: {
database_url: DATABASE_URL,
...
},
plugins,
modules: {
inventoryService: "@medusajs/inventory",
stockLocationService: "@medusajs/stock-location",
},
}
Run migrations:
medusa migrations run
And finally, run a script to migrate current product variant information to fit the schema changes introduced by these modules:
node ./node_modules/@medusajs/medusa/dist/scripts/migrate-inventory-items.js
After setting up the modules, a new set of settings in Medusa Admin will be available.
Managing inventory
In the Inventory section, you'll obtain a comprehensive overview of your inventory items within a specific warehouse, providing you with a clear understanding of your real-time stock.
Managing inventory items
Inventory is managed together with an inventory item’s variant information.
Flexible fulfillment
Fulfill orders from various locations, including the ability to split orders across stock locations.
Read the full product announcement here.
Our new Product Category API allows you to create, nest, and rank categories and add products to each. Categories are a way to organize your products to provide customers with a better browsing experience as they navigate their way through 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 (these might already be applied to your database, as we have only hidden the API behind the flag):
medusa migrations run
You now have a simple yet powerful Product Category API at your fingertips. Combine the API with other features of Medusa to create a fantastic customer experience and manage it all in your admin, as seen below:
Read the full product announcement here or dive into the technical details of the feature in the RFC.
Moving Medusa Admin to the core has been a long-standing wish of ours, and we are very excited to finally see it happen. The move was motivated by frequent issues with versioning between core and admin features and an eagerness to improve the developer experience - internally and externally.
The new Medusa Admin is released as @medusajs/admin
and can be installed directly into your Medusa project – similar to any other plugin.
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@latest
Add it to your plugins in medusa-config.js
:
module.exports = {
projectConfig,
modules,
featureFlags,
plugins: [
...
{
resolve: "@medusajs/admin",
/** @type {import('@medusajs/admin').PluginOptions} */
options: {
autoRebuild: true,
},
},
]
};
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.
We highly recommend reading through the full product announcement and the technical overview, as it is important to understand the limitations and features of the admin plugin.
The framework powering the events system of Medusa will no longer be baked into the core package. In 1.8, we are introducing an event bus module alongside two implementations; one using the Node EventEmitter, and the other using Redis.
The event bus module lets businesses choose the underlying technology powering their events system. Medusa has always relied on Redis and Bull for handling events. But as businesses increasingly adopt Medusa into their existing technology stack, we’ve seen a rise in demand for leveraging existing infrastructure. Businesses that already have an events system in place can now configure Medusa to leverage that instead of having to spin up additional services, adding unnecessary complexity to their stack.
By default, Medusa will come with the Node EventEmitter event bus installed. We advise using the Redis event bus for projects already in or close to production, as it is geared toward production environments.
To install the Redis event bus, you first install the new package:
yarn add @medusajs/event-bus-redis@latest
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,
plugins,
featureFlags,
modules: {
eventBus: {
resolve: "@medusajs/event-bus-redis",
options: {
redisUrl: "your-redis-url"
}
}
}
}
After configuring the Redis event bus module, you can start your server as if nothing has changed.
Read the full product announcement here, and refer to the module README for an overview of the options you can pass to the event bus.
The framework powering the caching mechanism of Medusa will neither no longer be baked into the core package. In 1.8, we are introducing a cache module alongside two implementations, one storing data in memory and the other using Redis.
The motivation behind adding the cache module is the same as with the event bus. It is a step toward a more flexible architecture where businesses are not constrained to a specific piece of technology.
By default, Medusa will come with the in-memory cache module installed. Though again, we advise using the Redis module for production environments, as the in-memory one does not scale well.
To use the Redis cache module, you first install the new package:
yarn add @medusajs/cache-redis@latest
Configure it in your project configuration in medusa-config.js
:
module.exports = {
projectConfig,
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.
Read the full product announcement here.
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
* @param paymentSessionData
*/
capturePayment(
paymentSessionData: Record<string, unknown>
): Promise<
PaymentProcessorError | PaymentProcessorSessionResponse["session_data"]
>
/**
* Delete an existing session
*/
deletePayment(
paymentSessionData: Record<string, unknown>
): Promise<
PaymentProcessorError | PaymentProcessorSessionResponse["session_data"]
>
/**
* Retrieve an existing session
*/
retrievePayment(
paymentSessionData: Record<string, unknown>
): Promise<
PaymentProcessorError | PaymentProcessorSessionResponse["session_data"]
>
/**
* Cancel an existing session
*/
cancelPayment(
paymentSessionData: Record<string, unknown>
): Promise<
PaymentProcessorError | PaymentProcessorSessionResponse["session_data"]
>
/**
* Return the status of the session
*/
getPaymentStatus(
paymentSessionData: Record<string, unknown>
): Promise<PaymentSessionStatus>
}
Our Stripe and PayPal payment plugins have been migrated to follow this interface.
We’ve removed all database mutations from the plugins to constrain their functionality to only be about communicating with the 3rd party service. This will mitigate the risk of nasty issues with database transactions spanning the core and plugins.
To mutate entities in the core database from a payment plugin, you must pass an update request in your call to initiate the payment. This flow may sound complex, but it is fairly straightforward, as seen in the example below.
The core payment provider service initiates payments. To create a payment object specific to your provider, we call the plugin method initiatePayment
. The plugin must respond with a PaymentSessionResponse
that has the following shape:
export type PaymentSessionResponse = {
update_requests: { customer_metadata: Record<string, unknown> }
session_data: Record<string, unknown>
}
As you might have guessed, the update_requests
property is what you will be using to mutate data in the core. In the first iteration, we define the constraints of the update requests, which are initially limited to customer metadata.
In the case of Stripe, we store the Stripe customer id on the customer entity in Medusa, such that we can identify customers and potentially present payment methods on subsequent orders.
So from the initiatePayment
method in the Stripe plugin, we “send back” the following object to the core:
{
session_data,
update_requests: customer?.metadata?.stripe_id
? undefined
: {
customer_metadata: {
stripe_id: intentRequest.customer,
},
},
}
This will trigger the payment provider service in the core to update the Medusa customer metadata with the Stripe customer id.
We’ve added backward compatibility in the Stripe and PayPal plugins, as these are by far the most used providers. That said, we highly recommend updating the core and plugins to the latest versions as soon as possible to avoid any unexpected issues.
Read the full product announcement here.
We will introduce the first iteration of our OpenAPI Spec (OAS) tooling, including automated SDK generation, a thorough clean-up of our OAS in the API layer, and a new types package.
Included in the OAS tooling, we ship a CLI allowing you to extend our SDKs and types based on custom OAS in your Medusa project.
Let's say you have the following OAS schema in your own project in file src/simple-product.ts
:
/**
* @schema SimpleProduct
* title: "SimpleProduct"
* description: "Pretty simple product"
* type: object
* required:
* - handle
* - id
* properties:
* id:
* description: The product's ID
* type: string
* example: prod_01G1G5V2MBA328390B5AXJ610F
* handle:
* description: A unique identifier for the Product (e.g. for slug structure).
* nullable: true
* type: string
* example: coffee-mug
*/
You can extend our Store API OAS output with this schema by running the following command (given that you have the CLI installed):
yarn medusa-oas-cli oas --type store --paths ~path-to-your-project/src
This will add the SimpleProduct
to the generated store.oas.json
:
"SimpleProduct": {
"title": "SimpleProduct",
"description": "Pretty simple product",
"type": "object",
"required": [
"handle",
"id"
],
"properties": {
"id": {
"description": "The product's ID",
"type": "string",
"example": "prod_01G1G5V2MBA328390B5AXJ610F"
},
"handle": {
"description": "A unique identifier for the Product (e.g. for slug structure).",
"nullable": true,
"type": "string",
"example": "coffee-mug"
}
}
}
Now that you've generated your OAS, you can create a type to live alongside all the types from our core. You do so by running the following command:
yarn medusa-oas client --src-file ./store.oas.json --out-dir ./src/client-types --type store --component types
Inspect the ./src/client-types
and find your SimpleProduct.ts
in the models/
folder.
With great excitement, we also announce the @medusajs/client-types
package - a highly requested package that separates client types from the core. It has been reported several times that importing the core package in client applications to use types is far from ideal. It blows up the bundle size of the application and introduces many unnecessary dependencies. You should now be able to remove the dependency on the core package and use the client types one instead.
Read the full product announcement here.
In the same vein, we are also introducing two new packages for utils and types that live without a dependency on the core.
The reasoning is the same as with the client types; we want to improve the developer experience when building server applications by eliminating the need to import a huge core package to leverage our types.
Initially, these packages will contain very few types, but we will move all common, shared types and utils to the two new packages in the coming months.
The packages are published under:
@medusajs/types
@medusajs/utils
We are extending the capabilities of search services and updating all plugins to use the latest version of their provider-specific SDK.
We are now exposing a transformer function in the config, allowing developers to build custom resource transformers. Effectively, this means you’ll be able to store the entities of Medusa in whatever format fits your use case.
As always, search plugins are configured in medusa-config.js
. You can add the transformer function on a per-index basis. The following example is for a products index:
{
resolve: "medusa-plugin-meilisearch",
options: {
apiKey: "api-key",
host: "http://localhost:7700" },
products: {
indexSettings: {
searchableAttributes: ["title", "description", "variant_sku"],
displayedAttributes: ["title", "description"],
},
transformer: (product: Product) => {
return {
id: product.id,
title: `Custom title: ${product.title}`,
}
}
}
}
The attentive reader might have spotted that we are now nested provider-specific settings in a variable indexSettings
. This has been added to allow for the transformer feature. The settings are backward compatible, but if you want to leverage the transformer, you must fit the new shape of the configuration.
Aside from modularity, we have another central focus area: performance improvements. We are pushing hard to ensure that all frequently used domains such as Orders, Products, and Checkout are remarkably performant.
We are currently synthesizing benchmarks to share publicly. Until these are published, you can refer to the following pull requests to see the changes and related tests:
We’ve upgraded Typeorm from 0.2.31 to ^0.3.11 to leverage a range of significant improvements added by the Typeorm team in 0.3.
This upgrade has brought with it a large amount of breaking changes. Refer to their release notes for an overview of all breaking changes.
We will only cover the changes that affected Medusa, and how you should handle them in your custom implementations.
Changes to find
and findOne
You can find a detailed walkthrough of the changes to these methods in Typeorm’s release notes. We’ll cover it briefly.
find()
without any arguments used to return all records of a given entity. This now throws an error. You have to pass an empty object to achieve the same behaviour as before.
findOne({})
and findOne(undefined)
used to return the first record of a given entity. These now return null
.
findOne(id)
has been dropped. To retrieve an entity by id, you now have to use findOneBy({ id: "some_id" })
findOne()
now requires a where
option in its query object to filter data findOne({ where: { ... }})
. The same goes for methods findOne
, findOneOrFail
, find
, count
, findAndCount
.
Querying for enums now requires you to use the enum value directly. You cannot pass the string value of the enum.
Utilities
We’ve added utilities that transform data from what was previously expected to the new format to make the upgrade seamless. You can find those in the build-query.ts
utility file.
Repositories
Repositories no longer extend a base class, nor are they of type class. They are created as extensions to the DataSource
.
DataSource
Typeorm’s Connection
has been deprecated in favor of DataSource
.
npx create-medusa-app
commandAs mentioned, we are pushing the modularity agenda hard these days. In the near future, you’ll see other domains of Medusa shipped as modules and support for spinning these up in complete isolation.
You can find our tentative roadmap on GitHub Discussions. This is forever work-in-progress, and we will continuously update and refine it to fit the needs of our users and the general developer community.
Give Medusa 1.8 a go - we are excited to hear your thoughts. As always, please report GitHub Issues in our repository, and file feature requests on GitHub Discussions.
Happy hacking!
Team Medusa 💜
A huge thanks to all contributors to this release - you've all been absolutely killing it to make this release a reality!
/admin
and /store
in paths URLs (#3314)activeManager_
getter in TransactionBaseService (#3256)expand
parameter on order page (#3383)tailwindcss/nesting
correctly (#3404)expand
parameter on order page (#3383)tailwindcss/nesting
correctly (#3404)Published by olivermrbl over 1 year ago
Published by olivermrbl over 1 year ago
Published by olivermrbl over 1 year ago
Published by olivermrbl over 1 year ago
Published by olivermrbl over 1 year ago
Published by olivermrbl over 1 year ago
Published by olivermrbl over 1 year ago
Published by olivermrbl over 1 year ago
Published by olivermrbl over 1 year ago
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.
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.
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:
This is not an exhaustive overview. Refer to the concrete changes at the bottom of the notes for a more detailed overview.
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
|
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.
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.
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.
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.
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.
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
* @param paymentSessionData
*/
capturePayment(
paymentSessionData: Record<string, unknown>
): Promise<
PaymentProcessorError | PaymentProcessorSessionResponse["session_data"]
>
/**
* Delete an existing session
*/
deletePayment(
paymentSessionData: Record<string, unknown>
): Promise<
PaymentProcessorError | PaymentProcessorSessionResponse["session_data"]
>
/**
* Retrieve an existing session
*/
retrievePayment(
paymentSessionData: Record<string, unknown>
): Promise<
PaymentProcessorError | PaymentProcessorSessionResponse["session_data"]
>
/**
* Cancel an existing session
*/
cancelPayment(
paymentSessionData: Record<string, unknown>
): Promise<
PaymentProcessorError | PaymentProcessorSessionResponse["session_data"]
>
/**
* Return the status of the session
*/
getPaymentStatus(
paymentSessionData: Record<string, unknown>
): Promise<PaymentSessionStatus>
}
The new interface has been applied to our Stripe and PayPal payment plugins.
We will introduce the first iteration of our OpenAPI Spec (OAS) tooling, including automated SDK generation, a thorough clean-up of our OAS in the API layer, and a client types package - shipped separately from the core.
The client types package is published under @medusajs/client-types
Included in the OAS tooling, we ship a CLI allowing you to extend our SDKs and types based on custom OAS in your Medusa project.
Let's say you have the following OAS schema in your own project in file src/simple-product.ts
:
/**
* @schema SimpleProduct
* title: "SimpleProduct"
* description: "Pretty simple product"
* type: object
* required:
* - handle
* - id
* properties:
* id:
* description: The product's ID
* type: string
* example: prod_01G1G5V2MBA328390B5AXJ610F
* handle:
* description: A unique identifier for the Product (e.g. for slug structure).
* nullable: true
* type: string
* example: coffee-mug
*/
You can extend our Store API OAS output with this schema by running the following command (given that you have the CLI installed):
yarn medusa-oas-cli oas --type store --paths ~path-to-your-project/src
This will add the SimpleProduct
to the generated store.oas.json
:
"SimpleProduct": {
"title": "SimpleProduct",
"description": "Pretty simple product",
"type": "object",
"required": [
"handle",
"id"
],
"properties": {
"id": {
"description": "The product's ID",
"type": "string",
"example": "prod_01G1G5V2MBA328390B5AXJ610F"
},
"handle": {
"description": "A unique identifier for the Product (e.g. for slug structure).",
"nullable": true,
"type": "string",
"example": "coffee-mug"
}
}
}
Now that you've generated your OAS, you can create a type to live alongside all the types from our core. You do so by running the following command:
yarn medusa-oas client --src-file ./store.oas.json --out-dir ./src/client-types --type store --component types
Inspect the ./src/client-types
and find your SimpleProduct.ts
in the models/
folder.
In the same vein, we are also introducing two new packages for utils and types that live without a dependency on the core.
The packages are published under
@medusajs/types
@medusajs/utils
We are extending the capabilities of search services and updating all plugins to use the latest version of their provider-specific SDK.
Most important is the change to the configuration of search plugins. We are updating the shape of index settings. Consider the example with Meilisearch below:
export interface MeilisearchPluginOptions {
/**
* Meilisearch client configuration
*/
config: Config
/**
* Index settings
*/
settings?: {
[key: string]: SearchTypes.IndexSettings
}
}
export type IndexSettings = {
/**
* Settings specific to the provider. E.g. `searchableAttributes`.
*/
indexSettings: Record<string, unknown>
/**
* Primary key for the index. Used to enforce unique documents in an index. See more in Meilisearch' https://docs.meilisearch.com/learn/core_concepts/primary_key.html.
*/
primaryKey?: string
/**
* Document transformer. Used to transform documents before they are added to the index.
*/
transformer?: (document: any) => any
}
As you can see, the index settings that are specific to each provider have been moved to live under the property indexSettings
in the type IndexSettings
.
The new transformer
function allows you to overwrite how the Medusa entities are transformed before being stored in the search provider's data store.
Example:
{
resolve: "medusa-plugin-meilisearch",
options: {
...,
products: {
transformer: async (product: Product) => ({ id: product.id, some_external_prop: "This is an external property" })
}
}
}
This section will not cover all the new UI for the features that are included in the release. Those will be covered in each feature section in the official 1.8 notes.
Sign in: Simplified
Managing Gift Cards: Switching to use the standard Product page
We’ve upgraded Typeorm from 0.2.31 to ^0.3.11 to leverage a range of significant improvements added by the Typeorm team in 0.3.
This upgrade has brought with it a large amount of breaking changes. Refer to their release notes for an overview of all breaking changes.
We will only cover the changes that affected Medusa, and how you should handle them in your custom implementations.
Changes to find
and findOne
You can find a detailed walkthrough of the changes to these methods in Typeorm’s release notes. We’ll cover it briefly.
find()
without any arguments used to return all records of a given entity. This now throws an error. You have to pass an empty object to achieve the same behaviour as before.
findOne({})
and findOne(undefined)
used to return the first record of a given entity. These now return null
.
findOne(id)
has been dropped. To retrieve an entity by id, you now have to use findOneBy({ id: "some_id" })
findOne()
now requires a where
option in its query object to filter data findOne({ where: { ... }})
. The same goes for methods findOne
, findOneOrFail
, find
, count
, findAndCount
.
Querying for enums now requires you to use the enum value directly. You cannot pass the string value of the enum.
Utilities
We’ve added utilities that transform data from what was previously expected to the new format to make the upgrade seamless. You can find those in the build-query.ts
utility file.
Repositories
Repositories no longer extend a base class, nor are they of type class. They are created as extensions to the DataSource
.
DataSource
Typeorm’s Connection
has been deprecated in favor of DataSource
.
To be filled out
Thanks to all contributors to this release 💜
Happy hacking!
Team Medusa
/admin
and /store
in paths URLs (#3314)activeManager_
getter in TransactionBaseService (#3256)expand
parameter on order page (#3383)tailwindcss/nesting
correctly (#3404)expand
parameter on order page (#3383)tailwindcss/nesting
correctly (#3404)