Svelte Commerce × Swell
Svelte Commerce on Swell
Solid core coverage: cart, checkout and sign-in are wired against Swell’s storefront API, authenticated with the store’s public key. Reviews, wishlist, vendors and states are the recorded gaps.
- 23/43 services wired
- @misiki/swell-connector 0.4.0
- Cart wired
- Checkout wired
- Sign-in (auth) wired
What works on Swell today
Cart, checkout and sign-in are wired; reviews, wishlist, vendors and states are not.
Cart
Wired: issues a real request to Swell.
Checkout
Wired: issues a real request to Swell.
Sign-in (auth)
Wired: issues a real request to Swell.
Known gaps: review, wishlist, vendor, state
23 of 43 services wired, read from CONNECTORS.md on ; npm may carry a newer patch. How coverage is measured.
What the connector calls on Swell
The connector calls Swell’s storefront (Frontend) REST API at https://{store}.swell.store/api for the shop, and reaches the Backend API at https://api.swell.store only from the server, with no /v1 prefix.
Storefront requests send Authorization: Basic with the base64 of the public key alone, and the shopper’s session, which is also the cart, travels in the X-Session header: the connector reads the rotated token from every response, replays it on every request with X-Locale and X-Currency, and keeps it in a swell-session cookie; there is no token refresh.
| Service | What it requests |
|---|---|
product | GET /api/products with page, limit, sort and search, and GET /api/products/{slug or id} with expand[0]=variants&expand[1]=categories |
category | GET /api/categories and GET /api/categories/{id}; a category’s products come from GET /api/products?categories= |
search | GET /api/products with search, plus two one-row GET /api/products queries sorted price asc and price desc for the price range facet |
cart | GET /api/cart, POST /api/cart/items, PUT and DELETE /api/cart/items/{id}, PUT /api/cart/coupon with code and DELETE /api/cart/coupon |
checkout | PUT /api/cart with billing: { method } (and shipping: { service } for the rate), then POST /api/cart/order |
payment-method | GET /api/settings/payments, which is also where the cash on delivery method id is looked up |
auth | POST /api/account/login with { email, password }, POST /api/account to register, GET /api/account and POST /api/account/logout |
address | GET /api/account/addresses, POST /api/account/addresses, and PUT and DELETE /api/account/addresses/{id} |
Swell rules the connector follows
- Swell reports some failures with HTTP 200, as
{ errors: { <field>: { code, message } } }or{ error }, so the connector checks every successful body for them, and a wrong password onPOST /account/logincomes back as 200 with a body ofnull. limitdefaults to 15 and is capped at 100 on the storefront API, so it is always sent, and totals come from thecount,limit,pageandpage_countof the list envelope.- Sorting is a
<field> asc|descpair limited todate_created,date_updated,price,name,skuandslug;popularityis not a product field and is dropped. - Variants are a child collection with no price or stock in the base product until
expandasks for them, andexpandis sent in array form (expand[0]=variants). - Swell has no PATCH verb and
PUTis a deep merge, so every update is aPUT, and no tag filter is sent, becausewhere[tags]works only on the Backend API.
Read from the source of misiki-in/swell-connector at commit ce0b4c8 of . Where the code has changed since, the code is right.
Quick start
From nothing to a Svelte Commerce storefront reading Swell. You need Node.js and a Swell to point it at; the storefront holds no data of its own.
Clone it, choose the connector, point it at Swell
# 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/swell-connector
# 3 — point it at your Swell store
echo PUBLIC_SWELL_API_URL=https://your-store.swell.store >> .env
echo PUBLIC_SWELL_API_KEY=pk_... >> .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_SWELL_API_URL | Yes | Your storefront origin, such as https://<store>.swell.store. Boot fails, naming this variable, if it is missing. |
PUBLIC_SWELL_API_KEY | No | The store’s public key, sent on its own as HTTP Basic to the storefront API. |
PUBLIC_SWELL_STORE_ID | No | The store ID. With the secret key it authenticates Swell’s Backend API, which the connector refuses to call from a browser. |
PUBLIC_SWELL_API_SECRET | No | The secret key, for Backend API calls. See the limitations before setting it. |
PUBLIC_CONNECTOR | No | Only when more than one connector is installed: @misiki/swell-connector names the one this build runs on. |
init.ts hands the connector every PUBLIC_SWELL_* variable that is set, camel-cased. The guide also lists PUBLIC_SWELL_ACCESS_TOKEN, PUBLIC_SWELL_ACCESS_KEY and PUBLIC_SWELL_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 Swell
- For cash on delivery, add a manual payment method named
codin Swell’s payment settings; without one, the storefront’s cash-on-delivery option is refused.
How the integration works
Swell has two APIs. The storefront API takes the public key alone as HTTP Basic, and it is the one the storefront calls. The Backend API takes the store ID and secret key, and the connector refuses to call it from a browser.
Limitations on Swell
- Setting
PUBLIC_SWELL_API_SECRETwould put Swell’s secret key in every visitor’s browser: SvelteKit sendsPUBLIC_variables to the browser, even though the connector only calls the Backend API from the server.
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 Swell
Can I run a Swell store on Svelte Commerce today?
Cart, checkout and sign-in are wired; reviews, wishlist, vendors and states are not. Like every connector, it has not been run against a live production Swell store.
How do I switch Svelte Commerce to Swell?
Remove the connectors the storefront ships with, install @misiki/swell-connector, set PUBLIC_SWELL_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 Swell keys does the storefront need?
The public key, for the storefront API. The secret key is for Swell’s Backend API, which the connector will not call from a browser — and because every PUBLIC_ variable reaches the browser, it is better left unset.
Sources
SWELL.md, read on ; CONNECTORS.md, read on ; the connector’s source at ce0b4c8. Where they disagree with this page, they are right. Swell is a trademark of its owner, named only to describe compatibility; see trademarks.