Svelte Commerce × Medusa

Svelte Commerce on Medusa

The Medusa connector reaches Medusa’s Store API with a publishable key and a region. Its guide describes cart, checkout and sign-in as Medusa-native, but the coverage script does not count cart or sign-in as wired — and until that is settled, it cannot sell.

31/43 services wired
@misiki/medusa-connector 2.1.5
Cart not yet wired
Checkout wired
Sign-in (auth) not yet wired

What works on Medusa today

Cannot sell yet. The coverage script counts cart and sign-in — and products, categories and search — as not wired, and CONNECTORS.md says this connector predates the current wiring pass and has not had the source-verification sweep the others have. Even by its own guide, only cash on delivery completes: the card gateways are not wired to Medusa.

Cart

Not yet wired, by the coverage script’s measure.

Checkout

Wired: issues a real request to Medusa.

Sign-in (auth)

Not yet wired, by the coverage script’s measure.

Known gaps: auth, cart, product, category, search, address, user, payment-method

31 of 43 services wired, read from CONNECTORS.md on 21 September 2026; npm may carry a newer patch. How coverage is measured.

What the connector calls on Medusa

The connector calls Medusa’s Store API through the official Medusa JS SDK (@medusajs/js-sdk 2.18.0), using its store.* methods rather than hand-built paths.

Each call builds a fresh SDK client with baseUrl and the publishable API key, and hands it a bearer token only when localStorage holds medusa_auth_token.

Requests the @misiki/medusa-connector source makes, by storefront service
Service	What it requests
`checkout`	Cash on delivery runs `store.cart.retrieve`, then `store.payment.initiatePaymentSession` with provider `pp_system_default`, then `store.cart.complete`
`checkout`	Shipping rates come from `store.fulfillment.listCartOptions` with `cart_id`
`order`	`store.order.list` with `limit` 10, an `offset` and `fields: 'items,shipping_address,*billing_address'`
`order`	`store.order.retrieve(id)` with the same `fields` expansion

Medusa rules the connector follows

An order is placed only when store.cart.complete answers with type: 'order'; any other answer is raised as a checkout error.
After an order is placed the connector removes cart_id from localStorage, so the next add to cart starts a new cart.
Order lists page by limit and offset, and the line items and both addresses are requested through the fields parameter.
Any path the connector inherits under /api/ is answered inside the connector and never sent to a server: a list resolves empty, and a single record throws “This item is not available on this store (medusa).”

Read from the source of misiki-in/medusa-connector at commit 5c4d27a of 25 August 2026. Where the code has changed since, the code is right.

Quick start

From nothing to a Svelte Commerce storefront reading Medusa. You need Node.js and a Medusa to point it at; the storefront holds no data of its own.

Clone it, choose the connector, point it at Medusa

# 1 — get the storefront
git clone https://github.com/itswadesh/svelte-commerce
cd svelte-commerce

# 2 — one connector at a time: remove the two the storefront ships with, add this one
npm uninstall @misiki/litekart-connector @misiki/vendure-connector
npm i @misiki/medusa-connector

# 3 — point it at your Medusa server
echo PUBLIC_MEDUSA_API_URL=http://localhost:9000 >> .env
echo PUBLIC_MEDUSA_PUBLISHABLE_API_KEY=pk_... >> .env
echo PUBLIC_MEDUSA_REGION_ID=reg_... >> .env

# 4 — run it
npm run dev

Switching works the same way on every backend: what all 26 share, from one connector at a time to store identity.

Environment variables

What Svelte Commerce reads to reach Medusa
Variable	Required	What it does
`PUBLIC_MEDUSA_API_URL`	Yes	Base URL of the Medusa server’s Store API.
`PUBLIC_MEDUSA_PUBLISHABLE_API_KEY`	Yes	A publishable API key created in the Medusa admin. Publishable keys are meant to be used from a browser.
`PUBLIC_MEDUSA_REGION_ID`	Yes	The region ID (`reg_…`) used for pricing, currency and availability.
`PUBLIC_CONNECTOR`	No	Only when more than one connector is installed: `@misiki/medusa-connector` names the one this build runs on.

Boot checks only PUBLIC_MEDUSA_API_URL, but the guide marks all three as required. The Litekart trio is not used in Medusa mode.

Every variable here begins PUBLIC_, and SvelteKit sends PUBLIC_ variables to the browser: treat each value you set as published.

