Kiln CMS
Kiln CMS logo

Kiln CMS

A small headless CMS on Hono and Drizzle (SQLite). Write the app once, run it on Cloudflare Workers, Node.js or Bun. Your frontends are separate projects that call its JSON API.

pnpm add kiln-cms

How it works

Kiln has two parts:

PartWhat it is
The kiln-cms packageRouter and response helpers, errors, middleware, change hooks, login (/auth), users and the kiln command-line tool. You upgrade it with pnpm update kiln-cms.
The app (template/)A starter built on the package: posts, categories, tags, media, the route map, the migrations and one entry per runtime. You copy it and make it your own.

Routes

PrefixAuthUse for
/api/*nonePublic, read-only content
/admin/*Authorization: Bearer <accessToken>Create, update, delete
/auth/*see Call the APISetup, login, refresh, logout, me
/files/*noneFiles from R2, when the bucket has no public domain
/docs, /openapi.jsonnoneInteractive API reference and OpenAPI document

Runtimes

The app lives in src/app.ts. A one-line entry per runtime picks where it runs. All three use SQLite, so the schema and the migrations are the same everywhere.

RuntimeEntryDataFiles
Cloudflare Workerskiln-cms/cloudflareD1R2
Node.js 22.12+kiln-cms/nodeSQLite file (libSQL)a folder
Bunkiln-cms/bunSQLite file (libSQL)a folder
// src/worker.ts (Cloudflare)
import { createWorker } from 'kiln-cms/cloudflare'
import { appOptions } from './app'
export default createWorker(appOptions)

// src/server.ts (Node.js) or src/server.bun.ts (Bun)
import { serve } from 'kiln-cms/node' // or 'kiln-cms/bun'
import { appOptions } from './app'
await serve(appOptions)

Code inside the app never touches a runtime API: files go through getStorage(), vars through getEnv().

Quick start

You need Node.js and pnpm (or Bun). Copy the template/ folder into a new repo, then run one of:

# Cloudflare (local Workers runtime)
cp .dev.vars.example .dev.vars
pnpm install
pnpm db:migrate:local
pnpm dev

# Node.js
cp .env.example .env
pnpm install
pnpm dev:node

# Bun
cp .env.example .env
bun install
bun run dev:bun

On Node.js and Bun the server applies the migrations at startup and keeps everything in data/.

The API runs at http://localhost:8787. Open http://localhost:8787/docs for the reference.

Create the first admin once, then log in:

curl -s -X POST http://localhost:8787/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"..."}'

curl -s -X POST http://localhost:8787/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"..."}'

Deploy to Cloudflare

You need a Cloudflare account and pnpm wrangler login.

  1. Set the name of the Worker, the database and the bucket in wrangler.jsonc (default: kiln-cms).
  2. Deploy. The first deploy creates the D1 database and the R2 bucket:
    pnpm run deploy
  3. Set the JWT secret (32 characters or more, random):
    pnpm wrangler secret put JWT_SECRET
  4. Create the tables. Run this again after every deploy that adds a migration:
    pnpm db:migrate:remote
  5. Create the first admin with POST /auth/setup on the deployed URL.

Do step 5 right away: /auth/setup is open until the first user exists.

Settings

In wrangler.jsonc under vars:

  • CORS_ALLOW_LIST: origins allowed to call the API from a browser, separated by |. The default * allows every origin; list your frontends in production.
  • FILES_PUBLIC_URL: public base URL of the bucket (custom domain). Empty serves files through the Worker at /files/*.

Deploy on a server (Node.js or Bun)

  1. Copy the app to the server and install: pnpm install or bun install.
  2. Create .env from .env.example: NODE_ENV=production, a random JWT_SECRET (32+ characters), CORS_ALLOW_LIST.
  3. Start it with pnpm start:node or bun run start:bun, under systemd, pm2 or a container.
  4. Create the first admin with POST /auth/setup right away.
Env varDefaultWhat it does
PORT8787Port to listen on
DATABASE_URLfile:./data/kiln.dblibSQL URL (a Turso URL works too, with DATABASE_AUTH_TOKEN)
FILES_DIR./data/filesFolder of the uploaded files
FILES_PUBLIC_URLemptyPublic base URL of the files; empty serves them at /files/*
CLIENT_IP_HEADERemptyClient IP header behind a proxy (X-Forwarded-For...), for the rate limits

SQLite is one file on one machine: run one server process, keep data/ on a persistent disk and back it up.

Call the API

Every response has success and requestId. Lists add pagination; errors carry an error object with a code to branch on.

{ "success": true, "data": [], "pagination": { "total": 42, "page": 1, "limit": 20, "totalPages": 3, "hasMore": true }, "requestId": "..." }
{ "success": false, "error": { "code": "NOT_FOUND", "message": "Category not found" }, "requestId": "..." }
  • Page through lists with ?page=2&limit=10. limit defaults to 20, capped at 100.
  • POST /auth/login returns accessToken (15 minutes) and refreshToken.
  • POST /auth/refresh with { "refreshToken": "..." } returns a new pair. The old refresh token stops working, so store the new one.
  • POST /auth/logout with the refresh token ends that session.
const BASE = 'https://cms.example.com'

const res = await fetch(`${BASE}/admin/categories`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'News', slug: 'news' }),
})
const body = await res.json()
if (!body.success) throw new Error(body.error.message)

Full walkthrough: Call the API.

Extend

Content types are code: add a table, generate a migration, deploy.

pnpm gen:module products product
pnpm db:generate
pnpm db:migrate:local

Upgrade

pnpm update kiln-cms
pnpm db:generate
pnpm check

pnpm db:generate creates a migration when the new version changed the package's tables (users, sessions, rate_limits). On Cloudflare apply it with pnpm db:migrate:remote after you deploy; Node.js and Bun apply it at the next start.

From 0.2: createWorker moved to kiln-cms/cloudflare, files go through getStorage() instead of getEnv().BUCKET, and R2_PUBLIC_URL is now FILES_PUBLIC_URL (the old name is still read).

Scope

Kiln stays small on purpose. It does not have, and does not plan:

  • an admin UI (each site brings its own; the API is described at /openapi.json)
  • content types created at runtime
  • runtime plugins (extend with modules and change hooks)
  • databases other than SQLite