How it works
Kiln has two parts:
| Part | What it is |
|---|---|
The kiln-cms package | Router 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
| Prefix | Auth | Use for |
|---|---|---|
/api/* | none | Public, read-only content |
/admin/* | Authorization: Bearer <accessToken> | Create, update, delete |
/auth/* | see Call the API | Setup, login, refresh, logout, me |
/files/* | none | Files from R2, when the bucket has no public domain |
/docs, /openapi.json | none | Interactive 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.
| Runtime | Entry | Data | Files |
|---|---|---|---|
| Cloudflare Workers | kiln-cms/cloudflare | D1 | R2 |
| Node.js 22.12+ | kiln-cms/node | SQLite file (libSQL) | a folder |
| Bun | kiln-cms/bun | SQLite 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.
- Set the name of the Worker, the database and the bucket in
wrangler.jsonc(default:kiln-cms). - Deploy. The first deploy creates the D1 database and the R2 bucket:
pnpm run deploy - Set the JWT secret (32 characters or more, random):
pnpm wrangler secret put JWT_SECRET - Create the tables. Run this again after every deploy that adds a migration:
pnpm db:migrate:remote - Create the first admin with
POST /auth/setupon 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)
- Copy the app to the server and install:
pnpm installorbun install. - Create
.envfrom.env.example:NODE_ENV=production, a randomJWT_SECRET(32+ characters),CORS_ALLOW_LIST. - Start it with
pnpm start:nodeorbun run start:bun, under systemd, pm2 or a container. - Create the first admin with
POST /auth/setupright away.
| Env var | Default | What it does |
|---|---|---|
PORT | 8787 | Port to listen on |
DATABASE_URL | file:./data/kiln.db | libSQL URL (a Turso URL works too, with DATABASE_AUTH_TOKEN) |
FILES_DIR | ./data/files | Folder of the uploaded files |
FILES_PUBLIC_URL | empty | Public base URL of the files; empty serves them at /files/* |
CLIENT_IP_HEADER | empty | Client 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.limitdefaults to 20, capped at 100. POST /auth/loginreturnsaccessToken(15 minutes) andrefreshToken.POST /auth/refreshwith{ "refreshToken": "..." }returns a new pair. The old refresh token stops working, so store the new one.POST /auth/logoutwith 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