DOCSEARCHbyAlgolia
Submit Docs

Svelte Commerce

repository·main·Indexed 23 days ago

https://github.com/itswadesh/svelte-commerce

An open-source, headless PWA storefront built with SvelteKit. It features a connector-based architecture supporting backends such as Litekart, Medusa, Vendure, Saleor, Shopify, and WooCommerce. The platform includes a product catalog, cart, checkout, and order management, and supports multiple switchable storefront themes. It also includes varni-reskin, a tool for performing design transplants from static HTML/CSS/JS stores into Svelte Commerce themes.

Tokens
25.8K
Snippets
30
Records
156
Agent score
83%

What's inside svelte-commerce

  1. What is Svelte Commerce?

    main

    Svelte Commerce is an open-source, headless e-commerce frontend. It is built using SvelteKit and Tailwind CSS.

    Its primary goal is to provide a high-performance, 'lightning-fast' shopping experience that is decoupled from the backend. Because it is headless, it is designed to connect to any backend API, including:

    • Litekart
    • Medusa
    • Shopify
    • and other compatible APIs.

  2. Component build order for AI agents

    main

    When building or restyling storefronts, agents should follow a bottom-up approach to ensure reusability and structural integrity:

    1. Micro components: Buttons, icons, badges, labels, price text, inputs, etc.
    2. Reusable commerce components: Product cards, category cards, menu cards, promo cards, etc.
    3. Layout components: Header, navigation, footer, announcement bars, containers.
    4. Page sections: Hero, categories, featured products, about, testimonials.
    5. Page contents: Route files that compose sections and pass data.

  3. Manage switchable storefront themes

    main

    The application supports multiple coexisting themes. Instead of overwriting the app, the live application selects an active theme from configuration.

    Theme Selection

    • Local/Deployment: Use the PUBLIC_STOREFRONT_THEME environment variable (e.g., PUBLIC_STOREFRONT_THEME=limelight).
    • Admin/Store Overrides: Themes can be overridden via various store configuration fields, such as store.theme, store.activeTheme, store.themeName, store.settings.theme, or store.plugins.themeSettings.activeTheme.

    Implementation Requirements

    • Root Layout: The root layout should expose data.theme and the attribute data-theme="<theme-name>".
    • Guarding Content: Theme-specific code (copy, images, sections, icons) must be guarded by the active theme check.
    • Content Separation: Homepage theme copy, assets, and static content (hero copy, SEO metadata, section labels, decorative images, testimonials, etc.) must live in the theme layer. Route files should only render themeContent combined with API commerce data.
    • Data Integrity: Do not replace theme-owned elements (banners, promos, trust badges) with API data like desktopBanners or mobileBanners.

  4. How to switch eCommerce backends

    main

    Svelte Commerce uses a connector-based architecture to communicate with different eCommerce backends. To switch your backend, you must modify a single export in src/lib/services/index.ts. You must pick exactly one connector to export.

    Supported connectors include:

    • @misiki/litekart-connector (Reference implementation, most complete)
    • @misiki/medusa-connector
    • @misiki/vendure-connector
    • @misiki/saleor-connector
    • @misiki/shopify-connector
    • @misiki/woocommerce-connector
    // src/lib/services/index.ts
