Svelte Commerce × Spree
Svelte Commerce on Spree
Spree’s storefront API speaks JSON:API, so the connector ships a deserialiser that resolves included relationships. Cart, checkout and sign-in are wired; reviews are the one recorded gap.
- 26/43 services wired
- @misiki/spree-connector 0.4.0
- Cart wired
- Checkout wired
- Sign-in (auth) wired
What works on Spree today
Cart, checkout and sign-in are wired; reviews are the one recorded gap.
Cart
Wired: issues a real request to Spree.
Checkout
Wired: issues a real request to Spree.
Sign-in (auth)
Wired: issues a real request to Spree.
Known gaps: review
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 Spree
The connector calls Spree’s Storefront API v2, a JSON:API surface under /api/v2/storefront, with Doorkeeper’s token routes at /spree_oauth/token and /spree_oauth/revoke; its source notes that v2 is deprecated upstream and targets Spree 4.x and 5.x stores that still serve it.
A shopper signs in with a Doorkeeper password grant to POST /spree_oauth/token, and the access token is then sent as Authorization: Bearer <token> and renewed once from the refresh token when a call answers 401; a guest cart is identified by X-Spree-Order-Token, read from the cart body’s data.attributes.token and kept in localStorage and a cookie under spree_order_token.
| Service | What it requests |
|---|---|
product | GET /api/v2/storefront/products with filter[...], sort, page, per_page and include=images,default_variant, and GET /api/v2/storefront/products/{slug} with the variants, option types and images included |
category | GET /api/v2/storefront/taxons with include=image, and GET /api/v2/storefront/taxons/{id or permalink} |
search | GET /api/v2/storefront/products with filter[name], filter[taxons], filter[price]=min,max, filter[options][<name>] and filter[properties][<name>] |
cart | POST /api/v2/storefront/cart, GET /api/v2/storefront/cart, POST /cart/add_item with variant_id, PATCH /cart/set_quantity, DELETE /cart/remove_line_item/{id} and PATCH /cart/apply_coupon_code |
checkout | PATCH /api/v2/storefront/checkout with the order addresses, GET /checkout/shipping_rates, POST /checkout/create_payment with payment_method_id, then PATCH /checkout/advance and PATCH /checkout/complete |
payment-method | GET /api/v2/storefront/checkout/payment_methods |
auth | POST /spree_oauth/token (grant_type: password), POST /api/v2/storefront/account, GET /api/v2/storefront/account, PATCH /cart/associate?guest_order_token= after sign-in and POST /spree_oauth/revoke on sign-out |
order | GET /api/v2/storefront/account/orders and /account/orders/{number} for a signed-in shopper, GET /order_status/{number} with the order token otherwise |
Spree rules the connector follows
- Without an explicit
include, Spree returns no images and no variants, only bare{ id, type }pointers, so every product, cart and order request names the relationships it needs. - Filters are nested query parameters, such as
filter[options][color]=red, and ranges or lists are one comma-separated value, such asfilter[price]=10,100. sortis one signed token from a fixed list (name,price,available_on,created_at,updated_at,sku); anything else is dropped, andGET /taxonstakes no sort and comes back in tree order.filter[taxons]takes ids, so a category permalink is first resolved throughGET /taxons/{permalink}.- Totals come from the JSON:API
meta.total_countandmeta.total_pages, not from headers, and there is noGET /cart/{id}, so the order token sent as a header is the only way to address a guest cart.
Read from the source of misiki-in/spree-connector at commit 9c050b3 of . Where the code has changed since, the code is right.
Quick start
From nothing to a Svelte Commerce storefront reading Spree. You need Node.js and a Spree to point it at; the storefront holds no data of its own.
Clone it, choose the connector, point it at Spree
# 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/spree-connector
# 3 — point it at your Spree store
echo PUBLIC_SPREE_API_URL=https://your-store.example.com >> .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_SPREE_API_URL | Yes | Your Spree store’s URL. Boot fails, naming this variable, if it is missing. |
PUBLIC_SPREE_ACCESS_TOKEN | No | Sent as a bearer token when set. |
PUBLIC_CONNECTOR | No | Only when more than one connector is installed: @misiki/spree-connector names the one this build runs on. |
init.ts hands the connector every PUBLIC_SPREE_* variable that is set, camel-cased. The guide also lists PUBLIC_SPREE_API_KEY, PUBLIC_SPREE_API_SECRET, PUBLIC_SPREE_ACCESS_KEY, PUBLIC_SPREE_STORE_ID and PUBLIC_SPREE_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.
How the integration works
Spree answers in JSON:API, with related records in an included array; the connector’s deserialiser stitches them back together. (The jsonapi file in its source is that helper, not a service.) The API documentation URL its authors were given was dead, so it was written from Spree’s own source instead.
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 Spree
Can I run a Spree store on Svelte Commerce today?
Cart, checkout and sign-in are wired, and reviews are the only recorded gap. Like every connector, it has not been run against a live production Spree store.
How do I switch Svelte Commerce to Spree?
Remove the connectors the storefront ships with, install @misiki/spree-connector, set PUBLIC_SPREE_API_URL in .env and start the dev server. vite.config.ts resolves whichever connector is installed, so no file in the storefront changes.
How was the Spree connector written?
From Spree’s own source. The API documentation URL the authors were given was dead, so they read the code instead, and handle Spree’s JSON:API responses with a deserialiser that resolves the included relationships.
Sources
SPREE.md, read on ; CONNECTORS.md, read on ; the connector’s source at 9c050b3. Where they disagree with this page, they are right. Spree is a trademark of its owner, named only to describe compatibility; see trademarks.