Svelte Commerce × Django Oscar
Svelte Commerce on Django Oscar
The Django Oscar connector is wired against django-oscar-api, a separate package from Oscar core that must be installed and routed on your instance. Cart, checkout and sign-in are wired; search is among nine recorded gaps.
- 15/43 services wired
- @misiki/oscar-connector 0.5.0
- Cart wired
- Checkout wired
- Sign-in (auth) wired
What works on Django Oscar today
Cart, checkout and sign-in are wired; coupons, reviews, search, CMS pages, payment-method listing, currencies, states, wishlist and vendors are not. Without search, shoppers find products only by browsing.
Cart
Wired: issues a real request to Django Oscar.
Checkout
Wired: issues a real request to Django Oscar.
Sign-in (auth)
Wired: issues a real request to Django Oscar.
Known gaps: coupon, review, search, page, payment-method, currency, state, wishlist, vendor
15 of 43 services wired, read from CONNECTORS.md on ; npm may carry a newer patch. How coverage is measured.
What the connector calls on Django Oscar
The connector calls the JSON REST API of the django-oscar-api package, a Django REST Framework API mounted by the store owner, conventionally under /api/, and checked against the package’s oscarapi/urls.py and views on master and tag 3.2.4.
By default the connector generates a Session-Id header of the form SID:ANON:{host}:{id}, sends it on every call and captures the copy the server echoes back; signing in is POST /api/login/ with username and password, after which the connector flips the header from ANON to AUTH itself, because a browser can read the echoed header only if the store exposes it.
| Service | What it requests |
|---|---|
product | GET /api/products/ with page and page_size, then for each row GET /api/products/{id}/ and the price and availability links it carries |
category | GET /api/categories/, GET /api/categories/{id}/ for a numeric ID, and the parent path such as GET /api/categories/books/ to find a category by slug |
cart | GET /api/basket/, POST /api/basket/add-product/ with { url, quantity }, PATCH and DELETE /api/baskets/{id}/lines/{lineId}/, and POST /api/basket/add-voucher/ with vouchercode |
checkout | GET /api/basket/shipping-methods/, then POST /api/checkout/ with the basket hyperlink, shipping_method_code, shipping_address, billing_address and guest_email |
order | GET /api/orders/ and GET /api/orders/{id}/, following each order’s lines link |
auth | POST /api/login/, GET /api/login/ for the signed-in user, DELETE /api/login/ to sign out, and POST /api/register/ |
address | GET, POST, PATCH and DELETE on /api/useraddresses/ |
Django Oscar rules the connector follows
- Every path ends in a slash, with any query string after it, because Django otherwise answers with a 301 redirect and the POST body is lost.
- Relations are absolute URLs in both directions, so the connector adds to the basket with
{ url: <product URL>, quantity }and checks out with{ basket: <basket URL> }; sendingproduct_idinstead returns 406. - django-oscar-api sets no pagination on any list view, so a stock store returns the whole collection as a bare array and ignores
?page=; the connector then slices pages itself, and readscountfrom a{ count, next, previous, results }envelope only when the store has configured one. - The product list returns only
url,id,upcandtitleby default and accepts no search, sort or category filter, so the connector fetches each product’s detail, price and availability separately. - Signing in on a session that is already
AUTHanswers 405 “Session is in use, log out first”, so the connector sendsDELETE /api/login/first and starts a fresh anonymous session; thehostpart of the header must match the API host without its port, or the store answers 403.
Read from the source of misiki-in/oscar-connector at commit 1dfca30 of . Where the code has changed since, the code is right.
Quick start
From nothing to a Svelte Commerce storefront reading Django Oscar. You need Node.js and a Django Oscar to point it at; the storefront holds no data of its own.
Clone it, choose the connector, point it at Django Oscar
# 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/oscar-connector
# 3 — point it at your Oscar site
echo PUBLIC_DJANGO_OSCAR_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_DJANGO_OSCAR_API_URL | Yes | Base URL of your Oscar site, with django-oscar-api routed. Boot fails, naming this variable, if it is missing. |
PUBLIC_DJANGO_OSCAR_API_KEY | No | HTTP Basic username, for stores that authenticate that way. By default the connector uses django-oscar-api’s Session-Id header session. See the limitations. |
PUBLIC_DJANGO_OSCAR_API_SECRET | No | HTTP Basic password, with the username above. |
PUBLIC_DJANGO_OSCAR_ACCESS_TOKEN | No | Sent as Authorization: Token <key> — only useful if your store wired up DRF token authentication itself; django-oscar-api does not ship it. |
PUBLIC_CONNECTOR | No | Only when more than one connector is installed: @misiki/oscar-connector names the one this build runs on. |
The package is oscar-connector, but the variables follow the product: PUBLIC_DJANGO_OSCAR_*. init.ts hands the connector every one that is set, camel-cased. The guide also lists PUBLIC_DJANGO_OSCAR_ACCESS_KEY, PUBLIC_DJANGO_OSCAR_STORE_ID and PUBLIC_DJANGO_OSCAR_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 Django Oscar
- Install django-oscar-api and route it on your instance: it is a separate package from Oscar core, and the connector talks to nothing else.
How the integration works
The connector speaks django-oscar-api, not Oscar core. By default it keeps the shopper’s session in django-oscar-api’s Session-Id header, which needs no CSRF token; HTTP Basic works too, and there is no bearer scheme at all — django-oscar-api ignores Authorization: Bearer. The route documentation its authors were given was dead, so it was written from the package’s source.
Limitations on Django Oscar
- If you set
PUBLIC_DJANGO_OSCAR_API_KEYandPUBLIC_DJANGO_OSCAR_API_SECRETfor HTTP Basic, that username and password reach every visitor: SvelteKit sendsPUBLIC_variables to the browser.
Troubleshooting Django Oscar
| When you see | What to do |
|---|---|
| Boot fails with “the oscar connector is active but PUBLIC_DJANGO_OSCAR_API_URL is not set” | Add PUBLIC_DJANGO_OSCAR_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/oscar-connector'. |
[oscar] 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 Django Oscar 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 Django Oscar’s maintainers: Is a headless storefront a supported use case for django-oscar-api? Worth stating either way in its docs.
Offer a sandbox or a correctionFAQ
Questions about Svelte Commerce on Django Oscar
Can I run a Django Oscar store on Svelte Commerce today?
Cart, checkout and sign-in are wired through django-oscar-api. Nine services are not, search among them. Like every connector, it has not been run against a live production Oscar store.
How do I switch Svelte Commerce to Django Oscar?
Remove the connectors the storefront ships with, install @misiki/oscar-connector, set PUBLIC_DJANGO_OSCAR_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 Django Oscar need anything extra installed?
Yes: django-oscar-api, a separate package from Oscar core, installed and routed on your instance. The connector talks to it and to nothing else.
Sources
DJANGO-OSCAR.md, read on ; CONNECTORS.md, read on ; the connector’s source at 1dfca30. Where they disagree with this page, they are right. Django Oscar is a trademark of its owner, named only to describe compatibility; see trademarks.