# KeystoneJS for E-commerce

> Node.js CMS for headless commerce.

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

## Overview

KeystoneJS is a modern, TypeScript-first headless CMS and application framework built on Node.js that provides a GraphQL API and admin interface for content management. Originally developed by Thinkmill, KeystoneJS has evolved into a powerful platform for building complex data-driven applications, offering a code-first approach to schema definition with automatic admin UI generation and type-safe database operations through Prisma ORM.

This stack combines KeystoneJS with PostgreSQL to create a robust foundation for headless e-commerce applications. KeystoneJS handles content management, user authentication, and GraphQL API generation, while PostgreSQL provides ACID-compliant data storage with advanced features like JSON support for flexible product catalogs and full-text search capabilities for product discovery. The integration leverages PostgreSQL's relational strengths for complex e-commerce queries involving orders, inventory, and customer relationships.

This combination is ideal for developers building modern e-commerce platforms who need the flexibility of a headless architecture with the robustness of enterprise-grade data management. E-commerce businesses requiring custom admin interfaces, complex product catalogs, multi-channel content delivery, and sophisticated business logic will benefit from KeystoneJS's extensible hook system and PostgreSQL's advanced querying capabilities.

## Features

- Auto-generated GraphQL API with built-in playground for testing product queries and mutations
- TypeScript-first schema definition with automatic type generation for e-commerce entities
- Built-in admin interface with customizable forms for managing products, orders, and customers
- Prisma ORM integration providing type-safe database operations and migrations
- Hook system for implementing custom e-commerce logic like inventory updates and order processing
- Session-based authentication with configurable access control for different user roles
- PostgreSQL JSONB support for flexible product attributes and metadata storage
- Full-text search capabilities through PostgreSQL for product catalog searches

## Use cases

- Headless e-commerce platforms requiring custom frontend applications across web and mobile
- Multi-tenant marketplaces with different seller dashboards and product catalogs
- B2B commerce platforms with complex pricing rules and customer-specific product visibility
- Content-rich e-commerce sites combining product catalogs with editorial content management
- Inventory management systems requiring real-time stock tracking and automated reordering
- Subscription-based commerce platforms with recurring billing and customer portal functionality
- International e-commerce sites requiring multi-currency support and localized product data

## Prerequisites

- Docker Engine 20.10+ and Docker Compose V2 for container orchestration
- Minimum 1GB RAM for PostgreSQL optimal performance with e-commerce workloads
- Port 3000 available for KeystoneJS admin interface and GraphQL API access
- Basic understanding of GraphQL queries and mutations for API interaction
- Node.js and TypeScript knowledge for custom schema development and hooks
- Familiarity with Prisma ORM concepts for database schema management

## docker-compose.yml

```yaml
services:
  keystone:
    image: keystonejs/keystone:latest
    container_name: keystone
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
      SESSION_SECRET: ${SESSION_SECRET}
    ports:
      - "3000:3000"
    depends_on:
      - postgres
    networks:
      - keystone

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

volumes:
  postgres_data:

networks:
  keystone:
    driver: bridge
```

## .env

```bash
DB_NAME=keystone
DB_USER=keystone
DB_PASSWORD=changeme
SESSION_SECRET=your-session-secret
```

## Usage notes

- Docs: https://keystonejs.com/docs
- Admin UI at http://localhost:3000 - create admin on first visit
- GraphQL API built-in at /api/graphql with Playground
- Define schemas in schema.ts: lists for products, orders, users
- TypeScript-first with Prisma ORM for database
- Hooks and access control for custom business logic

## Troubleshooting

- KeystoneJS fails to start with database connection error: Verify DATABASE_URL format and ensure PostgreSQL container is fully initialized before KeystoneJS starts
- Admin interface shows 'Session Secret Required' error: Set a strong SESSION_SECRET environment variable with at least 32 characters
- GraphQL mutations fail with permission errors: Configure access control in your schema.ts lists or create an admin user through the initial setup flow
- PostgreSQL container exits with 'data directory not empty' error: Remove the postgres_data volume or use different volume name to start fresh
- KeystoneJS schema changes not reflected: Restart the KeystoneJS container to trigger Prisma migrations and schema updates
- Memory issues with large product catalogs: Increase PostgreSQL shared_buffers and effective_cache_size through environment variables

