# Vendure

> Headless e-commerce framework with GraphQL.

- Category: E-Commerce & Business
- Difficulty: intermediate
- Components: vendure, postgres
- Tags: vendure, graphql, nodejs, headless
- Source: https://docker.recipes/ecommerce/vendure

## Overview

Vendure is a modern, open-source headless e-commerce framework built with TypeScript and Node.js that provides GraphQL-first APIs for building custom commerce experiences. Launched in 2019, Vendure was designed to address the limitations of traditional monolithic e-commerce platforms by offering a developer-friendly, extensible architecture that separates the commerce engine from the presentation layer. This approach enables businesses to create unique shopping experiences across web, mobile, and emerging channels while maintaining full control over their commerce logic.

This Docker stack combines Vendure's powerful e-commerce engine with PostgreSQL's robust relational database capabilities to create a production-ready headless commerce platform. PostgreSQL's ACID compliance and advanced querying features make it ideal for handling complex e-commerce operations like inventory management, order processing, and customer data relationships. The combination leverages PostgreSQL's JSON support for flexible product attributes while maintaining referential integrity for critical business data like transactions and customer records.

This configuration is perfect for development teams building custom e-commerce solutions, agencies creating commerce platforms for clients, or businesses transitioning from legacy e-commerce systems to modern headless architectures. The stack provides both a complete admin interface for content management and dual GraphQL APIs for frontend integration, making it suitable for everything from rapid prototyping to enterprise-scale deployments.

## Features

- Dual GraphQL APIs with separate shop and admin endpoints for secure role-based access
- Built-in admin UI with comprehensive product, order, and customer management capabilities
- Extensible plugin architecture supporting custom payment processors, shipping calculators, and business logic
- Multi-channel support for managing different storefronts, currencies, and tax zones
- Advanced product modeling with variants, facets, and collections for complex catalog structures
- Real-time inventory tracking with stock allocation and backorder management
- Flexible promotion engine supporting percentage, fixed amount, and tiered discount strategies
- PostgreSQL integration with optimized queries for e-commerce operations and full-text product search

## Use cases

- Building custom storefronts with React, Vue, or Angular while leveraging a robust commerce backend
- Creating multi-brand e-commerce platforms where each brand needs distinct catalogs and pricing
- Developing B2B commerce solutions with custom pricing tiers and approval workflows
- Migrating from Shopify Plus or Magento to a more flexible, developer-controlled platform
- Building marketplace platforms that require complex vendor management and commission structures
- Creating omnichannel retail experiences that sync inventory across web, mobile, and POS systems
- Developing subscription commerce platforms with recurring billing and customer lifecycle management

## Prerequisites

- Minimum 2GB RAM recommended for combined Vendure and PostgreSQL operations
- Port 3000 available for Vendure GraphQL APIs and admin interface access
- Basic understanding of GraphQL queries and mutations for API integration
- Node.js and TypeScript knowledge for customizing Vendure plugins and configuration
- Familiarity with PostgreSQL for database optimization and backup strategies
- Understanding of headless commerce concepts and API-driven frontend development

## docker-compose.yml

```yaml
services:
  vendure:
    image: vendure/vendure:latest
    container_name: vendure
    restart: unless-stopped
    environment:
      DB_HOST: postgres
      DB_PORT: 5432
      DB_NAME: ${DB_NAME}
      DB_USERNAME: ${DB_USER}
      DB_PASSWORD: ${DB_PASSWORD}
    ports:
      - "3000:3000"
    depends_on:
      - postgres
    networks:
      - vendure

  postgres:
    image: postgres:16-alpine
    container_name: vendure-postgres
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - vendure

volumes:
  postgres_data:

networks:
  vendure:
    driver: bridge
```

## .env

```bash
DB_NAME=vendure
DB_USER=vendure
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://docs.vendure.io/
- Admin UI at http://localhost:3000/admin (superadmin/superadmin)
- Shop GraphQL API at http://localhost:3000/shop-api
- Admin GraphQL API at http://localhost:3000/admin-api
- TypeScript + Node.js, highly extensible plugin architecture
- Built for headless commerce with any frontend framework

## Troubleshooting

- Database connection failed: Verify PostgreSQL container is running and DB_HOST matches the postgres service name in the network
- Admin UI shows 'Cannot connect to server': Check that Vendure container started successfully after PostgreSQL and database migrations completed
- GraphQL queries return authentication errors: Ensure you're using the correct API endpoint (shop-api vs admin-api) and proper authorization headers
- Product images not displaying: Configure asset storage settings in Vendure config and ensure proper file upload permissions
- Performance issues with large catalogs: Optimize PostgreSQL memory settings and consider adding database indexes for custom product queries
- Plugin installation failures: Verify TypeScript compilation succeeds and all plugin dependencies are included in the container build

