# Vendure — Open Source Headless E-Commerce Framework

> Vendure is a headless commerce framework built with TypeScript, NestJS, and GraphQL. Extensible plugin system, multi-channel support, and full API-first architecture.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
npx @vendure/create my-shop
cd my-shop
npm run dev
```

Open `http://localhost:3000/admin` — login with `superadmin` / `superadmin` and start setting up your store.

## Intro

**Vendure** is an open-source headless commerce framework built with TypeScript, NestJS, and GraphQL. Designed for developers who need a flexible, API-first e-commerce backend, it provides a robust plugin system, multi-channel/multi-vendor support, and a modern admin UI — all without dictating your frontend technology.

With 8K+ GitHub stars, Vendure is popular among teams building custom storefronts with React, Next.js, Vue, or any frontend framework, while leveraging a battle-tested commerce engine for products, orders, payments, and fulfillment.

## What Vendure Does

Vendure covers the complete commerce backend:

- **Product Management**: Products with variants, facets, collections, and custom fields
- **Order Processing**: Cart, checkout, payment, fulfillment, and refund workflows
- **Customer Management**: Customer accounts, addresses, order history, and groups
- **Payment Integration**: Stripe, PayPal, Mollie, Braintree, and custom payment methods
- **Shipping**: Configurable shipping methods with weight/price/zone-based calculation
- **Tax**: Flexible tax calculation with zone-based rates and tax categories
- **Multi-Channel**: Sell on web, mobile, POS, marketplace from a single backend
- **Search**: Full-text product search with Elasticsearch or database-based search
- **Admin UI**: Angular-based admin panel with real-time updates and extensibility

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Storefront  │────▶│  Vendure     │────▶│  PostgreSQL /│
│  (Any FE)    │     │  Server      │     │  MySQL /     │
│  Next.js /   │     │  (NestJS)    │     │  SQLite      │
│  Remix / Vue │     │  GraphQL API │     └──────────────┘
└──────────────┘     └──────┬───────┘
                            │
                     ┌──────┴───────┐
                     │  Admin UI    │
                     │  (Angular)   │
                     └──────────────┘
```

## Getting Started

### Scaffold a New Project

```bash
npx @vendure/create my-shop

# Options:
# - Database: SQLite (dev) / PostgreSQL (prod) / MySQL
# - Populate sample data: Yes/No
# - Install email plugin: Yes/No
```

### Project Structure

```
my-shop/
├── src/
│   ├── vendure-config.ts    # Main configuration
│   ├── plugins/             # Custom plugins
│   └── migrations/          # Database migrations
├── static/                  # Static assets
└── package.json
```

### Configuration

```typescript
// vendure-config.ts
import { VendureConfig } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import { AssetServerPlugin } from '@vendure/asset-server-plugin';
import { EmailPlugin } from '@vendure/email-plugin';

export const config: VendureConfig = {
  apiOptions: {
    port: 3000,
    adminApiPath: 'admin-api',
    shopApiPath: 'shop-api',
  },
  dbConnectionOptions: {
    type: 'postgres',
    host: 'localhost',
    port: 5432,
    database: 'vendure',
    username: 'vendure',
    password: 'vendure',
  },
  plugins: [
    AssetServerPlugin.init({
      route: 'assets',
      assetUploadDir: './static/assets',
    }),
    AdminUiPlugin.init({
      route: 'admin',
      port: 3002,
    }),
    EmailPlugin.init({
      route: 'mailbox',
      handlers: defaultEmailHandlers,
      templatePath: './static/email/templates',
      transport: { type: 'smtp', host: 'localhost', port: 1025 },
    }),
  ],
};
```

## Key Features

### Plugin System

Vendure's plugin architecture is its core strength:

```typescript
import { VendurePlugin, PluginCommonModule } from '@vendure/core';

@VendurePlugin({
  imports: [PluginCommonModule],
  entities: [ReviewEntity],
  shopApiExtensions: {
    schema: gql`
      type ProductReview {
        id: ID!
        rating: Int!
        body: String!
      }
      extend type Product {
        reviews: [ProductReview!]!
      }
    `,
    resolvers: [ProductReviewResolver],
  },
  adminApiExtensions: {
    schema: adminSchema,
    resolvers: [AdminReviewResolver],
  },
})
export class ReviewsPlugin {}
```

### GraphQL API

```graphql
# Shop API — Product query
query {
  product(slug: "laptop-pro") {
    name
    description
    variants {
      name
      price
      stockLevel
    }
    facetValues {
      name
      facet { name }
    }
  }
}

# Shop API — Add to cart
mutation {
  addItemToOrder(productVariantId: "1", quantity: 2) {
    ... on Order {
      code
      totalWithTax
      lines {
        productVariant { name }
        quantity
        linePriceWithTax
      }
    }
  }
}
```

### Custom Fields

Extend any entity without writing migrations:

```typescript
// vendure-config.ts
customFields: {
  Product: [
    { name: 'reviewRating', type: 'float', ui: { component: 'star-rating' } },
    { name: 'downloadUrl', type: 'string' },
  ],
  Customer: [
    { name: 'loyaltyPoints', type: 'int', defaultValue: 0 },
  ],
}
```

## Vendure vs Alternatives

| Feature | Vendure | Medusa | Saleor | Shopify |
|---------|---------|--------|--------|---------|
| Open Source | Yes | Yes (MIT) | Yes (BSD) | No |
| Language | TypeScript | TypeScript | Python | Liquid |
| API | GraphQL | REST + JS SDK | GraphQL | REST + GraphQL |
| Plugin system | Excellent | Good | Apps | Apps |
| Admin UI | Built-in | Built-in | Built-in | Built-in |
| Multi-channel | Yes | Sales channels | Channels | Plus plan |
| Custom fields | Native | Metadata | Metadata | Metafields |

## FAQ

**Q: What size e-commerce is Vendure suitable for?**
A: Everything from small indie shops to medium and large platforms. Vendure's plugin architecture and TypeScript type safety make it especially good for customization-heavy mid-to-large projects. For simple small shops, Shopify may be faster to launch.

**Q: Which frontend framework?**
A: Vendure is fully headless — use any frontend. Official storefront templates exist for Next.js, Remix, and Angular. The community also maintains Nuxt.js and SvelteKit templates.

**Q: Multi-language and multi-currency?**
A: Supported. The Channel feature allows configuring different languages, currencies, and pricing strategies. Each Channel can have its own product catalog, prices, and tax settings.

## Source & Thanks

- GitHub: [vendure-ecommerce/vendure](https://github.com/vendure-ecommerce/vendure) — 8K+ ⭐
- Website: [vendure.io](https://vendure.io)

---
Source: https://tokrepo.com/en/workflows/vendure-open-source-headless-e-commerce-framework-6123e157
Author: AI Open Source