Svelte Commerce × X-Cart
Svelte Commerce on X-Cart
Solid core coverage: cart, checkout and sign-in are wired against X-Cart’s modern API, and the one recorded gap is vendors. Every call carries the store’s API key; a shopper’s token joins it after sign-in.
- 26/43 services wired
- @misiki/x-cart-connector 0.5.0
- Cart wired
- Checkout wired
- Sign-in (auth) wired
What works on X-Cart today
Cart, checkout and sign-in are wired; vendors are the one recorded gap. Cart and checkout need X-Cart’s read/write API key, and the connector takes it from a PUBLIC_ variable, which the browser receives.
Cart
Wired: issues a real request to X-Cart.
Checkout
Wired: issues a real request to X-Cart.
Sign-in (auth)
Wired: issues a real request to X-Cart.
Known gaps: vendor
26 of 43 services wired, read from CONNECTORS.md on ; npm may carry a newer patch. How coverage is measured.
What the connector calls on X-Cart
The connector calls X-Cart’s Storefront API, a REST API in Hydra JSON-LD under /api/storefront, and reaches the admin API under /api only to read the signed-in customer’s orders.
Every call carries the store API key as X-Auth-Token; a shopper signs in with POST /api/storefront/auth/login, whose JWT goes out as Authorization: Bearer, and on a 401 the connector tries POST /auth/refresh once, which works only when a refresh token was captured, because the login response returns the refresh token as a server cookie.
| Service | What it requests |
|---|---|
product | GET /api/storefront/products/compact with page, itemsPerPage, filter.substring, filter.categories, filter.bestsellers and order_by.<field>; a product page uses GET /products/detailed/by_clean_url/{clean_url} or GET /products/detailed/{id} |
category | GET /api/storefront/categories/compact with filter.parent and order_by.pos |
cart | POST /api/storefront/carts creates the cart; then GET /carts/{uuid}, POST /carts/{uuid}/items, PATCH and DELETE /carts/{uuid}/items/{id}, POST /carts/{uuid}/coupons and POST /carts/{uuid}/calculate |
checkout | GET /carts/{uuid}/payment_methods, POST /carts/{uuid}/select_payment_method, PATCH /carts/{uuid}/payment/{id} with action: init (then pay), and POST /carts/{uuid}/order |
order | GET /api/orders on the admin API with profile.login set to the e-mail from GET /api/storefront/auth/whoami |
auth | POST /auth/login, then GET /users/self and GET /auth/whoami; POST /users to register, POST /auth/reset_password, POST /auth/logout |
address | GET, POST, PATCH and DELETE on /api/storefront/users/self/addresses, with the field list from GET /address_fields |
payment-method | GET /api/storefront/carts/{uuid}/payment_methods; X-Cart has no store-wide payment-method list |
X-Cart rules the connector follows
- Requests send
Accept: application/ld+jsonbecause only that type returns collections in the Hydra envelope withhydra:totalItems, and withapplication/jsonX-Cart answers with a bare array and no total. - Filters and sorting are flat parameters,
filter.<field>andorder_by.<field>=asc|desc, and products sort only by name, price,arrivalDateand sales, so any other sort is left off. - The cart is a UUID returned by
POST /cartsand replayed in every/carts/{uuid}/...path; the connector keeps it in anxc-cartcookie, the name X-Cart’s own storefront uses, and on sign-in merges the anonymous cart into the account withPOST /carts/{uuid}/merge. - The admin
/api/orderscollection covers every customer, so the connector always sendsprofile.loginwith the signed-in shopper’s e-mail, then drops any returned row whose e-mail does not match, in case the store ignores the filter. - Payment runs on the cart’s payment transaction with
PATCH /carts/{uuid}/payment/{id}, and whenaction: initreturns a hosted-gateway URL the connector sends the shopper there and places no order until they return.
Read from the source of misiki-in/x-cart-connector at commit 06b7c22 of . Where the code has changed since, the code is right.
Quick start
From nothing to a Svelte Commerce storefront reading X-Cart. You need Node.js and a X-Cart to point it at; the storefront holds no data of its own.
Clone it, choose the connector, point it at X-Cart
# 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/x-cart-connector
# 3 — point it at your X-Cart store
echo PUBLIC_X_CART_API_URL=https://your-store.example.com >> .env
echo PUBLIC_X_CART_API_KEY=... >> .env
# 4 — run it
npm run devSwitching works the same way on every backend: what all 26 share, from one connector at a time to store identity.
Environment variables
| Variable | Required | What it does |
|---|---|---|
PUBLIC_X_CART_API_URL | Yes | Your X-Cart store’s URL. Boot fails, naming this variable, if it is missing. |
PUBLIC_X_CART_API_KEY | No | The store API key from X-Cart’s Settings › API, sent as X-Auth-Token on every call. A read-only key rejects writes, so cart and checkout need the read/write key. See the limitations. |
PUBLIC_X_CART_ACCESS_TOKEN | No | Sent as a bearer token when set; a shopper’s token after sign-in travels the same way. |
PUBLIC_CONNECTOR | No | Only when more than one connector is installed: @misiki/x-cart-connector names the one this build runs on. |
init.ts hands the connector every PUBLIC_X_CART_* variable that is set, camel-cased. The guide also lists PUBLIC_X_CART_API_SECRET, PUBLIC_X_CART_ACCESS_KEY, PUBLIC_X_CART_STORE_ID and PUBLIC_X_CART_CHANNEL_ID; the connector’s source does not read them.
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 X-Cart
- Run X-Cart 5.5.1 or later. The connector follows the modern API; the
_keyquery parameter of the 5.3/5.4 admin API does not exist there and is not used. - Create the API key under Settings › API — the read/write one, because a read-only key rejects every cart and checkout write.
How the integration works
X-Cart 5.5.1 and later want two headers: X-Auth-Token, the store API key, on every call, and Authorization: Bearer, the shopper’s token, once they have signed in. A read-only key is enough to browse but rejects every POST, PATCH and DELETE.
Limitations on X-Cart
- The store API key, sent as
X-Auth-Token, comes fromPUBLIC_X_CART_API_KEY— and cart and checkout need the read/write key. SvelteKit sendsPUBLIC_variables to the browser, so every visitor to the store can read it.
Troubleshooting X-Cart
| When you see | What to do |
|---|---|
| Boot fails with “the x-cart connector is active but PUBLIC_X_CART_API_URL is not set” | Add PUBLIC_X_CART_API_URL to .env. A production Node build and Docker read PUBLIC_* from the process environment rather than .env, so set it on your deploy platform too. |
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 correctionFAQ
Questions about Svelte Commerce on X-Cart
Can I run an X-Cart store on Svelte Commerce today?
Cart, checkout and sign-in are wired, and vendors are the only recorded gap. The obstacle is the key: cart and checkout need X-Cart’s read/write API key, which the connector reads from a PUBLIC_ variable that every visitor’s browser receives.
How do I switch Svelte Commerce to X-Cart?
Remove the connectors the storefront ships with, install @misiki/x-cart-connector, set PUBLIC_X_CART_API_URL in .env and start the dev server. vite.config.ts resolves whichever connector is installed, so no file in the storefront changes.
Which X-Cart versions and keys does the connector need?
X-Cart 5.5.1 or later, and the read/write store API key from Settings › API, sent as X-Auth-Token. A read-only key can browse but rejects cart and checkout writes.
Sources
X-CART.md, read on ; CONNECTORS.md, read on ; the connector’s source at 06b7c22. Where they disagree with this page, they are right. X-Cart is a trademark of its owner, named only to describe compatibility; see trademarks.