// pick exactly one
export * from '@misiki/litekart-connector'
// export * from '@misiki/medusa-connector'
// export * from '@misiki/vendure-connector'
// export * from '@misiki/saleor-connector'
// export * from '@misiki/shopify-connector'
// export * from '@misiki/woocommerce-connector'

  5. Understand the Design Migration Architecture

    main

    The varni-reskin tool is a design migration system, not a full logic rewrite. The existing SvelteKit app remains the source of truth for all ecommerce logic (cart, checkout, API calls, routing, etc.). Only the visual layer is migrated.

    Migration Flow

    1. Parse: Analyze static HTML/CSS.
    2. Extract: Identify design tokens (colors, fonts, spacing, etc.).
    3. Detect: Identify reusable static blocks (header, footer, hero, product cards).
    4. Map: Map static blocks to existing Svelte components.
    5. Generate: Create theme files and a migration plan.
    6. Patch: Apply visual changes to mapped components while preserving props, stores, API calls, events, loops, and accessibility attributes.
    7. Verify: Use Playwright or rendered inspection to compare key pages (Home, Category, Product, Cart, Checkout, Login).

    Data Separation Principle

    • Live Commerce Content: Must come from the app/API. Never hardcode products, prices, or user data in theme files.
    • Theme-Owned Content: Static homepage content (banners, hero text, section copy) belongs in theme config/modules.
    • API-Owned Content: Product lists and commerce data belong in API/composables/stores. On the homepage, only the actual product list should depend on API data.

  6. Complete Storefront Feature Expectations

    main

    A complete storefront implementation must include the following page types and features:

    • Homepage: Full-bleed hero, promo/category tiles, featured products, trust/story band, and newsletter.
    • Shop/Catalog: Category filters, sort, item count, and responsive product grid.
    • Product Detail (PDP): Variants, quantity stepper, add to bag, buy now, wishlist, share, live spec table, trust row, FAQ accordion, reviews (with form), and related products.
    • Cart: Persisted items, quantity edits, remove action, and subtotal.
    • Checkout: Validated shipping form, order summary, persisted order record, and confirmation.
    • Account: Order history, editable persisted profile, and editable persisted saved address.
    • Wishlist: Dedicated page with remove action and synced header count.
    • Long-tail Pages: Contact, FAQ, shipping/returns, about/story, sustainability, careers, press, store locator, gift cards, size guide, order tracking, terms, privacy, and cookie preferences.
    • Mobile Navigation: A real drawer/menu containing the same core links as the desktop version.

  7. Perform visual and functional verification of the store

    main

    After restyling, verify the application through visual inspection and functional testing:

    Visual Inspection

    Compare the rendered app against the source design. Check the following attributes:

    • Layout: Container width/gutters, section padding, grid gaps, card spacing.
    • Typography: Heading margins, font weight.
    • Components: Hero background, primary/secondary buttons, floating cards/badges, images, icons (size, stroke, fill).
    • Styles: Border width/color/style.

    Use Playwright screenshots or direct inspection for key pages: home, category/product listing, product detail, cart, checkout, and login/register.

    Functional Testing

    Exercise the full shopping path to ensure restyling hasn't broken logic:

    1. Product Listing Page (PLP)
    2. Product Detail Page (PDP)
    3. Add to cart
    4. Cart view
    5. Checkout (Address $\rightarrow$ Payment $\rightarrow$ Process $\rightarrow$ Success)

    Fix any console errors, navigation errors, failed requests, or broken cart/checkout states before finalizing the theme.

  8. Guidelines for Originality and Branding

    main

    To ensure brand originality and avoid plagiarism when reskinning, follow these rules:

    • Logo: Do not copy the source logo or use lookalike artwork. Replace logo marks with a text wordmark using the website name. By default, rename the brand to Website-$1 (where $1 is the identifier).
    • Identity: Change all source names, including brand name, domain name, email addresses, phone numbers, addresses, copyright text, metadata, page titles, and footer legal identity.
    • Content: Do not copy proprietary logos, brand names, domains, product names, slogans, long-form copy, photography, illustrations, icon sets, reviews, policies, or distinctive trade dress. Use original target-store content, licensed assets, or API data.
    • Usage of References: Use references only for layout patterns, interaction ideas, component roles, and commerce expectations.

  9. Requirements for Header and Footer implementation

    main

    A theme is not considered complete if the header or footer is missing or still uses the previous theme's chrome. When creating a new theme, clone the source header and footer layout as required sections, ensuring you include:

    • Header: Desktop header, mobile nav/drawer, announcement/top bars, logo placement area, and action icons.
    • Footer: Footer columns, newsletter/legal rows, social/payment areas, and responsive behavior.
    • States: All interaction states must be defined.

  10. Run the reskin pipeline for a single store

    main

    To reskin exactly one store at a specific path, use the reskin.js CLI tool. The tool uses project defaults from reskin.config.json. If the provided path is a parent folder containing multiple stores, the process will stop and prompt you to select a specific store. It does not run in batch mode by default.

    Usage:

    node ./tools/varni-reskin/bin/reskin.js auto --in "<path-to-static-site-store-folder>"
    node ./tools/varni-reskin/bin/reskin.js auto --in "$1"

  11. Final Checklist for Theme Completion

    main

    Before finalizing a theme, perform these checks:

    1. Content Audit: Search for source brand names, domains, emails, phone numbers, addresses, copied policy/review text, copyright strings, and unlicensed asset filenames.
    2. Link Integrity: Verify every footer link points to a real page (no dead # links).
    3. Commerce Flow: Verify the full flow: PLP/category $\rightarrow$ PDP $\rightarrow$ Add to Cart $\rightarrow$ Cart (quantity/remove/subtotal) $\rightarrow$ Checkout (address/payment/process/success) and ensure API/localStorage state persists.
    4. Responsiveness: Check desktop, laptop, tablet, and mobile widths. Ensure scrollWidth <= clientWidth to prevent horizontal overflow. Fix overflowing elements (grids, images, long text) rather than hiding them.
    5. Functionality: Verify forms validate, localStorage persists after reload, and state mutations (add/remove/update) work correctly.
    6. Usability: Run a usability critique and prioritize fixing P0/P1 issues.

  12. Core Workflow for creating or reskinning storefront themes

    main

    When creating, adapting, or reskinning ecommerce storefront themes, follow this two-step documentation workflow before implementation:

    1. Define Brand and Success Criteria: Create or update PRODUCT.md in the root. This file must include:

      • Users
      • Success criteria
      • Brand personality
      • Anti-references
      • 3-5 design principles

    2. Define Theme Design Tokens: Create or update themes/<theme>/DESIGN.md (ensure it is inside the specific theme folder, not the root). This file must include:

      • Color tokens
      • Type scale
      • Spacing
      • Radius
      • Shadow/border rules
      • Component rules
      • Accent-color usage
      • Responsive behavior
      • A copyright/plagiarism checklist