Svelte Commerce × commercetools
Svelte Commerce on commercetools
The commercetools connector models version-based optimistic concurrency — { version, actions: [] } — throughout, and is wired against the /me endpoints so nothing runs unscoped. Cart, checkout and sign-in are wired.
- 21/43 services wired
- @misiki/commercetools-connector 0.5.0
- Cart wired
- Checkout wired
- Sign-in (auth) wired
What works on commercetools today
Cart, checkout and sign-in are wired, all through the /me endpoints; countries, currencies, CMS pages and vendors are not.
Cart
Wired: issues a real request to commercetools.
Checkout
Wired: issues a real request to commercetools.
Sign-in (auth)
Wired: issues a real request to commercetools.
Known gaps: country, currency, page, vendor
21 of 43 services wired, read from CONNECTORS.md on ; npm may carry a newer patch. How coverage is measured.
What the connector calls on commercetools
The connector calls the commercetools Composable Commerce HTTP API, a JSON REST API whose paths are relative to the project-scoped root https://api.{region}.commercetools.com/{projectKey}, with tokens requested from a second host, https://auth.{region}.commercetools.com.
Every API call carries Authorization: Bearer; a guest gets an anonymous-session token from /oauth/{projectKey}/anonymous/token with an anonymous_id the connector generates, a shopper who signs in gets a password-flow token from /oauth/{projectKey}/customers/token, and the token, refresh token and scope are kept in localStorage under ct_session so a reload keeps the same identity; logout is local only, because commercetools has no revocation endpoint.
| Service | What it requests |
|---|---|
product | GET /product-projections with limit, offset, sort, priceCurrency and storeProjection; GET /product-projections/key={key} and /product-projections/{id}; GET /product-projections/search with text.{locale} and fuzzy=true for a text query |
category | GET /categories with where=slug(en="..."), falling back to GET /categories/key={key} and /categories/{id}; the whole tree with limit=500 |
search | GET /product-projections/search with filter.query=categories.id:subtree("{id}"), a variants.price.centAmount:range (...) filter in minor units, and facet=categories.id |
cart | GET /me/active-cart, POST /me/carts to create, GET /me/carts/{id}, and POST /me/carts/{id} with { version, actions }, each with expand=discountCodes[*].discountCode and paymentInfo.payments[*] |
checkout | GET /shipping-methods/matching-cart?cartId=, POST /me/payments with amountPlanned and paymentMethodInfo.method, an addPayment action on the cart, then POST /me/orders with { id, version } |
order | GET /me/orders with where, limit, offset and sort=createdAt desc, and GET /me/orders/{id} |
auth | POST /me/login with activeCartSignInMode: 'MergeWithExistingCustomerCart', POST /me/signup, GET /me, POST /customers/password-token and POST /customers/password/reset |
address | GET /me, then POST /me with addAddress, changeAddress, removeAddress, setDefaultShippingAddress or setDefaultBillingAddress update actions |
commercetools rules the connector follows
- When an update returns 409
ConcurrentModification, the connector readscurrentVersionfrom the error, or fetches the resource once, and replays the same actions exactly once; a second conflict goes back to the caller. - Localised fields cannot be compared directly, so the connector writes predicates as
slug(en="x")and sorts asname.en asc, sincewhere=slug="x"is a 400. - Page requests are clamped to the platform limits of 500 for
limitand 10,000 foroffset, totals are read from the body’s{ limit, offset, count, total, results }, and the page count is capped at what an offset of 10,000 can reach. GET /me/active-cartanswers 404 for a shopper with no cart, which the connector treats as an empty cart rather than an error; at sign-in it calls/me/loginwhile still holding the anonymous token so the guest cart is merged rather than orphaned.GET /payment-methodsreturns every PaymentMethod in the project, including other customers’ saved instruments, so the connector always adds awherepredicate that keeps only methods with no customer attached, plus the signed-in customer’s own (customer is not defined or customer(id=...)).
Read from the source of misiki-in/commercetools-connector at commit 8d51ac1 of . Where the code has changed since, the code is right.
Quick start
From nothing to a Svelte Commerce storefront reading commercetools. You need Node.js and a commercetools to point it at; the storefront holds no data of its own.
Clone it, choose the connector, point it at commercetools
# 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/commercetools-connector
# 3 — point it at your commercetools project
echo PUBLIC_COMMERCETOOLS_API_URL=https://api.europe-west1.gcp.commercetools.com/your-project-key >> .env
echo PUBLIC_COMMERCETOOLS_API_KEY=... >> .env
echo PUBLIC_COMMERCETOOLS_API_SECRET=... >> .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_COMMERCETOOLS_API_URL | Yes | The project-scoped root, https://api.{region}.commercetools.com/{projectKey}. Boot fails, naming this variable, if it is missing. |
PUBLIC_COMMERCETOOLS_API_KEY | No | The API client’s client_id, sent as HTTP Basic to the auth host only. |
PUBLIC_COMMERCETOOLS_API_SECRET | No | The API client’s client_secret. See the limitations. |
PUBLIC_COMMERCETOOLS_ACCESS_TOKEN | No | Sent as a bearer token when set. |
PUBLIC_COMMERCETOOLS_STORE_ID | No | A Store key: requests go through /in-store/key={storeKey}. |
PUBLIC_COMMERCETOOLS_CHANNEL_ID | No | A Channel ID, sent as a reference in request bodies and as the price channel on reads — not as a path segment. |
PUBLIC_COMMERCETOOLS_REGION | No | Such as europe-west1.gcp. Needed only when it cannot be read from the API URL. |
PUBLIC_COMMERCETOOLS_PROJECT_KEY | No | Defaults to the last path segment of the API URL. |
PUBLIC_COMMERCETOOLS_AUTH_URL | No | OAuth host override. Defaults to the API host with api. replaced by auth.. |
PUBLIC_COMMERCETOOLS_SCOPE | No | Space-separated OAuth scopes requested when a token is issued. |
PUBLIC_COMMERCETOOLS_LOCALE | No | Used to flatten localised strings and build where and sort predicates. Defaults to en. |
PUBLIC_COMMERCETOOLS_CURRENCY | No | ISO 4217 currency for cart and price selection. |
PUBLIC_COMMERCETOOLS_COUNTRY | No | Country code for price selection. |
PUBLIC_CONNECTOR | No | Only when more than one connector is installed: @misiki/commercetools-connector names the one this build runs on. |
init.ts hands the connector every PUBLIC_COMMERCETOOLS_* variable that is set, camel-cased: PUBLIC_COMMERCETOOLS_PROJECT_KEY arrives as projectKey. The guide also lists PUBLIC_COMMERCETOOLS_ACCESS_KEY; the connector’s source does not read it.
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 commercetools
- Create an API client for the storefront with only the scopes a shopper’s session needs: its ID and secret reach the browser.
How the integration works
commercetools updates a resource by sending its current version and a list of actions; the connector models that throughout, so a stale write fails rather than overwrites. It works through the /me endpoints, scoped to the signed-in or anonymous shopper, so no call returns another customer’s data. Tokens come from the auth host, with the API client’s ID and secret as HTTP Basic.
Limitations on commercetools
- The API client’s ID and secret come from
PUBLIC_COMMERCETOOLS_API_KEYandPUBLIC_COMMERCETOOLS_API_SECRET. SvelteKit sendsPUBLIC_variables to the browser, so every visitor can read them; the client’s scopes are what limit the damage.
Troubleshooting commercetools
| When you see | What to do |
|---|---|
| Boot fails with “the commercetools connector is active but PUBLIC_COMMERCETOOLS_API_URL is not set” | Add PUBLIC_COMMERCETOOLS_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. |
| The build stops with “Several commerce connectors are installed … Set PUBLIC_CONNECTOR to pick one” | More than one @misiki/*-connector is in package.json and none is Litekart’s. Uninstall the ones you do not run — a fresh clone also lists @misiki/vendure-connector — or set PUBLIC_CONNECTOR='@misiki/commercetools-connector'. |
[commercetools] no native implementation for get /api/... in the console | The connector’s REST guard caught a path inherited from Litekart and answered it empty instead of requesting it. Each path is reported once. Harmless if commercetools has no such feature; if it has one, the fix belongs in the connector’s matching service. |
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.
An open question for commercetools’s maintainers: For a headless storefront, is the /me surface plus an anonymous token the idiomatic pattern, or should the connector use the Checkout or Frontend APIs instead?
FAQ
Questions about Svelte Commerce on commercetools
Can I run a commercetools project on Svelte Commerce today?
Cart, checkout and sign-in are wired through the /me endpoints; countries, currencies, CMS pages and vendors are not. Like every connector, it has not been run against a live production commercetools project.
How do I switch Svelte Commerce to commercetools?
Remove the connectors the storefront ships with, install @misiki/commercetools-connector, set PUBLIC_COMMERCETOOLS_API_URL in .env and start the dev server. vite.config.ts resolves whichever connector is installed, so no file in the storefront changes.
Does the connector use the /me endpoints or the Checkout API?
The /me endpoints, with an anonymous token for guests, so nothing runs unscoped. The Svelte Commerce maintainers have asked commercetools whether that is the idiomatic pattern for a headless storefront, or whether the Checkout and Frontend APIs are.
Sources
COMMERCETOOLS.md, read on ; CONNECTORS.md, read on ; the connector’s source at 8d51ac1. Where they disagree with this page, they are right. commercetools is a trademark of its owner, named only to describe compatibility; see trademarks.