@ylstack-dev/cf-cms-core

Core framework for CfCms - A modern, TypeScript-first headless CMS built for Cloudflare's edge platform.

🏠 New to CfCms?

Visit cf-cms.com for full documentation and guides.

To create a new CfCms project, use:

npx create-cf-cms my-app

This is the recommended way to get started with CfCms. It sets up everything you need with a single command.

✨ Features

• 🚀 Edge-First: Runs on Cloudflare Workers for sub-50ms global response times
• 📦 Zero Cold Starts: V8 isolates provide instant startup
• 🔒 Type-Safe: Full TypeScript support with comprehensive type definitions
• 🔌 Plugin System: Extensible architecture with hooks and middleware
• ⚡ Three-Tier Caching: Memory, KV, and database layers for optimal performance
• 🎨 Admin Interface: Beautiful glass morphism design system
• 🔐 Authentication: JWT-based auth with role-based permissions
• 📝 Content Management: Dynamic collections with versioning and workflows
• 🖼️ Media Management: R2 storage with automatic optimization
• 🌐 REST API: Auto-generated endpoints for all collections

📦 Installation

npm install @ylstack-dev/cf-cms-core

Required Peer Dependencies

npm install @cloudflare/workers-types hono drizzle-orm zod

Optional Dependencies

npm install wrangler drizzle-kit  # For development

🚀 Quick Start

1. Create Your Application

// src/index.ts
import { createCfCmsApp } from '@ylstack-dev/cf-cms-core'
import type { CfCmsConfig } from '@ylstack-dev/cf-cms-core'

const config: CfCmsConfig = {
  collections: {
    directory: './src/collections',
    autoSync: true
  },
  plugins: {
    directory: './src/plugins',
    autoLoad: false
  }
}

export default createCfCmsApp(config)

2. Define Collections

// src/collections/blog-posts.collection.ts
import type { CollectionConfig } from '@ylstack-dev/cf-cms-core'

export default {
  name: 'blog-posts',
  displayName: 'Blog Posts',
  description: 'Manage your blog posts',

  schema: {
    type: 'object',
    properties: {
      title: {
        type: 'string',
        title: 'Title',
        required: true,
        maxLength: 200
      },
      content: {
        type: 'markdown',
        title: 'Content',
        required: true
      },
      publishedAt: {
        type: 'datetime',
        title: 'Published Date'
      },
      status: {
        type: 'select',
        title: 'Status',
        enum: ['draft', 'published', 'archived'],
        default: 'draft'
      }
    },
    required: ['title', 'content']
  }
} satisfies CollectionConfig

3. Configure Cloudflare Workers

# wrangler.toml
name = "my-cf-cms-app"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[[d1_databases]]
binding = "DB"
database_name = "my-cf-cms-db"
database_id = "your-database-id"
migrations_dir = "./node_modules/@ylstack-dev/cf-cms-core/migrations"

