v2.13.0: Improved Translations, Priority-based event processing, Better pnpm support
Highlights
Zod dependency restructuring
:construction: Breaking change
This release adds zod as a dependency of @medusajs/framework.
This change has been marked as breaking although for the vast majority of projects, existing zod imports will continue to work through either as a direct dependency (if zod is installed directly in your project), or a transitive dependency.
Developers using pnpm couldn't access zod due to strict dependency isolation. Since zod is essential for Medusa development, making it a framework export ensures consistent versioning and accessibility, similar to other third-party libraries used in Medusa.
Migration
Update your zod imports from:
import { z } from "zod"
To:
import { z } from "@medusajs/framework/zod"
We've added a codemod to automate this migration. After updating to the latest version, run:
This release adds a new admin dashboard interface for managing translation settings, allowing merchants to configure which entities and fields are translatable directly from the UI.
Translatable modifier in the Data Model API
This release adds a new .translatable() modifier for text properties in the Data Model API.
Example Usage:
const Store = model.define("store", {
name: model.text().translatable(),
description: model.text().translatable(),
})
These two changes to Translations improve the experience of managing translatable entities and their translatable fields. When the translatable modifier from the Data Model API is used, the entity will automatically be marked as translatable. This will make it available for configuration in the admin dashboard. Merchants can select what fields of each entity needs translation.
In https://github.com/medusajs/medusa/releases/tag/v2.12.4, we added support for translating custom entities by specifying them in the module options of Translations. This option has been removed in favor of the changes in this release. As described above, entities that has any field with the .translatable() modifier will be marked as translatable.
The following are required actions, if you have already translated data models from custom modules:
Remove the entities option from the translation module in medusa-config.ts
Add the .translatable() property to fields in your data model definitions
Configure the translatable entities from the new management view in the admin dashboard
Existing translations for custom data models will remain as is after the upgrade.
This release introduces a priority queue system for event processing to improve system responsiveness and prevent internal events from blocking critical business operations.
Key Changes
Event processing now uses priority levels to determine processing order (lower number = higher priority)
Internal system events are automatically assigned the lowest priority to prevent queue overload
Critical business events like order placement are processed first with high priority (priority 10)
All other events default to standard priority (priority 100)
Priority can be customized at message, emit, or module level for fine-grained control
This ensures that important customer-facing events (e.g., order confirmations) are processed immediately, even during high-volume internal system operations.
https://github.com/medusajs/medusa/pull/14476
Improved support for pnpm
This release resolves common issues with pnpm for new installations.
create-medusa-app now installs Medusa with the package manager you're using:
yarn dlx create-medusa-app@latest # install with yarn
pnpm dlx create-medusa-app@latest # install with pnpm
npx create-medusa-app@latest # install with npm
You can alternatively use the --use-npm, --use-yarn, or --use-pnpm options to specify the package manager to use.
Note: we recommend using yarn or pnpm to install dependencies. npm is known to be slower.
Filtering admin notifications
This release introduces a fixed filter, channel=feed, on notifications fetched for the notification drawer in Medusa Admin.
This was always intended to ensure we only show notifications that are purpose-built for the notification drawer. Other channel notifications will break the rendering of the drawer, since they don't have the required content format for the component.
https://github.com/medusajs/medusa/pull/14549
React Router upgrade
This release bumps react-router-dom from 6.20.1 to 6.30.3 to eliminate a security vulnerability. See advisory here.
If your project has react-router-dom installed explicitly, please upgrade to version 6.30.3.
Claude Code Plugins
We've published new Claude Code plugins to assist you in your development with Medusa. The medusa-dev plugin gives Claude the knowledge to help you in building customizations in your backend, admin, and storefront.
To install the plugin:
claude # start claude code
/plugin marketplace add medusajs/medusa-claude-plugins
/plugin install medusa-dev@medusa
Then, you can ask Claude Code to build Medusa features, fix bugs, and more. Claude Code will use the skills in the plugin to provide you with accurate and relevant Medusa code.
For example, you can run the following prompts to create a product reviews feature:
Implement a product reviews feature. Authenticated customers can add reviews. Admin users can view and approve or reject reviews from the dashboard
Features
feat(DML): Add a new translatable property modifier applicable on text by @adrien2p in https://github.com/medusajs/medusa/pull/14494
feat(deps,framework): add zod as framework dependency by @shahednasser in https://github.com/medusajs/medusa/pull/14441
feat(create-medusa-app): add support for pnpm and specifying package manager by @shahednasser in https://github.com/medusajs/medusa/pull/14443
feat(events): Implement default priority-based event processing by @adrien2p in https://github.com/medusajs/medusa/pull/14476
feat(config): Default event worker concurrency to 3 on cloud by @adrien2p in https://github.com/medusajs/medusa/pull/14477
feat(core-flows,types,utils,medusa): Translate tax lines by @NicolasGorga in https://github.com/medusajs/medusa/pull/14359
feat(medusa-cli): add codemod command + codemod for replacing zod imports by @shahednasser in https://github.com/medusajs/medusa/pull/14520
feat(translation,fulfillment,customer,product,region,tax,core-flows,medusa,types): Implement dynamic translation settings management by @NicolasGorga in https://github.com/medusajs/medusa/pull/14536
Feat(): improve module typings in medusa config and prepare event config typings by @adrien2p in https://github.com/medusajs/medusa/pull/14478
feat(medusa): Prevent build command from throwing on missing config by @adrien2p in https://github.com/medusajs/medusa/pull/14540
feat(core-flows): Allow payment session status captured to be processable upon cart completion by @NicolasGorga in https://github.com/medusajs/medusa/pull/14527
feat(create-medusa-app): add facts for Claude Code plugin and MCP server by @shahednasser in https://github.com/medusajs/medusa/pull/14578
feat(dashboard,translation,js-sdk,medusa,types): Translation settings management UI by @NicolasGorga in https://github.com/medusajs/medusa/pull/14541
Bugs
fix: Add schema only flag on Medusa app loader by @adrien2p in https://github.com/medusajs/medusa/pull/14502
fix(core-flows): Avoid throwing if no prices found for variant when adding to cart custom price item by @NicolasGorga in https://github.com/medusajs/medusa/pull/14528
fix(utils): fix import of caching and translation modules to be from @medusajs/medusa by @shahednasser in https://github.com/medusajs/medusa/pull/14519
fix(dashboard): filter feed channel notifications in admin dashboard by @NicolasGorga in https://github.com/medusajs/medusa/pull/14549
fix(core-flows): pass created_by to fulfillment input by @NicolasGorga in https://github.com/medusajs/medusa/pull/14561
fix: fix validation in posthog analytics identify by @peterlgh7 in https://github.com/medusajs/medusa/pull/14562
fix(core-flows): Prevent calling list methods unnecessarily in various update workflows by @NicolasGorga in https://github.com/medusajs/medusa/pull/14567
fix(docs): Remove spread operators and let mergeConfig handle merging by @NicolasGorga in https://github.com/medusajs/medusa/pull/14558
fix(create-medusa-app): fix error handling when thrown error is a string by @shahednasser in https://github.com/medusajs/medusa/pull/14555
fix(utils): support both path and parentPath in migration file by @riqwan in https://github.com/medusajs/medusa/pull/14576
fix(cli): show clear error when running outside a Medusa project by @shahednasser in https://github.com/medusajs/medusa/pull/14574
fix(order): call compensateRelationFieldsSelectionFromLoadStrategy when select-in strategy is configured in order repository list methods by @NicolasGorga in https://github.com/medusajs/medusa/pull/14566
fix(core-flows, types): improve product exports memory consumption by @NicolasGorga in https://github.com/medusajs/medusa/pull/14598
fix(core-flows, types): ensure promotion calculation context has required rules data by @fPolic in https://github.com/medusajs/medusa/pull/14597
fix(dashboard): translations settings ui styles alignment by @NicolasGorga in https://github.com/medusajs/medusa/pull/14601
fix(translation): recompute entity translations translated_field_count upon setting update by @NicolasGorga in https://github.com/medusajs/medusa/pull/14599
Documentation
chore(docs): Updated UI Reference (automated) by @github-actions[bot] in https://github.com/medusajs/medusa/pull/14507
docs: add npx2yarn component by @shahednasser in https://github.com/medusajs/medusa/pull/14512
Fix small typo in file name import by @Omar-Fetooh in https://github.com/medusajs/medusa/pull/14529
docs: paypal integration tutorial by @shahednasser in https://github.com/medusajs/medusa/pull/14253
docs: document incompatibility for Next.js storefront + Node v25 by @shahednasser in https://github.com/medusajs/medusa/pull/14538
docs: specify node.js version for Cloud projects by @shahednasser in https://github.com/medusajs/medusa/pull/14556
docs: fix digital products recipe duplicates bug by @shahednasser in https://github.com/medusajs/medusa/pull/14572
docs: add missing .yarn/releases in dockerfile by @shahednasser in https://github.com/medusajs/medusa/pull/14573
docs: fix links in pricing page by @shahednasser in https://github.com/medusajs/medusa/pull/14584
docs: add claude code plugins to docs by @shahednasser in https://github.com/medusajs/medusa/pull/14587
docs: add code to code block copy tracking by @shahednasser in https://github.com/medusajs/medusa/pull/14589
docs: improve sections in Index Module docs + fix supported storefront frameworks on Cloud by @shahednasser in https://github.com/medusajs/medusa/pull/14590
docs: use skills command for claude code plugin by @shahednasser in https://github.com/medusajs/medusa/pull/14594
docs: add release publish date to version by @shahednasser in https://github.com/medusajs/medusa/pull/14596
Chores
chore: add missing packages to eslint configurations by @shahednasser in https://github.com/medusajs/medusa/pull/14463
chore(docs): Update version in documentation (automated) by @github-actions[bot] in https://github.com/medusajs/medusa/pull/14505
chore(order): Add missing OrderItem GraphQL schema fields by @NicolasGorga in https://github.com/medusajs/medusa/pull/14459
chore: refactor graph query argument in a test by @fPolic in https://github.com/medusajs/medusa/pull/14513
chore(medusa): middleware policies by @carlos-r-l-rodrigues in https://github.com/medusajs/medusa/pull/14521
chore(core-flows): Emit cart updated event on deleteLineItemsWorkflow by @NicolasGorga in https://github.com/medusajs/medusa/pull/14466
chore: add claude skills for docs by @shahednasser in https://github.com/medusajs/medusa/pull/14533
chore: add to contributing guidelines overrides with pnpm by @shahednasser in https://github.com/medusajs/medusa/pull/14525
chore(dashboard): polish translations for refund reasons domain by @NicolasGorga in https://github.com/medusajs/medusa/pull/14560
chore: tsdoc updates for v2.13.0 by @shahednasser in https://github.com/medusajs/medusa/pull/14583
chore: bump RR minor version by @fPolic in https://github.com/medusajs/medusa/pull/14586
chore: reset event worker concurrency to 1 by @adrien2p in https://github.com/medusajs/medusa/pull/14595
Other Changes
Version Packages by @github-actions[bot] in https://github.com/medusajs/medusa/pull/14483
add cloud auto-login by @peterlgh7 in https://github.com/medusajs/medusa/pull/14488
feat(locales): add lt-LT to the default list of locales by @LukasKri in https://github.com/medusajs/medusa/pull/14518
feat: added mn-MN to the default list of locales by @erbold-bu in https://github.com/medusajs/medusa/pull/14487
docs: digital product media content binary -> base64 as of v2.11.0 by @420coupe in https://github.com/medusajs/medusa/pull/14497
Use ENTRYPOINT instead of CMD in Dockerfile by @nett00n in https://github.com/medusajs/medusa/pull/14553
Fix typo in returns and exchanges section by @haroldiedema in https://github.com/medusajs/medusa/pull/14329
chore: fix typos in comments by @NAM-MAN in https://github.com/medusajs/medusa/pull/14564
New Contributors
@LukasKri made their first contribution in https://github.com/medusajs/medusa/pull/14518
@erbold-bu made their first contribution in https://github.com/medusajs/medusa/pull/14487
@Omar-Fetooh made their first contribution in https://github.com/medusajs/medusa/pull/14529
@nett00n made their first contribution in https://github.com/medusajs/medusa/pull/14553
@haroldiedema made their first contribution in https://github.com/medusajs/medusa/pull/14329
@NAM-MAN made their first contribution in https://github.com/medusajs/medusa/pull/14564
Full Changelog: https://github.com/medusajs/medusa/compare/v2.12.5...v2.13.0