v2.2.0

🚀 Mercur 2.2.0

2.2.0 is here — our biggest release since 2.1.6 (80+ merged PRs). It brings a rebuilt attributes system, first-class AI-agent tooling, a full panel extension API, and a revamped docs experience.

📚 Docs: https://docs.mercurjs.com

🧪 Get started

bunx create-mercur-app

---

✨ Highlights

🛍️ Offers

• Store-facing offer discovery via the Store API (GET /store/offers).
• Admin offers now grouped per seller with variant counts for a clearer catalog view.

🏷️ Attributes, rebuilt (⚠️ breaking)

• Product attributes are now built on Medusa's native product options instead of a bespoke layer.
• Polished, streamlined product create flow.

🤖 Built for AI agents

• Version-matched docs ship inside your project at node_modules/@mercurjs/docs/ — always in sync with your installed version.
• AGENTS.md / CLAUDE.md scaffolding generated with every new project.
• MCP server at docs.mercurjs.com/mcp for live doc search in your editor.

🧩 Panel extension API

• Widgets, navigation, and custom-field extension zones across both Admin and Vendor dashboards.
• Seller form and display extension fields, additional_data threaded through vendor & admin routes.

📦 create-mercur-app

• Now a standalone package for faster, prompt-free scaffolding.
• Upgraded to Medusa 2.17.2 with full dashboard i18n and a seeded demo seller.

---

⚠️ Breaking changes

• Master products + offers on the Store API. Products in the /store catalog are now shared master products (not seller-owned), and what a seller actually sells is an offer. Storefronts must fetch offers via GET /store/offers, read pricing/inventory from the offer (offer.product_id, per-offer calculated_price), and add cart line items by offer ID rather than variant ID. Storefronts built against the old seller-owned product model need to migrate.
• Attributes are now backed by Medusa's native product options — projects with custom attribute logic will need to migrate. (#1165)

---

What's Changed

