# Payload CMS

> Modern TypeScript headless CMS with great developer experience.

- Category: CMS & Blogging
- Difficulty: intermediate
- Components: payload, mongodb
- Tags: payload, typescript, headless, nodejs
- Source: https://docker.recipes/cms/payload-cms

## Overview

Payload CMS is a modern headless content management system built specifically for TypeScript developers, offering full type safety and an exceptional developer experience. Unlike traditional CMSs that force you into rigid templates, Payload generates TypeScript types from your content schemas and provides both REST and GraphQL APIs automatically. It combines the flexibility of a headless architecture with powerful admin UI generation, making it ideal for developers who want complete control over their frontend while maintaining content editor-friendly backend interfaces.

This stack pairs Payload with MongoDB to create a powerful content platform that leverages MongoDB's flexible document structure for complex content relationships and schema evolution. MongoDB's JSON-like document storage aligns perfectly with Payload's TypeScript-first approach, allowing for rich content modeling without the constraints of relational database tables. The combination enables rapid content schema changes, complex nested structures, and efficient querying for content delivery APIs.

This configuration is perfect for development teams building modern web applications, e-commerce platforms, or multi-tenant SaaS products where content flexibility and type safety are paramount. Frontend developers working with React, Next.js, or Vue will particularly benefit from Payload's automatic TypeScript type generation, while content creators get a polished admin interface that adapts to custom field configurations.

## Features

- Automatic TypeScript type generation from content collections with full IntelliSense support
- Built-in authentication and authorization with role-based access control and field-level permissions
- Rich text editor with custom React components and serializable JSON output
- Advanced relationship fields supporting one-to-one, one-to-many, and many-to-many associations
- Configurable file upload handling with support for local storage, S3, and Cloudinary adapters
- Live preview functionality for draft content with webhook integration
- MongoDB aggregation pipeline support for complex content queries and analytics
- Custom React components in admin UI with hooks for extending functionality

## Use cases

- Multi-site content management for agencies serving multiple clients from single installation
- E-commerce platforms requiring complex product relationships and inventory management
- Documentation websites with versioning, team collaboration, and API-driven content delivery
- SaaS applications needing user-generated content with role-based publishing workflows
- Mobile app backends requiring structured content delivery with offline sync capabilities
- Corporate websites with multilingual content and approval workflows for compliance
- Developer portfolios and blogs with custom post types and automated deployment triggers

## Prerequisites

- Docker and Docker Compose installed with at least 4GB available RAM for development workloads
- Node.js 18+ and npm/yarn knowledge for Payload project initialization and customization
- TypeScript familiarity for schema configuration and custom field development
- Basic MongoDB concepts including document structure and indexing strategies
- Understanding of environment variable management for secrets and database connections
- Port 3000 available for Payload admin interface and API endpoints

## docker-compose.yml

```yaml
services:
  payload:
    build: .
    container_name: payload
    restart: unless-stopped
    environment:
      MONGODB_URI: mongodb://mongodb:27017/${DB_NAME}
      PAYLOAD_SECRET: ${PAYLOAD_SECRET}
    ports:
      - "3000:3000"
    depends_on:
      - mongodb
    networks:
      - payload-network

  mongodb:
    image: mongo:7
    container_name: payload-mongodb
    volumes:
      - mongodb_data:/data/db
    networks:
      - payload-network

volumes:
  mongodb_data:

networks:
  payload-network:
    driver: bridge
```

## .env

```bash
DB_NAME=payload
PAYLOAD_SECRET=your-secret-here
```

## Usage notes

- Docs: https://payloadcms.com/docs
- Create project: npx create-payload-app, then add Dockerfile
- Access admin at http://localhost:3000/admin - create first user
- REST API at /api/[collection], GraphQL available
- TypeScript-first: full type safety and autocompletion
- Local file uploads, S3, Cloudinary adapters available

## Troubleshooting

- Module build failed with TypeScript errors: Ensure tsconfig.json includes Payload's generated types directory and restart the container
- MongoDB connection refused: Verify MONGODB_URI environment variable uses service name 'mongodb' not 'localhost' for container networking
- Admin UI shows 'Unauthorized' after login: Check PAYLOAD_SECRET environment variable is set and consistent across container restarts
- File uploads failing with permission errors: Verify Docker volume permissions and ensure upload directory is writable by container user
- API responses missing TypeScript types: Run 'payload generate:types' command and rebuild container to update generated definitions
- Collection queries returning empty results: Check MongoDB indexes are created properly and collection names match Payload schema slugs exactly

