EmDash + Cloudflare D1: Serverless Database Architecture
Full-stack architecture with EmDash CMS, Cloudflare D1, and R2. Binding configuration, seed.json, and local development explained.
WordPress is aging. There’s a modern CMS alternative built for the edge. EmDash is an open-source full-stack CMS designed for Astro, combining Cloudflare D1 (SQLite-compatible serverless DB) and R2 (object storage). This article explains the complete database architecture.
1. Architecture Overview#
EmDash architecture has four pillars:
| Component | Role |
|---|---|
| Astro | Framework, SSR/SSG, Live Collections |
| EmDash CMS | Admin UI, content model, REST API, plugins |
| Cloudflare D1 | SQL DB for content, settings, taxonomies, users, media metadata |
| Cloudflare R2 | Object storage for media files (images, uploads) |
2. Cloudflare D1: SQLite Serverless Database#
D1 is Cloudflare’s managed serverless database. SQLite SQL semantics with built-in disaster recovery and Worker/HTTP API access.
Key Specs#
| Item | Details |
|---|---|
| Engine | SQLite |
| Free Tier | 5M rows read/day, 100K rows written/day, up to 5GB |
| Paid Plan | 1DB up to 10GB, account up to 50,000DB (1TB total) |
| Time Travel | Point-in-time recovery to any minute in last 30 days |
| Global Read Replica | Beta: cross-region read replicas |
Why D1?#
- SQLite compatible : Existing SQLite knowledge works out of the box
- Serverless : No idle charges, pay only for queries and storage
- Edge delivery : Cloudflare’s global network for low latency
- EmDash official support :
emdash/dbprovidesd1()adapter
3. Binding Configuration: wrangler.jsonc#
D1 and R2 bindings are configured in wrangler.jsonc:
{
"name": "my-worker",
"compatibility_date": "2026-06-28",
// D1 Database Binding
"d1_databases": [
{
"binding": "DB", // access via env.DB
"database_name": "emdash-db", // human-readable name
"database_id": "xxxxxxxx-xxxx-xxxx-xxxx" // UUID from `wrangler d1 create`
}
],
// R2 Bucket Binding
"r2_buckets": [
{
"binding": "MEDIA", // access via env.MEDIA
"bucket_name": "emdash-media"
}
]
}jsoncBinding Flow#
[!NOTE] The
bindingname is used in code asenv.DB,env.MEDIA. If you rename it, update the code too.
4. EmDash DB Adapter#
EmDash specifies the DB adapter in astro.config.mjs:
import emdash from "emdash/astro";
import { d1 } from "emdash/db";
export default defineConfig({
integrations: [
emdash({
database: d1(), // Cloudflare D1 adapter
}),
],
});jsAvailable adapters:
| Adapter | Use Case |
|---|---|
d1() | Cloudflare D1 (serverless) |
sqlite() | Local SQLite (development) |
libsql() | LibSQL/Turso |
postgresql() | PostgreSQL |
5. seed.json: Schema Source of Truth#
seed/seed.json is the bootstrap document for an EmDash site. Defines collections, fields, taxonomies, menus, redirects, widget areas, and site settings.
seed.json Structure#
{
"$schema": "https://emdashcms.com/seed.schema.json",
"version": "1",
"meta": {
"name": "My Blog",
"description": "Blog powered by EmDash + D1"
},
"settings": {
"title": "My Blog",
"postsPerPage": 10
},
"collections": [
{
"name": "posts",
"fields": [
{ "name": "title", "type": "string" },
{ "name": "body", "type": "portabletext" }
]
}
],
"taxonomies": [],
"menus": [],
"redirects": [],
"widgetAreas": [],
"content": {}
}jsonApplication Rules#
| Operation | Behavior |
|---|---|
| Collections, Settings | upsert — update if exists, create if not |
| Menus, Widgets | replace — overwrite completely with seed |
| Content entries | skip — skip if slug already exists |
How to Apply#
# Apply via CLI
npx emdash seed seed/seed.json
# Export existing schema
npx emdash export-seed > .emdash/seed.json
# Export with content
npx emdash export-seed --with-content > .emdash/seed.jsonbash[!TIP] seed.json auto-applies on “first request” when the database is empty. During development, applying explicitly via CLI is safer.
6. Local Development: Miniflare + SQLite#
Local development uses Miniflare (Cloudflare’s local simulator).
Storage Path#
.wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlitetext| Item | Description |
|---|---|
<hash> | Hex hash derived from database_id |
| File format | SQLite compatible (connect directly with better-sqlite3) |
| Persistence | Data persists between wrangler dev sessions |
| Local/Remote | Fully separated with --local / --remote flags |
Local Dev Flow#
# Apply seed to local D1
npx emdash seed seed/seed.json --local
# Start dev server
wrangler dev
# Check local DB
ls .wrangler/state/v3/d1/miniflare-D1DatabaseObject/bash[!NOTE] Local DB and remote DB are fully separated. Use
--localand--remoteto distinguish.
7. Complete Data Flow#
8. Summary#
| Component | Role | File |
|---|---|---|
| D1 | Content DB | wrangler.jsonc (Binding config) |
| R2 | Media storage | wrangler.jsonc (Binding config) |
| EmDash | CMS layer | astro.config.mjs (d1() adapter) |
| seed.json | Schema source of truth | seed/seed.json |
| Miniflare | Local DB | .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite |
EmDash + D1 + R2 combines into a serverless, scalable CMS architecture. Free from WordPress server management, delivered at edge speed.