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/                        # folder = content type ID
│   ├── hello-world.md           # file = one entry
│   └── our-mission.md
├── siteSettings/
│   └── index.md                 # singletons use index.md
└── media/                       # optional local images
    └── hero-banner.jpg

Markdown files with frontmatter:

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

## Who We Are

Rich text body, stored as 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