@wix/headless-ecom

E-commerce headless components for building cart, checkout, and commerce functionality in Wix-powered applications.

💡 Motivation

Traditional Wix components are tightly coupled with Wix's editor and rendering engine. Headless components break free from this constraint, enabling developers to build completely custom frontends while still leveraging Wix's powerful backend services.

This package connects your standalone React application (Next.js, Astro, Remix, etc.) directly to Wix's e-commerce APIs through the Wix SDK.

In simple words - the developer brings the UI, Wix provides the e-commerce engine. The headless components are the bridge that connects them, giving the developer the best of both worlds—Wix's robust backend with his frontend creativity.

📦 Package Overview

This package provides unstyled, composable React components for e-commerce functionality, following a service-oriented architecture where business logic is separated from presentation.

For detailed API specifications, see ECOM_INTERFACE.md.

🚀 Installation

``bash
npm install @wix/headless-ecom @wix/headless-components


or

`tsx
import { Cart } from '@wix/headless-ecom/react';
import { LineItem } from '@wix/headless-ecom/react';

function ShoppingCart() {
return (


{({ lineItems, isLoading }) =>
isLoading ? (



{({ checkout, isLoading }) => (

{isLoading ? 'Processing...' : 'Checkout'}

)}


);
}
`

$3

`tsx
import {
CurrentCartService,
loadCurrentCartServiceConfig,
} from '@wix/headless-ecom/services';

// Load cart configuration
const config = await loadCurrentCartServiceConfig();

// Use in your service manager
const services = createServiceManager({
services: [CurrentCartService],
config: { currentCart: config },
});
`

🏗️ Architecture

This package follows a three-layer architecture:

$3

Business logic, state management, and API integrations:

- current-cart-service.ts - Cart state and operations
- checkout-service.ts - Checkout flow management
- selected-option-service.ts - Product option handling
- common-types.ts - Shared TypeScript types

$3

Headless UI primitives with render props:

- Core Components (/react/core) - Plain render functions connecting directly to the SDK. These use the old render-props pattern and provide the foundational logic for interacting with Wix services.
- Public API Components (/react) - Primitive components inspired by Radix UI. These wrap the core components to provide a more modern, composable API with asChild support and follow the documented patterns.

Key Principle: Headless components include no styling and preferably minimal DOM elements. They are designed to be building blocks for composing the UI of your e-commerce app, giving the developer complete control over the visual presentation while handling all the business logic, state management, and API interactions.

$3

Data transformation utilities:

- line-item-to-selected-options.ts - Convert line items to selected options

📋 File Structure

`
ecom/
├── package.json
├── README.md (this file)
├── tsconfig.*.json
├── vitest.config.ts
├── src/
│ ├── react/
│ │ ├── Cart.tsx (1,246 lines - main component)
│ │ ├── Cart.test.tsx
│ │ ├── LineItem.tsx
│ │ ├── LineItem.test.tsx
│ │ ├── SelectedOption.tsx
│ │ ├── SelectedOption.test.tsx
│ │ ├── CartCoupon.tsx
│ │ ├── CartCoupon.test.tsx
│ │ ├── CurrentCart.tsx
│ │ ├── Commerce.tsx
│ │ ├── Commerce.test.tsx
│ │ ├── index.tsx
│ │ └── core/
│ │ ├── CurrentCart.tsx (old render-props)
│ │ └── Checkout.tsx
│ ├── services/
│ │ ├── current-cart-service.ts
│ │ ├── checkout-service.ts
│ │ ├── selected-option-service.ts
│ │ ├── common-types.ts
│ │ └── index.ts
│ ├── mappers/
│ │ └── line-item-to-selected-options.ts
│ └── data-component-tags.ts
├── dist/ (built ESM output)
└── cjs/ (built CommonJS output)
`

🛠️ Development

$3

`bash


Install dependencies (from monorepo root)

⚠️ Important: Always use --run flag to avoid interactive watch mode.

`bash


Run tests (non-interactive)

`bash


Build both ESM and CommonJS

`bash


Lint and fix

`tsx
// Level 1: Container - provides context, conditional rendering

// Level 2: List container - handles empty state
Your cart is empty