What to set up on Medusa

Create a publishable API key in the Medusa admin and set it as PUBLIC_MEDUSA_PUBLISHABLE_API_KEY.
Add the storefront’s origin to Medusa’s Store CORS configuration.

How the integration works

At boot, init in both hooks (through src/lib/core/connectors/init.ts) writes the three PUBLIC_MEDUSA_* values onto the connector’s BaseService — BASE_URL, PUBLISHABLE_KEY and REGION_ID. The server hook covers server rendering; the client hook covers the browser, which must reach the public Medusa URL in production.

By the guide’s account, cart, shipping rates and payment-method listing are Medusa-native; sign-in, sign-up, sign-out and password reset go through the Medusa SDK; categories map to Medusa product categories; and the profile page delegates to Medusa’s getMe and updateProfile. Medusa needs an email on the cart to complete an order, so the static store config defaults isEmailMandatory to true.

Store identity, menus and plugin toggles are static — default-store.json under the default export of kitcommerce.config.ts — and CMS pages and the blog resolve empty. From connector 2.1.6 the REST paths it once inherited from Litekart are answered by the connector itself.

The coverage script and the guide disagree. The script counts a service as wired only if it reaches the connector’s own HTTP layer, and it does not count cart, auth, product, category, search, address, user or payment-method. CONNECTORS.md names Medusa and Saleor as the next candidates for the source-verification sweep.

Limitations on Medusa

Sign-in (auth): not wired — the coverage script does not count it, though the guide describes email sign-in as native.
Cart: not wired — the coverage script does not count it, though the guide describes the cart as Medusa-native.
The card gateways in this connector — Razorpay, Stripe, PhonePe, PayPal, Cashfree, Affirm — still call Litekart’s /api/checkout/* routes, which the connector answers locally with an empty result, so they do not work. Only cash on delivery completes through Medusa.
OTP sign-in is a mock: getOtp reports success without sending anything.
Legal and CMS pages render their layout with empty content; the wishlist and the cart’s coupon drawer show empty states.
The Conversational Shopping assistant is Litekart-only; its widget stays hidden in Medusa mode without firing requests.

Troubleshooting Medusa

Errors particular to Svelte Commerce on Medusa, and what fixes them
When you see	What to do
Boot fails with “PUBLIC_MEDUSA_API_URL is set, but it configures a different backend than the one this build runs on”	The variable is set while a different connector is installed. Install `@misiki/medusa-connector`, or remove the variable if you meant to run another backend. With more than one connector installed, set `PUBLIC_CONNECTOR='@misiki/medusa-connector'`.
Sign-in or cart works in dev but not when deployed	Check the publishable API key, and that the deployed storefront’s origin is in Medusa’s Store CORS configuration.

Before you rely on it

No connector has been exercised against a live production instance of its platform; each was written from the platform’s published source. The limits every backend shares and the errors every switch can meet are on the backends page.

Offer a sandbox or a correction

FAQ

Questions about Svelte Commerce on Medusa

Can I sell on Medusa with Svelte Commerce today?

Not yet. The coverage script counts the cart and sign-in as not wired, and CONNECTORS.md says the Medusa connector predates the current wiring pass. By its own guide, only cash on delivery completes; the card gateways are not wired to Medusa.

Why does the guide say the cart works when the coverage table says it does not?

They measure different things. The guide describes what the connector calls; the coverage script counts a service only when it reaches the connector’s own HTTP layer, and does not count cart, auth, products, categories or search. CONNECTORS.md lists Medusa as a next candidate for the source-verification sweep that would settle it.

What does Medusa need configured for Svelte Commerce?

A publishable API key created in the Medusa admin, a region ID for pricing and currency, and the storefront’s origin in Medusa’s Store CORS configuration.

Which payment methods work with Medusa?

Cash on delivery completes through the Medusa SDK. The card gateways in this connector — Razorpay, Stripe, PhonePe, PayPal, Cashfree, Affirm — are not wired to Medusa and do not work.

Sources

MEDUSA.md, read on 25 September 2026; CONNECTORS.md, read on 21 September 2026; the connector’s source at 5c4d27a. Where they disagree with this page, they are right. Medusa is a trademark of its owner, named only to describe compatibility; see trademarks.

Read the whole guide

The Medusa guide on GitHub All 26 backends KitCommerce vs Medusa