koguma

Koguma

A little CMS with big heart — schema-driven content management that runs entirely on Cloudflare's free tier.

Koguma gives you a headless CMS with a beautiful admin dashboard, all powered by Cloudflare Workers + D1 + R2. Define your content types in code, and Koguma handles the rest — API routes, admin UI, media storage, and a file-based content/ directory for version-controlled content.

Quickstart

1. Install

bun add koguma
# or
npm install koguma

2. Define your content

Create a site.config.ts in your project root:

import { defineConfig, contentType, field } from 'koguma';

export default defineConfig({
  siteName: 'My Site',
  contentTypes: [
    contentType({
      id: 'post',
      name: 'Blog Post',
      displayField: 'title',
      fields: {
        title: field.text('Title').required(),
        slug: field.text('Slug').required(),
        body: field.markdown('Body'),
        heroImage: field.image('Hero Image'),
        published: field.boolean('Published').default(false),
        date: field.date('Published Date')
      }
    })
  ]
});

3. Create your worker

Create a worker.ts:

import { createWorker } from 'koguma/worker';
import config from './site.config';

export default createWorker(config);

4. Configure

Create koguma.toml:

name = "my-site"
database_id = ""    # filled by `koguma init`

That's it — two lines. Everything else is derived by convention:

• D1 database → my-site-db
• R2 bucket → my-site-media
• Worker name → my-site

5. Deploy

koguma init    # Scaffold project, create D1 + R2 on Cloudflare
koguma push    # Build + deploy + sync content

Your admin dashboard is at /admin. Your API is at /api/content/:type.

Content Schema

Field Types

Field	Usage	Stored As
field.text(label)	Titles, slugs, URLs	TEXT
field.longText(label)	Descriptions, bios	TEXT
field.markdown(label)	Rich formatted content	TEXT (markdown string)
field.number(label)	Counts, order	number in JSON
field.boolean(label)	Toggles	boolean in JSON
field.date(label)	Timestamps	string (ISO 8601)
field.select(label, {options})	Dropdowns	string
field.url(label)	URLs	string
field.email(label)	Email addresses	string
field.phone(label)	Phone numbers	string
field.color(label)	Hex colours	string
field.youtube(label)	YouTube video IDs	string
field.instagram(label)	Instagram handles	string
field.image(label)	Image from R2 media	string (asset ID)
field.images(label)	Array of images	string[] (asset IDs)
field.ref(typeId, label)	Link to another entry	string (entry ID)
field.refs(typeId, label)	Array of entry links	string[] (entry IDs)

All fields stored inside a JSON data blob in the entries table — no per-field columns, no migrations.

Content Type Options

contentType({
  id: "page",
  name: "Page",
  displayField: "title",
  singleton: true,           // Only one entry allowed (e.g. site settings)
  fields: { ... },
});

CLI Reference

All commands auto-detect your project root by looking for koguma.toml.

Command	Description
koguma init	Interactive project setup — scaffold, create D1 + R2, set secret
koguma dev	Auto-sync content/ → local D1, generate types, start dev server
koguma push	Build + deploy + sync content to remote
koguma pull	Download remote content + media → local content/ files
koguma gen-types	Generate koguma.d.ts typed interfaces
koguma tidy	Validate content/ against config, sync dirs, check fields

Content Directory

Koguma uses a content/ directory for file-based content that lives in your git repo:

content/
├── post/                          # collection — one file per entry
│   ├── hello-world.md             # slug = "hello-world"
│   ├── our-mission.md
│   └── our-mission.heroBody.md    # sibling markdown field
├── landingPage/                   # singleton — always index.md
│   ├── index.md                   # slug = content type ID
│   ├── heroBody.md                # sibling markdown field
│   └── ctaBody.md                 # sibling markdown field
└── media/                         # local images (synced to R2)
    └── hero-banner.jpg

File Format

Every content file uses YAML frontmatter + markdown body:

---
title: Our Mission
slug: our-mission
heroImage: media-hero-banner
published: true
date: 2026-03-01
---

This body content maps to the **first** `field.markdown()` in the content type.

Singletons vs Collections

• Collections (default): Each entry is a file named {slug}.md
• Singletons (singleton: true): One entry, always index.md. The slug is auto-set to the content type ID.

Sibling Markdown Fields

When a content type has multiple field.markdown() fields, the first one maps to the file body. Additional markdown fields are stored as sibling files (pure markdown, no frontmatter):

	Collections	Singletons
Main file	{slug}.md	index.md
Sibling pattern	{slug}.{fieldId}.md	{fieldId}.md

Example singleton with 3 markdown fields:

content/landingPage/
├── index.md           # frontmatter + 1st markdown field body
├── heroBody.md        # 2nd markdown field (pure markdown)
└── ctaBody.md         # 3rd markdown field (pure markdown)

Git is your version history. No custom versioning table needed.

API Routes

Public (no auth)

Method	Route	Description
GET	/api/content/:type	List all entries of a content type
GET	/api/content/:type/:id	Get a single entry (with resolved refs)
GET	/api/media/:key	Serve a media file from R2

Admin (auth required)

Method	Route	Description
POST	/api/auth/login	Login with { password }
POST	/api/auth/logout	Clear session
GET	/api/auth/me	Check authentication
GET	/api/admin/schema	Content type schemas (for admin UI)
GET	/api/admin/:type	List entries
GET	/api/admin/:type/:id	Get entry
POST	/api/admin/:type	Create entry
PUT	/api/admin/:type/:id	Update entry
DELETE	/api/admin/:type/:id	Delete entry
GET	/api/admin/media	List media assets
POST	/api/admin/media	Upload media (multipart form)
DELETE	/api/admin/media/:id	Delete media

References and images are automatically resolved to nested objects in the public API (up to 2 levels deep).

Package Exports

import { defineConfig, contentType, group, field, type Infer } from 'koguma';
import { createWorker } from 'koguma/worker';
import { createClient } from 'koguma/client';
import { Markdown, useEntry, useEntries } from 'koguma/react';
import type { KogumaAsset, EntryReference } from 'koguma/types';

Local Development

# Create .dev.vars with your local admin password
echo "KOGUMA_SECRET=your-password" > .dev.vars

# Start dev server (auto-syncs content/, generates types)
koguma dev

# Admin dashboard is at http://localhost:8787/admin
# API is at http://localhost:8787/api/content/:type

Architecture

Your Project
├── site.config.ts     ← Content type definitions
├── worker.ts          ← Entry point (imports koguma/worker)
├── koguma.toml        ← Project config (name + database_id)
├── .dev.vars          ← Local secrets (KOGUMA_SECRET)
└── content/           ← Version-controlled content files
    ├── post/
    │   └── hello-world.md
    └── siteSettings/
        └── index.md

Koguma (this package)
├── src/
│   ├── config/        ← Schema definitions (defineConfig, field types)
│   ├── api/           ← Hono router (CRUD + media + auth)
│   ├── db/            ← D1 queries (JSON document store)
│   ├── auth/          ← HMAC-signed cookie sessions
│   ├── media/         ← R2 upload/serve/delete
│   ├── admin/         ← Dashboard HTML shell + JS/CSS bundle
│   ├── client/        ← Fetch client for consuming the API
│   └── react/         ← React hooks + <Markdown> component
├── admin/             ← Vite + React admin dashboard source
└── cli/               ← CLI commands (init, dev, push, pull, gen-types, tidy)

License

MIT