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
zodimports 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:
npx medusa codemod replace-zod-imports
https://github.com/medusajs/medusa/pull/14441 https://github.com/medusajs/medusa/pull/14520
Improved Translations
Translation Settings Management UI
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
entitiesoption from the translation module inmedusa-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.
Translations is still an experimental feature. Enable it in your project by following the guide in our documentation.
https://github.com/medusajs/medusa/pull/14494 https://github.com/medusajs/medusa/pull/14541
Priority-based event processing
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
yarnorpnpmto install dependencies.npmis 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
compensateRelationFieldsSelectionFromLoadStrategywhenselect-instrategy 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
deleteLineItemsWorkflowby @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