[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-cf-cms-media"

4. Start Development

# Run migrations
wrangler d1 migrations apply DB --local

# Start dev server
wrangler dev

Visit http://localhost:8787/admin to access the admin interface.

📚 Core Exports

Main Application

import { createCfCmsApp } from '@ylstack-dev/cf-cms-core'
import type { CfCmsConfig, CfCmsApp, Bindings, Variables } from '@ylstack-dev/cf-cms-core'

Services

import {
  loadCollectionConfigs,
  syncCollections,
  MigrationService,
  Logger,
  PluginService
} from '@ylstack-dev/cf-cms-core'

Middleware

import {
  requireAuth,
  requireRole,
  requirePermission,
  loggingMiddleware,
  cacheHeaders,
  securityHeaders
} from '@ylstack-dev/cf-cms-core'

Types

import type {
  CollectionConfig,
  FieldConfig,
  Plugin,
  PluginContext,
  User,
  Content,
  Media
} from '@ylstack-dev/cf-cms-core'

Templates

import {
  renderForm,
  renderTable,
  renderPagination,
  renderAlert
} from '@ylstack-dev/cf-cms-core'

Utilities

import {
  sanitizeInput,
  TemplateRenderer,
  QueryFilterBuilder,
  metricsTracker
} from '@ylstack-dev/cf-cms-core'

Database

import {
  createDb,
  users,
  collections,
  content,
  media
} from '@ylstack-dev/cf-cms-core'

🔌 Subpath Exports

The package provides organized subpath exports:

// Services only
import { MigrationService } from '@ylstack-dev/cf-cms-core/services'

// Middleware only
import { requireAuth } from '@ylstack-dev/cf-cms-core/middleware'

// Types only
import type { CollectionConfig } from '@ylstack-dev/cf-cms-core/types'

// Templates only
import { renderForm } from '@ylstack-dev/cf-cms-core/templates'

// Utilities only
import { sanitizeInput } from '@ylstack-dev/cf-cms-core/utils'

// Plugins only
import { HookSystemImpl } from '@ylstack-dev/cf-cms-core/plugins'

🎯 Usage Examples

Custom Routes

import { Hono } from 'hono'
import { requireAuth } from '@ylstack-dev/cf-cms-core/middleware'
import type { Bindings } from '@ylstack-dev/cf-cms-core'

const customRoutes = new Hono<{ Bindings: Bindings }>()

customRoutes.get('/api/custom', requireAuth(), async (c) => {
  const db = c.env.DB
  // Your custom logic
  return c.json({ message: 'Custom endpoint' })
})

// In your app config
export default createCfCmsApp({
  routes: [{ path: '/custom', handler: customRoutes }]
})

Custom Plugin

import type { Plugin } from '@ylstack-dev/cf-cms-core'

export default {
  name: 'my-plugin',
  version: '1.0.0',
  description: 'My custom plugin',

  async onActivate() {
    console.log('Plugin activated!')
  },

  hooks: {
    'content.beforeSave': async (content) => {
      // Transform content before saving
      content.metadata = { modified: new Date() }
      return content
    }
  }
} satisfies Plugin

Accessing Services

import { Logger, MigrationService } from '@ylstack-dev/cf-cms-core'

const logger = new Logger({ category: 'custom', level: 'info' })
logger.info('Application started')

const migrationService = new MigrationService(db)
await migrationService.runAllMigrations()

🏗️ Architecture

@ylstack-dev/cf-cms-core
├── src/
│   ├── app.ts              # Application factory
│   ├── db/                 # Database schemas & utilities
│   ├── services/           # Business logic
│   ├── middleware/         # Request processing
│   ├── routes/             # HTTP handlers
│   ├── templates/          # Admin UI components
│   ├── plugins/            # Plugin system & core plugins
│   ├── types/              # TypeScript definitions
│   └── utils/              # Utility functions
├── migrations/             # Core database migrations
└── dist/                   # Compiled output

🔄 Versioning

CfCms follows semantic versioning:

• v2.x.x - Current npm package (core extracted)
• v1.x.x - Legacy monolith (deprecated)

Current Version: 2.0.0-alpha.1

Upgrade Path

# Install the new package
npm install @ylstack-dev/[email protected]

# Run any new migrations
wrangler d1 migrations apply DB

# Test your application
npm run dev

📖 Documentation

• Getting Started
• API Reference
• Collections Guide
• Plugin Development
• Deployment

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md.

📄 License

MIT © CfCms Team - See LICENSE for details.

💬 Support & Community

• Issues: GitHub Issues
• Discord: Join our community
• Docs: docs.cf-cms.com
• Twitter: @cf-cmscms

🔖 Resources

• Create CfCms App - Scaffold a new project
• Cloudflare Workers Docs
• D1 Database
• R2 Storage

⚡ Performance

• Global edge deployment
• Sub-50ms response times
• Zero cold starts
• Automatic scaling
• Built-in caching

🛡️ Security

• JWT authentication
• Role-based access control (RBAC)
• Permission system
• Secure headers
• Input sanitization

Built with ❤️ for the edge | v2.0.0-alpha.1