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 — each is explained under Limitations below.
21 of 43 services wired, read from CONNECTORS.md on , where the package version is recorded too; npm may carry a newer patch. Coverage is traced by a script in the Svelte Commerce repository: a service counts as wired only if it transitively issues an HTTP request, or delegates to one that does. It is not hand-asserted. Some services are Litekart-native concepts with no equivalent elsewhere (reels, deals, chat, gallery, popularity, demo-request, feedback, plugins, banner). They stay documented placeholders on every connector and are excluded from known gaps.
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 devThe guide removes only @misiki/litekart-connector. A fresh clone’s package.json also lists @misiki/vendure-connector, and with two connectors installed and neither of them Litekart’s, the build stops and asks for PUBLIC_CONNECTOR — so this removes both.
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.
- Let the storefront’s origin make cross-origin requests to commercetools (CORS): in production the browser calls
PUBLIC_COMMERCETOOLS_API_URLdirectly, not only the server.
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.
Installing the package is the whole switch. vite.config.ts resolves whichever @misiki/*-connector is installed, and src/lib/core/connectors/init.ts hands it every PUBLIC_COMMERCETOOLS_* variable that is set, camel-cased, at boot — in the server hook for server rendering and in the client hook for the browser, which must reach the same URL in production.
There is no Litekart API behind the storefront here, so store identity — name, logo, currency, menus, plugin toggles, theme colours — comes from src/lib/core/connectors/default-store.json merged under the default export of kitcommerce.config.ts. Until you override it, the store is called “Test”. Any Litekart REST path the connector still inherits is answered from that local data, or resolved empty, rather than requested.
Limitations
- Countries: not wired.
- Currencies: not wired.
- CMS pages: not wired — legal and CMS pages render their layout with empty content.
- Vendors: not wired.
- Pages that depend on a service that is not wired render their empty state rather than failing.
- 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. - Homepage sections other than the live product list come from the active theme’s static content — the standing rule for themes.
- The Conversational Shopping assistant is Litekart-only; its widget stays hidden when another connector is active.
Troubleshooting
| 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'. |
| Boot fails with “PUBLIC_…_API_URL is set, but it configures a different backend than the one this build runs on” | Another backend’s variable is still set, usually left over from the one you switched from. Remove it, or install that backend’s connector. PUBLIC_LITEKART_API_URL is exempt: it only points the dev proxy. |
| The store is called “Test”, or shows the wrong name and logo | Store identity is static on this backend. Set name, logo, currencyCode and the rest in the default export of kitcommerce.config.ts; src/lib/core/connectors/default-store.json lists every field. |
[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. |
http proxy error: api/... ECONNREFUSED in dev | A Litekart REST path was requested from outside the connector, so its guard never saw it. Vite proxies /api to PUBLIC_LITEKART_API_URL, or to localhost:7000. |
The build fails on @misiki/litekart-connector | @misiki/kitcommerce-core declares it as a peer, and vite.config.ts redirects that specifier to whichever connector is installed. Make sure exactly one @misiki/*-connector is listed in package.json. |
Before you rely on it
The one caveat that matters
Read this before choosing
Every connector was written by reading its platform’s authoritative source — an OpenAPI spec, a RAML file, a router registration or the controller source — rather than by running against a store. No connector has been exercised against a live production instance of its platform.
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.
Has the commercetools connector been run against a real commercetools store?
Not against a live production instance — no Svelte Commerce connector has been. It was written by reading commercetools’s authoritative API source, and the Svelte Commerce maintainers ask commercetools’s own maintainers for a sandbox to run it against.
Sources
This page summarises COMMERCETOOLS.md in the Svelte Commerce repository and the commercetools connector’s source, read on , and the coverage in CONNECTORS.md, read on . Where they disagree with this page, they are right and this page is out of date. commercetools is a trademark of its owner, named here only to describe compatibility; no endorsement or affiliation is implied — see trademarks.
Read the whole guide
The storefront is the same on every backend; the connector is what changes. COMMERCETOOLS.md has the commercetools setup in full, beside the connector’s source.