How itswadesh/svelte-commerce works
1. This repository is a SvelteKit-based headless ecommerce storefront. Its main boundary is the frontend app: it renders product discovery, cart, checkout, account, and content pages while delegating commerce data to an external backend/API.
2. The application is split by route groups under src/routes:
- (www) is the public storefront and commerce flow
- (my) is the authenticated customer area
- (legal) contains static/legal content
- proxy/shopify/[path] is an API proxy boundary
- robots.txt and sitemap.xml are generated SEO endpoints
3. The storefront flow is organized around core ecommerce domains: home page, categories, collections, products, store/vendor pages, cart, checkout, auth, profile, orders, wishlist, messages, and order tracking. Product detail pages have their own local component set, showing that PDP behavior is a major subsystem rather than a simple generic page.
4. Data loading is split between SvelteKit server hooks/layouts and page-level loaders. Files like +layout.server.ts, +page.server.ts, and +page.ts indicate SSR-driven data fetches for initial page state, with client-side navigation enhancing SPA behavior after hydration.
5. The backend integration boundary lives in src/lib/services and is explicitly configurable. The README says only one service implementation is active at a time, with supported connector targets such as Litekart and Medusa, and the proxy route exists to adapt third-party API paths without exposing the backend directly to the browser.
6. src/lib/core is the app’s shared architecture layer. It contains reusable logic, service exports, load-function helpers, stores, hooks, composables, utilities, and core components. This is where cross-cutting concerns like viewport detection, collection state, theme handling, and loading behavior are centralized.
7. UI is heavily componentized. src/lib/components contains feature components for auth, address, checkout, cart, coupon, navigation, home, page blocks, product catalogue, and order UI. In parallel, src/lib/components/ui provides a large primitive design system for dialogs, drawers, buttons, tables, forms, tabs, selects, carousel, sidebar, and other reusable controls.
8. The checkout and account areas are distinct subsystems. Checkout is broken into steps and pages for cart, address, payment, process, success, and failure. The customer area under (my) handles orders, addresses, profile, wishlist, and buy-again behavior, implying authenticated state and server-side authorization checks.
9. The content and merchandising layer is separate from pure catalog pages. Home page banners, collection carousels, featured products, featured categories, rich text blocks, Instagram/share/WhatsApp-style plugins, and product aggregations show that the storefront is designed to be driven by configurable page sections rather than hardcoded layouts.
10. Assets and presentation are part of the app package, not a separate service. Media lives in src/lib/assets and static, while styling is handled through app CSS, Tailwind/PostCSS, and Svelte components. This supports themeable storefronts and image-heavy merchandising.
11. Operationally, the repo is built for multiple deployment targets: Vercel, Docker, and a PM2-based setup in devops. There are helper scripts for copying and deploying, plus manifest generation, which suggests the app can be packaged and hosted in several production environments without changing the core architecture.
12. Test coverage is split between unit/component tests and browser flows. tests/*.test.ts covers lower-level UI and logic, while tests/*.spec.ts and Playwright config cover end-to-end storefront journeys like navigation, product browsing, checkout, login, and cart behavior.
13. The overall runtime picture is: browser client → SvelteKit pages/layouts → shared core/service layer → external commerce backend via connector/proxy. The repo’s key architectural choice is that the storefront owns presentation, routing, and customer flows, while catalog/order/payment data come from whichever backend connector is selected.
Main entry points: routes Storefront app · components Feature UI · (www) Public flow · core Core layer
Components 19
SvelteKit app
Frontend storefront application, route boundaries, and shared app layer.
- Storefront app · Headless ecommerce frontend that owns routing, presentation, and customer flows.
src/routes - Public flow · Public storefront for discovery, product browsing, and commerce actions.
src/routes/(www) - My account · Authenticated customer area for profile, orders, wishlist, and addresses.
src/routes/(my) - Legal pages · Static and content-oriented pages such as policies, blog, and FAQs.
src/routes/(legal) - Product pages · Product detail route with its own local component set for gallery, pricing, specs, reviews, and related items.
src/routes/(www)/products/[slug] - Checkout flow · Cart-to-success path covering cart, address, payment, processing, success, and failure states.
src/routes/(www)/checkout - Auth flow · Login, signup, verification, password reset, and vendor onboarding paths.
src/routes/(www)/auth - SEO endpoints · robots.txt and sitemap.xml generation for search indexing.
src/routes/robots.txt - Backend proxy · Path adapter boundary that forwards selected backend requests without exposing the service directly.
src/routes/proxy/shopify/[path] - SSR layouts · Root and section layouts/loaders that establish server-rendered app state and navigation context.
src/routes/+layout.server.ts
Shared core
Reusable logic, services, hooks, and UI building blocks.
- Core layer · Reusable application layer for cross-cutting state, hooks, load helpers, logic, and component exports.
src/lib/core - Services · Configurable commerce service implementations; only one connector is active at a time.
src/lib/core/services - Feature UI · Domain components for auth, cart, checkout, home, product catalogue, orders, navigation, and content sections.
src/lib/components - UI primitives · Reusable component library for dialogs, drawers, forms, tables, tabs, selects, carousel, sidebar, and more.
src/lib/components/ui - Hooks & stores · Shared client behaviors such as viewport detection, theme handling, and collection state.
src/lib/core/hooks - Assets & styles · Images, static media, app styles, and themeable presentation resources.
src/lib/assets
Operations
Deployment, build, and packaging helpers.
- Deploy tools · Build and deployment helpers for Docker, Vercel, and PM2-based hosting.
devops
Tests
Unit, component, and end-to-end coverage.
- Unit tests · Component and logic tests for UI primitives, services, utilities, and validation behavior.
tests - E2E tests · Playwright-style browser journeys covering navigation, product browsing, cart, checkout, and login.
tests
Connections 28
- Storefront app → Public flow: routes · Public storefront boundary.
- Storefront app → My account: routes · Authenticated customer area.
- Storefront app → Legal pages: routes · Static content and policy pages.
- Storefront app → SEO endpoints: generates · SEO output routes.
- Storefront app → Backend proxy: proxies · Backend API adaptation boundary.
- Storefront app → SSR layouts: boots · Server/client layouts establish app state.
- Public flow → Product pages: includes · PDP subsystem inside commerce flow.
- Public flow → Checkout flow: includes · Shopping cart and checkout journey.
- Public flow → Auth flow: includes · Public authentication and onboarding flow.
- Public flow → Feature UI: renders with · Feature components drive storefront sections.
- My account → Feature UI: renders with · Account UI reuses domain components.
- Legal pages → Feature UI: renders with · Content pages use shared layout components.
- Product pages → Feature UI: uses · Local PDP pieces compose the detail page.
- Checkout flow → Feature UI: uses · Checkout steps use feature UI components.
- Auth flow → UI primitives: uses · Forms, dialogs, and inputs support auth flows.
- Feature UI → UI primitives: built on · Feature UI composes the design system.
- Core layer → Services: exports · Connector and service layer lives under core.
- Core layer → Hooks & stores: centralizes · Shared client state and behaviors.
- Core layer → Feature UI: shares · Reusable core components and plugins.
- Core layer → SSR layouts: supports · Load helpers and SSR utilities feed route loaders.
- Services → Backend proxy: connects via · Proxy route adapts external commerce APIs.
- Assets & styles → Feature UI: supplies · Media and styling assets feed rendered UI.
- Deploy tools → Storefront app: packages · Operational scripts target the app for deployment.
- Unit tests → UI primitives: covers · Tests validate shared UI and logic.
- Unit tests → Core layer: covers · Tests validate shared architecture code.
- E2E tests → Public flow: covers · Browser flows exercise storefront journeys.
- E2E tests → Checkout flow: covers · Checkout journey is verified end to end.
- E2E tests → Auth flow: covers · Login and signup flows are browser tested.