• chore(deps): bump i18next-http-backend from 2.4.2 to 3.0.5 in /packages/admin by @dependabot[bot] in #916
• chore(deps): bump i18next-http-backend from 2.4.2 to 3.0.5 in /packages/dashboard-shared by @dependabot[bot] in #921
• docs: link release notes button to all releases by @vholik in #1097
• release: promote canary to main by @vholik in #1140
• fix(pages): remove symlink that breaks the registry Pages deploy by @vholik in #1155
• Release canary to main by @vholik in #1158
• chore: remove e2e-tests and playwright-skill; fix main Pages deploy by @vholik in #1160
• chore(ci): bump actions/checkout from 4 to 7 by @dependabot[bot] in #1141
• chore(ci): bump actions/cache from 4 to 6 by @dependabot[bot] in #1142
• chore(ci): bump actions/setup-node from 4 to 6 by @dependabot[bot] in #1143
• chore(deps): bump @types/react from 18.3.31 to 19.2.17 by @dependabot[bot] in #1144
• chore(deps): bump copy-to-clipboard from 3.3.3 to 4.0.2 by @dependabot[bot] in #1145
• chore(deps): bump tailwindcss from 3.4.19 to 4.3.2 by @dependabot[bot] in #1146
• chore(deps): bump vite from 5.4.21 to 8.1.3 by @dependabot[bot] in #1147
• chore(deps): bump @eslint/js from 9.39.4 to 10.0.1 by @dependabot[bot] in #1148
• chore(deps): bump jest from 29.7.0 to 30.4.2 by @dependabot[bot] in #1150
• chore(deps): bump zod from 3.25.76 to 4.4.3 by @dependabot[bot] in #1151
• chore(deps): bump @types/node from 20.19.43 to 26.1.0 by @dependabot[bot] in #1152
• chore(deps): bump radix-ui from 1.1.2 to 1.6.1 by @dependabot[bot] in #1153
• chore(deps): bump http-proxy-middleware from 3.0.5 to 3.0.7 in /templates/basic/packages/api by @dependabot[bot] in #1159
• chore(ci): harden workflow token permissions by @vholik in #1161
• fix(ci): deploy registry schemas via slim Pages artifact by @vholik in #1162
• fix(ci): tolerate transient Pages deploy status errors by @vholik in #1163
• feat(dashboard): panel extension API — widgets, navigation, custom fields (SPEC-021) by @vholik in #1165
• feat(core): thread additional_data through vendor & admin routes by @vholik in #1166
• feat(dashboard): panel extension coverage across admin & vendor by @vholik in #1167
• feat(dashboard): seller form extension zones across admin & vendor by @vholik in #1168
• feat(dashboard): widget extension zones across admin & vendor pages by @vholik in #1169
• fix(vendor): wire seller status & general zone through display extension fields by @vholik in #1170
• fix(dashboard): consistent spacing for form extension zone fields by @vholik in #1174
• docs: PRs target main instead of canary by @vholik in #1175
• docs: linear-task skill targets main instead of canary by @vholik in #1176
• fix(panels): merge custom-field link relations into entity fetches by @vholik in #1183
• fix(admin): correct customer address validation and success toasts by @vholik in #1182
• fix(admin): consistent collection create/update/delete toasts by @vholik in #1179
• fix(admin): default title sort on collection products table by @vholik in #1180
• fix(admin): validate title on edit collection form by @vholik in #1178
• feat(admin): add title validation to create collection form by @vholik in #1177
• fix(admin): customer address edit validations and stale name by @vholik in #1184
• feat(admin): add bottom action bar to category ranking editor by @vholik in #1181
• fix(product): enforce single category per product on assignment by @vholik in #1185
• feat(dashboard): wire custom-field links and explicit fields on store/product/order pages by @vholik in #1186
• feat(vendor): fetch seller custom-field links in onboarding wizard by @vholik in #1187
• fix(dashboard): unwrap zod wrappers when picking custom-field input control by @vholik in #1188
• fix(admin): align category toast messages with product copy by @vholik in #1190
• fix(admin): match collection products empty state to design by @vholik in #1189
• chore: update dev ports for admin and vendor panels by @vholik in #1192
• fix(admin): align product request modals with design by @vholik in #1191
• feat(vendor): use a single illustration for login and onboarding by @vholik in #1194
• fix(dashboard): scope custom-field validation to the form's zone by @vholik in #1195
• fix(vendor): validate tab-scoped custom fields in the onboarding wizard by @vholik in #1196
• fix(dashboard): polish create-product attribute modal and draft button by @vholik in #1193
• fix(vendor): resolve create-return issues on the order return form by @vholik in #1197
• fix(vendor): align order refund UI with design by @vholik in #1198
• refactor(vendor): deliver order outstanding-payment link as a widget by @vholik in #1199
• fix(vendor): refine create-fulfillment error messages by @vholik in #1201
• fix(orders): reserve order-edit offer items at a stocked location (MER-211) by @vholik in #1200
• docs: sync PRODUCT and ARCHITECTURE with RC feature set by @vholik in #1214
• docs: best practices guide for developing with Mercur by @vholik in #1215
• chore(ci): bump actions/upload-pages-artifact from 3 to 5 by @dependabot[bot] in #1203
• chore(deps): bump eslint from 9.39.4 to 10.6.0 by @dependabot[bot] in #1204
• chore(deps): bump @vitejs/plugin-react from 4.7.0 to 6.0.3 by @dependabot[bot] in #1205
• chore(deps): bump react-i18next from 13.5.0 to 17.0.8 by @dependabot[bot] in #1206
• chore(deps): bump meilisearch from 0.47.0 to 0.59.0 by @dependabot[bot] in #1208
• chore(deps): bump ts-morph from 27.0.2 to 28.0.0 by @dependabot[bot] in #1209
• chore(deps): bump @radix-ui/react-dialog from 1.1.4 to 1.1.19 by @dependabot[bot] in #1211
• chore(deps): bump commander from 14.0.3 to 15.0.0 by @dependabot[bot] in #1212
• chore(deps): bump i18next from 23.7.11 to 26.3.5 by @dependabot[bot] in #1207
• chore(deps): bump typescript from 5.9.3 to 7.0.2 by @dependabot[bot] in #1210
• fix(profile): load custom-field link data on profile pages by @vholik in #1216
• fix(panels): merge custom-field link relations + consolidate onto useLinkQuery by @vholik in #1217
• chore(deps): roll back typescript to 5.9.3 by @vholik in #1219
• chore(deps): bump react-router-dom from 6.30.3 to 7.18.1 by @dependabot[bot] in #1213
• chore(core)!: remove the search module and store search endpoint by @vholik in #1220
• feat(vendor): register link on login gated by feature flag + auth language switcher by @vholik in #1221
• fix(panels): respect base path on session-expiry login redirect by @vholik in #1223
• feat(template): seed a demo seller with products and offers by @vholik in #1225
• chore(i18n): backfill missing admin & vendor translations by @vholik in #1226
• fix(dashboard): route hardcoded panel strings through i18n by @vholik in #1227
• chore(create-app): default to basic template without prompting by @vholik in #1228
• fix(create-mercur-app): always pull template from main branch by @vholik in #1229
• fix(vendor): replace removed react-router json helper and guard optimizeDeps by @vholik in #1230
• fix(vendor): update auth footer strings on language switch by @vholik in #1231
• docs: promote 2.2.0 to stable and retire 2.1.x by @vholik in #1232

Full Changelog: v2.1.6...2.2.0