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

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

**Full Changelog**: https://github.com/mercurjs/mercur/compare/v2.1.6...2.2.0