@mdxe/payload

Generate and run Payload CMS apps on Cloudflare Workers using mdxdb.

Installation

pnpm add @mdxe/payload @mdxdb/payload @mdxdb/sqlite payload

Quick Start

1. Create Worker

// src/worker.ts
import { createPayloadWorker } from '@mdxe/payload'
import { MDXDatabase } from '@mdxdb/sqlite'

// Export Durable Object for wrangler
export { MDXDatabase }

// Export worker
export default createPayloadWorker({
  namespace: 'example.com',
  database: 'sqlite',
})

2. Configure Wrangler

# wrangler.toml
name = "my-payload-app"
main = "src/worker.ts"
compatibility_date = "2024-01-01"

[[durable_objects.bindings]]
name = "MDXDB"
class_name = "MDXDatabase"

[[migrations]]
tag = "v1"
new_classes = ["MDXDatabase"]

[vars]
PAYLOAD_SECRET = "your-secret-here"
NAMESPACE = "example.com"

3. Deploy

wrangler deploy

With Custom Collections

import {
  createPayloadWorker,
  createContentCollections,
  getNativeCollections,
} from '@mdxe/payload'
import { MDXDatabase } from '@mdxdb/sqlite'

export { MDXDatabase }

export default createPayloadWorker({
  namespace: 'example.com',
  database: 'sqlite',
  nativeCollections: {
    things: true,
    relationships: true,
    events: true,
    actions: true,  // Jobs/Tasks/Workflows
  },
  collections: [
    ...createContentCollections(), // Posts, Pages, Categories
  ],
})

Generate Collections from MDX

Parse MDX files to automatically generate Payload collections:

import { parseTypeFromMDX, generateCollections } from '@mdxe/payload/generate'

// From single MDX file
const mdxContent = `---
$type: BlogPost
title: Hello World
author: john
tags: [hello, world]
---

Content here...
`

const type = parseTypeFromMDX(mdxContent)
// { name: 'BlogPost', slug: 'blog-posts', fields: [...], relationships: [...] }

// Generate collection
const collections = await generateCollections({
  types: [type],
})

Configuration Options

interface PayloadAppConfig {
  // Required
  namespace: string           // e.g., 'example.com'
  database: 'sqlite' | 'clickhouse'

  // Native mdxdb collections
  nativeCollections?: boolean | {
    things?: boolean         // Graph nodes
    relationships?: boolean  // Graph edges
    search?: boolean         // Indexed content
    events?: boolean         // Event log
    actions?: boolean        // Jobs queue
    artifacts?: boolean      // Build cache
  }

  // Custom collections
  collections?: CollectionConfig[]
  globals?: GlobalConfig[]

  // Admin UI
  admin?: {
    route?: string           // Default: '/admin'
    livePreview?: boolean
    branding?: {
      logo?: string
      favicon?: string
      title?: string
    }
  }

  // API
  api?: {
    route?: string           // Default: '/api'
    graphQL?: boolean
    rest?: boolean
  }

  // Auth
  auth?: {
    enabled?: boolean
    userSlug?: string        // Default: 'users'
    apiKeys?: boolean
  }
}

Environment Variables

# Required
PAYLOAD_SECRET=your-secret-key

# Optional
NAMESPACE=example.com
DEBUG=true

# For ClickHouse mode
CLICKHOUSE_URL=https://your-instance.clickhouse.cloud
CLICKHOUSE_USERNAME=default
CLICKHOUSE_PASSWORD=secret
CLICKHOUSE_DATABASE=mdxdb

Pre-built Collection Sets

Content Collections

import { createContentCollections } from '@mdxe/payload'

// Creates: posts, pages, categories
const collections = createContentCollections()

Commerce Collections

import { createCommerceCollections } from '@mdxe/payload'

// Creates: products, product-categories, orders
const collections = createCommerceCollections()

API Endpoints

Once deployed, your Payload API is available at:

• GET /api/{collection} - List documents
• GET /api/{collection}/{id} - Get single document
• POST /api/{collection} - Create document
• PATCH /api/{collection}/{id} - Update document
• DELETE /api/{collection}/{id} - Delete document
• GET /health - Health check
• POST /graphql - GraphQL endpoint (coming soon)
• /admin - Admin UI (coming soon)

Query Parameters

# Pagination
GET /api/posts?page=1&limit=10

# Sorting
GET /api/posts?sort=-createdAt

# Filtering
GET /api/posts?where={"status":{"equals":"published"}}

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Cloudflare Workers                        │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                  @mdxe/payload                         │  │
│  │           (Worker Handler + Config Builder)            │  │
│  └───────────────────────────────────────────────────────┘  │
│                            │                                 │
│                            ▼                                 │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                  @mdxdb/payload                        │  │
│  │    (Payload DB Adapter → Things + Relationships)       │  │
│  └───────────────────────────────────────────────────────┘  │
│                            │                                 │
│            ┌───────────────┴───────────────┐                │
│            ▼                               ▼                │
│  ┌─────────────────────┐       ┌─────────────────────────┐  │
│  │   @mdxdb/sqlite     │       │    @mdxdb/clickhouse    │  │
│  │  (Durable Objects)  │       │     (HTTP Client)       │  │
│  └─────────────────────┘       └─────────────────────────┘  │
│            │                               │                │
│            ▼                               ▼                │
│  ┌─────────────────────┐       ┌─────────────────────────┐  │
│  │   SQLite Storage    │       │  ClickHouse Database    │  │
│  │  (per-namespace)    │       │  (shared analytics)     │  │
│  └─────────────────────┘       └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

License

MIT