#atom

Headless TypeScript CMS with built-in admin panel and developer flexibility

Core Idea: Payload CMS is a headless, self-hosted content management system built with TypeScript that provides a powerful admin interface while allowing developers to maintain complete control over the content structure, APIs, and presentation layer.

Key Elements

Key Features

• TypeScript-first Architecture: Built with and for TypeScript, providing type safety throughout
• Self-hosted Solution: Complete control over infrastructure and data
• Customizable Admin UI: Extensible React-based interface that can be tailored to specific needs
• Authentication & Access Control: Built-in user management with granular permissions (Payload Authentication)
• Localization Support: Multi-language content with flexible translation workflows
• GraphQL and REST APIs: Automatic API generation based on collection definitions

Concepts

• Payload Config: Central configuration for Payload
• Payload Database Adapter: How Payload connects to the database and communicates
• Payload Collection: A Collection is a Group of Documents that share a common schema, a table would be a Collection
• Payload Global: Global are very similar to Payload Collection, but they correspond to only one Document
• Payload Field: Fields are how the schema for Payload Collection and Payload Global are defined, they are used both for the database and to generate UI on the Payload Admin Panel
• Payload Hooks: These hooks allow for side-effects attached to the Document lifecycle
• Payload Authentication: It's used by default for the Payload Admin Panel, but it can be extended
• Payload Access Control: Determines what an user can do with a Document, they can be applied at Collection, Global or Field level
• Payload Admin Panel: Auto-generated React application to manage the database based on the Payload Config
• Payload API: Payload allows access to the data via three APIs: local, GraphQL and REST

Technical Specifications

• Database Support: MongoDB, PostgreSQL, SQLite
• Framework Compatibility: Next.js, Express, and other Node.js frameworks
• Security Features: RBAC (Role-Based Access Control), field-level access control
• Deployment Options: Self-host on any Node.js-compatible environment
• Plugin System: Extendable through plugins and hooks

Use Cases

• Content-rich Applications: Blogs, documentation sites, and marketing platforms
• E-commerce Solutions: Product catalogs, multi-vendor marketplaces
• Digital Asset Management: Media libraries and document repositories
• Multi-tenant Applications: White-labeled solutions with tenant-specific content

Implementation Steps

// 1. Collection Definition
// collections/Products.ts
import { CollectionConfig } from 'payload/types';

const Products: CollectionConfig = {
  slug: 'products',
  admin: {
    useAsTitle: 'title',
  },
  access: {
    read: () => true,
    create: ({ req }) => req.user?.role === 'admin',
    update: ({ req }) => req.user?.role === 'admin',
    delete: ({ req }) => req.user?.role === 'admin',
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'price',
      type: 'number',
      required: true,
      min: 0,
    },
    {
      name: 'description',
      type: 'richText',
    },
    {
      name: 'category',
      type: 'relationship',
      relationTo: 'categories',
      hasMany: false,
    },
    {
      name: 'images',
      type: 'array',
      fields: [
        {
          name: 'image',
          type: 'upload',
          relationTo: 'media',
          required: true,
        },
        {
          name: 'altText',
          type: 'text',
        }
      ]
    }
  ],
};

export default Products;

// 2. Payload Configuration
// payload.config.ts
import { buildConfig } from 'payload/config';
import Products from './collections/Products';
import Categories from './collections/Categories';
import Media from './collections/Media';
import Users from './collections/Users';

export default buildConfig({
  serverURL: process.env.SERVER_URL,
  admin: {
    user: Users.slug,
  },
  collections: [
    Products,
    Categories,
    Media,
    Users,
  ],
});

Code Examples

Direct API Access in Server Component:

// app/products/page.tsx
import { getPayload } from '@/lib/payload';

export default async function ProductsPage() {
  const payload = await getPayload();
  
  const { docs: products } = await payload.find({
    collection: 'products',
    limit: 10,
    sort: '-createdAt',
  });
  
  return (
    <div>
      <h1>Products</h1>
      <div className="product-grid">
        {products.map(product => (
          <ProductCard key={product.id} product={product} />
        ))}
      </div>
    </div>
  );
}

Common Pitfalls

• Not considering access control patterns early in development
• Overcomplicating collection structures instead of using relationships
• Inefficient field-level access control affecting performance
• Missing proper TypeScript configuration for full type safety benefits

Additional Connections

• Broader Context: Headless CMS, Headless CMS Architecture - How Payload compares to other headless CMS solutions
• Applications: Content Modeling Patterns - Best practices for designing collection structures
• See Also: Strapi - Alternative headless CMS with different architecture choices

References

1. Payload CMS Documentation - https://payloadcms.com/docs
2. "Building with Payload and Next.js" - Payload CMS Blog
3. GitHub Repository - https://github.com/payloadcms/payload

#cms #typescript #headless #api #content-management #node-js

Sources:

• From: Code With Antonio - Build and Deploy a Multi-Vendor E-Commerce Platform with Next.js, React & Stripe Connect (2025)