e-commerce-structure

A reusable TypeScript structure for e-commerce projects that need ecommerce logic and API integration.

The goal is to keep business logic separate from the API provider. Your app talks to services like ProductService, CartService, and CheckoutService. Those services talk to repository interfaces. An adapter connects the interfaces to your real backend, such as a custom REST API, Shopify, WooCommerce, Medusa, Stripe, Firebase, Supabase, or any other provider.

Structure

src/
  core/
    api-client.ts          Shared HTTP client
    errors.ts              Shared app errors
    result.ts              Result helper
  commerce/
    product/               Product contracts and service
    cart/                  Cart contracts and service
    customer/              Customer contracts and service
    order/                 Order contracts and service
    checkout/              Checkout contracts and service
  integrations/
    rest/                  Generic REST adapter
examples/
  basic-usage.ts

Why This Structure Works

• Services hold reusable ecommerce rules.
• Repository interfaces define what the app needs.
• Integrations translate your API provider into those interfaces.
• UI frameworks stay optional. Use this from Next.js, React, Vue, Svelte, Express, or Node.
• Providers are replaceable. Swap the adapter, keep the business logic.

Basic Usage

import {
  ApiClient,
  CartService,
  CheckoutService,
  ProductService,
  RestCommerceAdapter,
} from "web2-commerce-kit";

const api = new ApiClient({
  baseUrl: process.env.API_BASE_URL!,
  token: process.env.API_TOKEN,
});

const adapter = new RestCommerceAdapter({ api });

export const products = new ProductService(adapter);
export const carts = new CartService(adapter);
export const checkout = new CheckoutService(adapter);

Add To A Project

1. Copy src/commerce, src/core, and the needed folder from src/integrations.
2. Create services once in your app, usually in a lib/commerce.ts file.
3. Use the services from pages, server actions, API routes, controllers, or jobs.
4. Add a new adapter when your backend has different endpoint names or payload shapes.

Custom REST Endpoints

You can override endpoint paths when creating the adapter:

const adapter = new RestCommerceAdapter({
  api,
  paths: {
    products: "/store/products",
    checkoutSessions: "/payments/checkout",
    productById: (id) => `/store/products/${id}`,
  },
});

Suggested Next Modules

• payment: payment intents, refunds, webhooks.
• shipping: shipping rates, labels, tracking.
• promotion: coupons, discounts, gift cards.
• inventory: stock reservations and warehouse rules.
• tax: regional tax calculation.
• analytics: events for product views, cart actions, and checkout.

Commands

npm install
npm run typecheck
npm run build