emdash Documentation

```js title="astro.config.mjs"
import { aiSearch } from "@emdash-cms/cloudflare/plugins";

// ...
plugins: [
	formsPlugin(),
	aiSearch(),
],
```

2. Add the AI Search namespace binding to your Worker configuration:

   jsonc title="wrangler.jsonc" Copy

   {
       "ai_search_namespaces": [
           {
               "binding": "AI_SEARCH",
               "namespace": "default",
           },
       ],
   }

3. Create the search endpoint used by the search interface:

   ts title="src/pages/api/ai-search/search.ts" Copy

   export { POST, prerender } from "@emdash-cms/cloudflare/plugins/ai-search";

4. Add the search interface to your site layout. The trigger slot can contain any button that fits your site's design:

   astro title="src/layouts/base.astro" Copy

   ---
   import AISearchSnippet from "@emdash-cms/cloudflare/plugins/ai-search/astro";
   ---
   
   <AISearchSnippet apiUrl="/api/ai-search" placeholder="Search...">
       Search
   </AISearchSnippet>

5. Deploy the site:

   bash Copy

   pnpm exec wrangler deploy

6. Open Cloudflare AI Search in the EmDash admin panel, select the collections to index, and click Sync All Content.

   This initial sync is required: the plugin's content hooks only fire for content created or updated after it was enabled, so anything published beforehand stays missing from the index until you run a full sync.

Content published or updated after setup is kept in sync automatically. The same page shows indexing progress.

Email Copy Chapter

On Workers, the only built-in email:deliver handler is a dev console stub, so
email-dependent flows — magic-link login, team invites, and comment
notifications — fail with "Email is not configured" in production. The
cloudflareEmail() plugin delivers real email through
Cloudflare Email Sending
using a native send_email Worker binding, with no external API keys.

1. Onboard a sender domain Copy Section

In the Cloudflare dashboard, go to Email and verify the domain (or address)
you send from. Email Sending rejects messages from unverified senders.

2. Add the binding Copy Section

Declare a send_email binding in wrangler.jsonc:

{
	"send_email": [{ "name": "EMAIL" }],
}

3. Register the provider Copy Section

Add the plugin to your emdash() integration:

import { d1, r2 } from "@emdash-cms/cloudflare";
import { cloudflareEmail } from "@emdash-cms/cloudflare/plugins";

emdash({
	database: d1({ binding: "DB" }),
	storage: r2({ binding: "MEDIA" }),
	plugins: [
		cloudflareEmail({
			from: { email: "[email protected]", name: "My Site CMS" },
			replyTo: "[email protected]", // optional
			binding: "EMAIL", // optional, defaults to "EMAIL"
		}),
	],
}),

4. Activate and select it Copy Section

Deploy, then activate the plugin under Admin → Extensions and choose it as
the provider under Settings → Email.

Options

Environment Variables Copy Chapter

Recommended: encryption key Copy Section

EMDASH_ENCRYPTION_KEY is the key for encrypting plugin secrets at
rest (webhook tokens, Turnstile keys, etc.). The key is validated on
startup; plugin secret encryption uses it once enabled. Set it on
every deployment so secrets are protected without a later config
change.

The key is provided by you and never stored in the database; only
encrypted ciphertext is. Losing it means losing every secret encrypted
with it.

Generate a key and store it as a Worker secret with the following commands:

npx emdash secrets generate
wrangler secret put EMDASH_ENCRYPTION_KEY

Optional: stable-value overrides Copy Section

EmDash auto-generates the preview HMAC secret and commenter-IP hash
salt and persists them in the database on first use. The env vars
below are overrides for cases where you need to pin the value
yourself — for example, when a preview Worker in a separate process
needs to share the secret with your main site.

Access environment variables in your configuration using import.meta.env or the Cloudflare env binding.

For the complete inventory of every secret EmDash uses — including storage locations, rotation steps, and what breaks when a key is lost — see Secrets & Key Management.

Preview Deployments Copy Chapter

Deploy a preview branch:

wrangler deploy --env preview

Add an environment section to wrangler.jsonc:

{
	"env": {
		"preview": {
			"d1_databases": [
				{
					"binding": "DB",
					"database_name": "emdash-db-preview",
				},
			],
		},
	},
}

Troubleshooting Copy Chapter

"D1 binding not found" Copy Section

Verify the binding name in wrangler.jsonc matches your database configuration:

// Must match: d1({ binding: "DB" })
"binding": "DB"

"R2 binding not found" Copy Section

Check that the R2 bucket is correctly bound:

// Must match: r2({ binding: "MEDIA" })
"binding": "MEDIA"

Migration errors Copy Section

If you see schema errors, tail the Worker logs (wrangler tail) and reproduce the error to capture the underlying message — then file an issue with that output.

File: docs/src/content/docs/deployment/database.mdx Copy Chapter

title: Database Options Copy Chapter

import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";

EmDash supports multiple database backends. Choose based on your deployment target.

Overview Copy Chapter

Cloudflare D1 Copy Chapter

D1 is Cloudflare's serverless SQLite database. Use it when deploying to Cloudflare Workers.

import { d1 } from "@emdash-cms/cloudflare";

export default defineConfig({
	integrations: [
		emdash({
			database: d1({ binding: "DB" }),
		}),
	],
});

Configuration Copy Section

Setup Copy Section

Read Replicas Copy Section

D1 supports read replication to lower read latency for globally distributed sites. When enabled, read queries are routed to nearby replicas instead of always hitting the primary database.

EmDash uses the D1 Sessions API to manage this transparently. Enable it with the session option:

import { d1 } from "@emdash-cms/cloudflare";

export default defineConfig({
	integrations: [
		emdash({
			database: d1({
				binding: "DB",
				session: "auto",
			}),
		}),
	],
});

Session Modes

How It Works

• Anonymous visitors get first-unconstrained — reads go to the nearest replica for the lowest latency. Since anonymous users never write, they don't need consistency guarantees.
• Authenticated users (editors, authors) get bookmark-based sessions. After a write, a bookmark cookie ensures the next request sees at least that state.
• Write requests (POST, PUT, DELETE) always start at the primary database.
• Build-time queries (Astro content collections) bypass sessions entirely and use the primary directly.

libSQL Copy Chapter

libSQL is a fork of SQLite that supports remote connections. Use it when you need a remote database without Cloudflare D1.

import { libsql } from "emdash/db";

export default defineConfig({
	integrations: [
		emdash({
			database: libsql({
				url: process.env.LIBSQL_DATABASE_URL,
				authToken: process.env.LIBSQL_AUTH_TOKEN,
			}),
		}),
	],
});

Configuration Copy Section

Local Development Copy Section

Use a local libSQL file during development:

database: libsql({ url: "file:./data.db" });

PostgreSQL Copy Chapter

PostgreSQL is supported for Node.js deployments that need a full relational database.

import { postgres } from "emdash/db";

export default defineConfig({
	integrations: [
		emdash({
			database: postgres({
				connectionString: process.env.DATABASE_URL,
			}),
		}),
	],
});

Configuration Copy Section

You can connect with a connection string or individual parameters:

// Connection string
database: postgres({
	connectionString: "postgres://user:password@localhost:5432/emdash",
});

// Individual parameters
database: postgres({
	host: "localhost",
	port: 5432,
	database: "emdash",
	user: "emdash",
	password: process.env.DB_PASSWORD,
	ssl: true,
});

Database role requirements Copy Section

EmDash creates and updates its own PostgreSQL tables. Core migrations create and alter system and collection tables, content types create ec_* tables, and adding or removing a field alters its collection table. The configured PostgreSQL role therefore needs schema authority for the lifetime of the site, not only during initial setup.

Use one canonical role for EmDash. It needs:

• CONNECT on the database;
• USAGE and CREATE on the active schema;
• ownership of every EmDash table and function, either directly or through membership with INHERIT in the owning role; and
• SELECT, INSERT, UPDATE, and DELETE on those tables.

It does not need to be a superuser, have CREATEDB or CREATEROLE, or create extensions. PostgreSQL does not provide an ALTER or DROP table grant: those operations belong to the object owner and roles that inherit its privileges. Granting ALL on a table to a different role does not make that role an owner. EmDash does not run SET ROLE, so membership configured without inheritance is not sufficient.

Most installations can use the database's existing schema, commonly public. This is the simplest option when the database is dedicated to EmDash. In the examples below, emdash_app is the login role in EmDash's connection string; use an existing provider role or create a dedicated login. Grant it access with an administrative connection, substituting your database, schema, and role names:

GRANT CONNECT ON DATABASE app TO emdash_app;
GRANT USAGE, CREATE ON SCHEMA public TO emdash_app;

These grants let the role create new objects. They do not change the owner of existing tables; see Repair mixed PostgreSQL ownership.

EmDash uses PostgreSQL's active current_schema(). It does not create a schema or set search_path, so verify the connection before deployment:

SELECT
  current_database(),
  session_user,
  current_user,
  current_schema(),
  current_setting('search_path');

Optional: use a dedicated schema

Use a dedicated schema when EmDash shares a database with another application or when you want its objects isolated from public. This is optional and is easiest to configure before the first EmDash setup. A database dedicated to EmDash does not need a separate schema.

Assuming the canonical emdash_app role already exists, create and select its schema with an administrative connection:

GRANT CONNECT ON DATABASE app TO emdash_app;
CREATE SCHEMA emdash AUTHORIZATION emdash_app;
ALTER ROLE emdash_app IN DATABASE app SET search_path = emdash;

This does not move an existing installation from public or repair mixed ownership. Existing sites should keep their current schema and follow Repair mixed PostgreSQL ownership instead.

Connection Pooling Copy Section

The adapter uses pg.Pool under the hood. Tune pool size based on your deployment:

database: postgres({
	connectionString: process.env.DATABASE_URL,
	pool: { min: 2, max: 20 },
});

Hyperdrive Copy Chapter

Use the hyperdrive() adapter to run EmDash on Cloudflare Workers backed by an existing PostgreSQL — or Postgres-compatible (e.g. PlanetScale Postgres) — database. Hyperdrive pools and accelerates the connection over Cloudflare's network; EmDash's PostgreSQL dialect runs the queries.

import { hyperdrive, r2 } from "@emdash-cms/cloudflare";

export default defineConfig({
	integrations: [
		emdash({
			database: hyperdrive({ binding: "HYPERDRIVE" }),
			storage: r2({ binding: "MEDIA" }),
		}),
	],
});

Requirements Copy Section

• pg >= 8.16.3 installed in your site (pnpm add pg)
• compatibility_flags: ["nodejs_compat"]
• compatibility_date >= "2024-09-23"

Setup Copy Section

First prepare the PostgreSQL role. Then create the Hyperdrive configuration with that role's connection string and add the binding to your Wrangler config:

wrangler hyperdrive create emdash-db \
  --connection-string "postgres://user:password@host/db?sslmode=verify-full" \
  --caching-disabled

Configuration Copy Section

*Default 60000 applies only when cachedBinding is set; ignored otherwise.

Serving anonymous reads from cache Copy Section

By default you disable Hyperdrive caching entirely, because the admin and writes need read-after-write consistency. But anonymous public requests using GET or HEAD can tolerate a short staleness window. If that trade-off is acceptable, run two Hyperdrive configurations over the same database: one with caching off (the primary binding) and one with caching on (cachedBinding). EmDash routes those anonymous public requests through the cache-enabled binding and every other request through the uncached primary.

# Primary — caching OFF (used by admin, auth'd requests, writes, migrations)
wrangler hyperdrive create emdash-db \
  --connection-string "postgres://user:password@host/db?sslmode=verify-full" \
  --caching-disabled

# Cached — SAME database role and connection string, caching ON
wrangler hyperdrive create emdash-db-cached \
  --connection-string "postgres://user:password@host/db?sslmode=verify-full"

{
	"hyperdrive": [
		{ "binding": "HYPERDRIVE", "id": "<caching-disabled-id>" },
		{ "binding": "HYPERDRIVE_CACHED", "id": "<caching-enabled-id>" }
	]
}

database: hyperdrive({ binding: "HYPERDRIVE", cachedBinding: "HYPERDRIVE_CACHED" });

This is the two-configuration pattern Cloudflare documents for caching. EmDash decides which binding to use per request:

• Anonymous reads of public-site paths (GET/HEAD, no session, not under /_emdash) → cache-enabled cachedBinding, except for a short window after a content publish (default 60s; set preferUncachedAfterWriteMs to your Hyperdrive max_age) when EmDash prefers the uncached binding so a rebuild cannot reseed edge/object caches from still-stale Hyperdrive results.
• Authenticated requests (editors, authors) → uncached binding.
• Mutation requests (POST, PUT, PATCH, DELETE, including anonymous ones) → uncached binding.
• Any request under /_emdash (admin, setup, auth, internal APIs), even an anonymous GET → uncached binding.
• Runtime migrations and cold-start → always the primary binding.
• Deployment-managed migrations → connect directly to the PostgreSQL origin using migrationConnectionStringEnv; they never use either Hyperdrive binding.

Optional: use a separate cached role

Migrations, setup, authenticated requests, and explicit write requests always use the primary binding. A separate role for cachedBinding does not need schema ownership or CREATE, but it needs CONNECT, schema USAGE, and SELECT on every table used by the public site.

Anonymous public GET and HEAD requests can also record redirect hits and 404s. To preserve those features, the cached role additionally needs UPDATE on _emdash_redirects and SELECT, INSERT, UPDATE, and DELETE on _emdash_404_log. Plugins or application code that writes during a public GET or HEAD may require more. Use the same role for both bindings unless you have tested the site with a restricted cached role.

Add the cached role after EmDash has completed its initial migrations. The examples below use the optional emdash schema; substitute your active schema, such as public. Create the login and database settings with your provider's administrative role:

CREATE ROLE emdash_cached LOGIN PASSWORD 'replace-with-a-secret';
GRANT CONNECT ON DATABASE app TO emdash_cached;
ALTER ROLE emdash_cached IN DATABASE app SET search_path = emdash;

Then connect as emdash_app, the schema and table owner, to grant access to existing and future tables:

GRANT USAGE ON SCHEMA emdash TO emdash_cached;
GRANT SELECT ON ALL TABLES IN SCHEMA emdash TO emdash_cached;
GRANT UPDATE ON emdash._emdash_redirects TO emdash_cached;
GRANT SELECT, INSERT, UPDATE, DELETE ON emdash._emdash_404_log TO emdash_cached;

ALTER DEFAULT PRIVILEGES IN SCHEMA emdash
  GRANT SELECT ON TABLES TO emdash_cached;

Connect with both roles and verify they report the same current_database() and current_schema() before enabling cachedBinding. On a shared schema, GRANT SELECT ON ALL TABLES also exposes unrelated tables. Grant access to individual EmDash tables instead, and update those grants when collections or other schema objects are added.

Repair mixed PostgreSQL ownership Copy Chapter

If a site has used multiple PostgreSQL users, first choose the canonical role that the primary EmDash connection will continue using. Take a backup and stop schema changes while repairing ownership.

Inspect every table in the active schema:

SELECT
  n.nspname AS schema_name,
  c.relname AS table_name,
  pg_get_userbyid(c.relowner) AS owner
FROM pg_class AS c
JOIN pg_namespace AS n ON n.oid = c.relnamespace
WHERE n.nspname = current_schema()
  AND c.relkind IN ('r', 'p')
ORDER BY c.relname;

EmDash objects include _emdash_* and _plugin_* system tables, ec_* collection tables, and unprefixed tables such as content_taxonomies, media, options, revisions, and taxonomies. In a dedicated EmDash schema, every application table should have the canonical owner.

EmDash also creates PostgreSQL functions used by media-usage triggers. Inspect function ownership and retain each function's argument signature for the repair command:

SELECT
  n.nspname AS schema_name,
  p.proname AS function_name,
  pg_get_function_identity_arguments(p.oid) AS arguments,
  pg_get_userbyid(p.proowner) AS owner
FROM pg_proc AS p
JOIN pg_namespace AS n ON n.oid = p.pronamespace
WHERE n.nspname = current_schema()
ORDER BY p.proname, arguments;

Transfer each mismatched object with a superuser or provider role that can change its ownership, always using schema-qualified names:

ALTER TABLE emdash.content_taxonomies OWNER TO emdash_app;
ALTER TABLE emdash.ec_posts OWNER TO emdash_app;
ALTER FUNCTION emdash.emdash_media_usage_capture_work() OWNER TO emdash_app;

Use the argument list returned by the inventory query inside each ALTER FUNCTION statement. Changing a table's owner also covers its attached indexes, constraints, and triggers, but not their independent trigger functions. Repeat both inventory queries until every EmDash table and function reports the canonical owner, then connect as that role and verify current_schema() before starting the application.

For a non-superuser to transfer ownership, it must own or inherit ownership of the object, be able to SET ROLE to the new owner, and the new owner must have CREATE on the schema. Managed PostgreSQL providers may require their administrative role to perform the transfer.

SQLite Copy Chapter

SQLite with better-sqlite3 is the simplest option for Node.js deployments.

import { sqlite } from "emdash/db";

export default defineConfig({
	integrations: [
		emdash({
			database: sqlite({ url: "file:./data.db" }),
		}),
	],
});

Configuration Copy Section

File Path Copy Section

The url must start with file::

// Relative path
database: sqlite({ url: "file:./data/emdash.db" });

// Absolute path
database: sqlite({ url: "file:/var/data/emdash.db" });

// From environment variable
database: sqlite({ url: `file:${process.env.DATABASE_PATH}` });

Migrations Copy Chapter

EmDash runs core migrations automatically by default for every supported dialect. Astro build and sync also emit a validated, secret-free .emdash/migrations.json, which emdash migrate can apply before deployment. SQLite, libSQL, PostgreSQL, D1, and the direct PostgreSQL origin behind Hyperdrive have deployment executors.

See Manage Core Database Migrations for target credentials, CI serialization, auto/check/manual runtime policy, and recovery from unknown records or ambiguous D1 writes.

For PostgreSQL, runtime migrations run through the configured connection; Hyperdrive runtime migrations always use its primary binding. Deployment-managed Hyperdrive migrations connect directly to the PostgreSQL origin. Core migrations may create tables, indexes, and functions, alter or drop columns and constraints, and update existing rows. A role that can connect and modify rows but does not own the existing EmDash objects is not sufficient. The setup wizard cannot repair missing database privileges because runtime migrations run before setup.

If the database is empty (no collections) and the setup wizard has not been completed, EmDash also applies a seed file on first boot. The seed is read from .emdash/seed.json, the path in package.json#emdash.seed, or seed/seed.json — whichever is found first — and inlined into the build at compile time. If none is present, a built-in default seed is used. Subsequent boots against an existing database leave its content alone.

Environment-Based Configuration Copy Chapter

Use different databases per environment:

import { sqlite, libsql, postgres } from "emdash/db";
import { d1 } from "@emdash-cms/cloudflare";

const database = import.meta.env.PROD ? d1({ binding: "DB" }) : sqlite({ url: "file:./data.db" });

export default defineConfig({
	integrations: [emdash({ database })],
});

The choice can also key off an environment variable instead of the build mode:

const database = process.env.DATABASE_URL
	? postgres({ connectionString: process.env.DATABASE_URL })
	: sqlite({ url: "file:./data.db" });

File: docs/src/content/docs/deployment/nodejs.mdx Copy Chapter

title: Deploy to Node.js Copy Chapter

import { Aside, Steps, Tabs, TabItem } from "@astrojs/starlight/components";

EmDash runs on any Node.js 22+ hosting platform. This guide uses SQLite with local or S3-compatible storage; libSQL and PostgreSQL work the same way on Node.js — see Database Options.

Prerequisites Copy Chapter

• Node.js v22.12.0 or higher
• A Node.js hosting provider or VPS

Configuration Copy Chapter

Configure EmDash for Node.js deployment:

import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import emdash, { local, s3 } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	output: "server",
	adapter: node({ mode: "standalone" }),
	integrations: [
		emdash({
			database: sqlite({ url: "file:./data/emdash.db" }),
			storage: local({
				directory: "./data/uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

Build and Run Copy Chapter

1. Build the project:

   bash Copy

   npm run build

2. Start the server:

   bash Copy

   node ./dist/server/entry.mjs

The server runs on http://localhost:4321 by default. Migrations are applied on the first request. If the database is empty and setup hasn't been completed, your seed file (or the built-in default if you don't have one) is also applied on that first request.

Production Storage Copy Chapter

For production, use S3-compatible storage instead of local filesystem:

import emdash, { s3 } from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			database: sqlite({ url: `file:${process.env.DATABASE_PATH}` }),
			storage: s3({
				endpoint: process.env.S3_ENDPOINT,
				bucket: process.env.S3_BUCKET,
				accessKeyId: process.env.S3_ACCESS_KEY_ID,
				secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
				publicUrl: process.env.S3_PUBLIC_URL, // Optional CDN URL
			}),
		}),
	],
});

Docker Copy Chapter

Add a .dockerignore to keep the build context small:

node_modules
dist
.git

Create a Dockerfile:

FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

RUN mkdir -p data

ENV HOST=0.0.0.0
ENV PORT=4321

EXPOSE 4321
CMD ["node", "./dist/server/entry.mjs"]

The seed file is read at build time and inlined into the bundle, so it does not need to be copied into the runtime image. Migrations run on the first request after a deploy; the seed applies only when the database has no collections and setup hasn't been completed — existing data is never overwritten.

If you hit that error, install the toolchain in the builder stage before npm ci:

# Alpine-based images (node:22-alpine)
RUN apk add --no-cache python3 make g++

# Debian-based images (node:22-slim)
RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ \
    && rm -rf /var/lib/apt/lists/*

Build the image and run the container:

docker build -t my-emdash-site .
docker run -p 4321:4321 -v emdash-data:/app/data my-emdash-site

A Docker Compose file manages the same container with a named volume:

services:
  emdash:
    build: .
    ports:
      - "4321:4321"
    volumes:
      - emdash-data:/app/data
    restart: unless-stopped

volumes:
  emdash-data:

Start the stack in the background:

docker compose up -d

Environment Variables Copy Chapter

Recommended: encryption key Copy Section

EMDASH_ENCRYPTION_KEY is the key for encrypting plugin secrets at
rest. The key is validated on startup; plugin secret encryption uses
it once enabled. Set it on every deployment so secrets are protected
without a later config change.

Generate a key and add the result to your environment:

npx emdash secrets generate  # add the result to your environment

The key is provided by you and never stored in the database; only
encrypted ciphertext is. Back it up somewhere durable (a password
manager, KMS, or your team's secret store) — losing it means losing
every secret encrypted with it.

Optional: stable-value overrides Copy Section

EmDash auto-generates the preview HMAC secret and commenter-IP hash
salt and persists them in the database on first use. The env vars
below pin them to a value you control — useful when a separate
process needs to share a secret with your main site.

Database and Storage Copy Section

Persistent Storage Copy Chapter

SQLite requires persistent disk storage. Ensure your hosting platform provides:

• A mounted volume or persistent disk
• Write access to the database directory
• Backup mechanisms for the database file

Health Checks Copy Chapter

Add a health check endpoint for load balancers:

export const GET = () => {
  return new Response("OK", { status: 200 });
};

Configure your platform to check /health for liveness probes.

File: docs/src/content/docs/deployment/storage.mdx Copy Chapter

title: Storage Options Copy Chapter

import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";

EmDash stores uploaded media (images, documents, videos) in a configurable storage backend. Choose based on your deployment platform and requirements.

Overview Copy Chapter

Cloudflare R2 (Binding) Copy Chapter

Use R2 bindings when deploying to Cloudflare Workers for the fastest integration.

import emdash from "emdash/astro";
import { r2 } from "@emdash-cms/cloudflare";

export default defineConfig({
	integrations: [
		emdash({
			storage: r2({ binding: "MEDIA" }),
		}),
	],
});

Configuration Copy Section

Setup Copy Section

Add the R2 binding to your Wrangler configuration:

Public Access Copy Section

For public media URLs, enable public access on your R2 bucket:

1. Go to Cloudflare Dashboard > R2 > your bucket
2. Enable public access under Settings
3. Add the public URL to your config:

storage: r2({
	binding: "MEDIA",
	publicUrl: "https://pub-xxxx.r2.dev",
});

S3-Compatible Storage Copy Chapter

The S3 adapter works with Cloudflare R2 (via S3 API), MinIO, and other S3-compatible services.

The following configuration points EmDash at an S3-compatible bucket:

import emdash, { s3 } from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			storage: s3({
				endpoint: process.env.S3_ENDPOINT,
				bucket: process.env.S3_BUCKET,
				accessKeyId: process.env.S3_ACCESS_KEY_ID,
				secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
				region: "auto", // Optional, defaults to "auto"
				publicUrl: process.env.S3_PUBLIC_URL, // Optional CDN URL
			}),
		}),
	],
});

Configuration Copy Section

* Both accessKeyId and secretAccessKey must be provided together, or both omitted.

Resolving S3 config from environment variables Copy Section

Any field omitted from s3({...}) is read from the matching S3_* environment variable
when the process starts. This lets you build a container image once and inject credentials
at boot without a rebuild. Explicit values in s3({...}) always take precedence over
environment variables.

Environment variables are read from process.env when the process starts. This is a
Node-only feature.

Calling s3() with no arguments reads every field from the S3_* environment variables:

import emdash, { s3 } from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			// s3() with no args: all fields from S3_* environment variables
			storage: s3(),

			// Or mix: override one field, rest from environment
			// storage: s3({ publicUrl: "https://cdn.example.com" }),
		}),
	],
});

R2 via S3 API Copy Section

Use S3 credentials with R2 for features like signed upload URLs:

storage: s3({
	endpoint: "https://<account-id>.r2.cloudflarestorage.com",
	bucket: "emdash-media",
	accessKeyId: process.env.R2_ACCESS_KEY_ID,
	secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
	publicUrl: "https://pub-xxxx.r2.dev",
});

Generate R2 API credentials in the Cloudflare dashboard under R2 > Manage R2 API Tokens.

MinIO Copy Section

Point the S3 adapter at a MinIO endpoint with its access credentials:

storage: s3({
	endpoint: "https://minio.example.com",
	bucket: "emdash-media",
	accessKeyId: process.env.MINIO_ACCESS_KEY,
	secretAccessKey: process.env.MINIO_SECRET_KEY,
	publicUrl: "https://minio.example.com/emdash-media",
});

Local Filesystem Copy Chapter

Use local storage for development. Files are stored in a directory on disk.

import emdash, { local } from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

Configuration Copy Section

The baseUrl should match EmDash's media file endpoint (/_emdash/api/media/file) unless you configure a custom static file server.

Environment-Based Configuration Copy Chapter

Switch storage backends based on environment:

import emdash, { s3, local } from "emdash/astro";
import { r2 } from "@emdash-cms/cloudflare";

const storage = import.meta.env.PROD
	? r2({ binding: "MEDIA" })
	: local({
			directory: "./uploads",
			baseUrl: "/_emdash/api/media/file",
		});

export default defineConfig({
	integrations: [emdash({ storage })],
});

Signed Uploads Copy Chapter

The S3 adapter supports signed upload URLs, allowing clients to upload directly to storage without passing through your server. This improves performance for large files.

Signed uploads are automatic when using the S3 adapter. The admin interface uses them when available.

Adapters that support signed uploads:

• S3 (including R2 via S3 API)

Adapters that do not support signed uploads:

• R2 binding (use S3 adapter with R2 credentials instead)
• Local

Storage Interface Copy Chapter

All storage adapters implement the same interface:

interface Storage {
	upload(options: {
		key: string;
		body: Buffer | Uint8Array | ReadableStream;
		contentType: string;
	}): Promise;

	download(key: string): Promise<DownloadResult>;
	delete(key: string): Promise<void>;
	exists(key: string): Promise;
	list(options?: ListOptions): Promise<ListResult>;
	getSignedUploadUrl(options: SignedUploadOptions): Promise<SignedUploadUrl>;
	getPublicUrl(key: string): string;
}

This consistency allows switching storage backends without changing application code.

File: docs/src/content/docs/contributing/architecture.mdx Copy Chapter

title: Architecture (internals) Copy Chapter

import { Aside, Steps } from "@astrojs/starlight/components";

This page is for people working on EmDash, not building a site with it. It documents internal mechanics — table layouts, the Astro integration, the request path, code generation. None of it is needed to use EmDash. If you are building a site, read Architecture and the Content Model instead.

The Astro integration Copy Chapter

EmDash runs as an Astro integration from the emdash package. At build time it:

• Injects the admin SPA and REST API routes with Astro's injectRoute API. Nothing is copied into the user's project. The injected paths are:

  Path pattern	Purpose
  /_emdash/admin/[...path]	Admin panel SPA
  /_emdash/api/manifest	Admin manifest (collections, plugins)
  /_emdash/api/content/[collection]	Content entry CRUD
  /_emdash/api/media/*	Media library operations
  /_emdash/api/schema/*	Schema management
  /_emdash/api/settings	Site settings
  /_emdash/api/menus/*	Navigation menus
  /_emdash/api/taxonomies/*	Categories, tags, custom taxonomies

• Generates virtual modules so the bundler can resolve and tree-shake configuration and plugin code:

  Module	Purpose
  virtual:emdash/config	Database and storage configuration
  virtual:emdash/dialect	Database dialect factory
  virtual:emdash/plugin-admins	Static imports for plugin admin UIs

• Provides the Live Collections loader, manages migrations, and opens the storage connection.

Database-first schema Copy Chapter

Schema definitions live in the database, not in code. Two system tables track structure.

_emdash_collections holds one row per collection:

CREATE TABLE _emdash_collections (
  id TEXT PRIMARY KEY,
  slug TEXT UNIQUE NOT NULL,        -- "posts", "products"
  label TEXT NOT NULL,              -- "Blog Posts"
  label_singular TEXT,              -- "Post"
  description TEXT,
  icon TEXT,
  supports JSON,                    -- ["drafts", "revisions", "preview"]
  source TEXT,                      -- how it was created
  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
  updated_at TEXT
);

The source column records provenance: manual (admin UI), template:<name> (seed file), import:wordpress (importer), or discovered (auto-detected from existing tables).

_emdash_fields holds one row per field, linked to its collection:

CREATE TABLE _emdash_fields (
  id TEXT PRIMARY KEY,
  collection_id TEXT REFERENCES _emdash_collections(id),
  slug TEXT NOT NULL,               -- column name
  label TEXT NOT NULL,
  type TEXT NOT NULL,               -- field type
  column_type TEXT NOT NULL,        -- TEXT, REAL, INTEGER, JSON
  required INTEGER DEFAULT 0,
  unique_field INTEGER DEFAULT 0,
  default_value TEXT,
  validation JSON,
  widget TEXT,
  options JSON,
  sort_order INTEGER,
  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
  UNIQUE(collection_id, slug)
);

Per-collection content tables Copy Section

Each collection gets its own table, prefixed ec_. A products collection with title and price fields produces:

CREATE TABLE ec_products (
  -- System columns, always present
  id TEXT PRIMARY KEY,
  slug TEXT UNIQUE,
  status TEXT DEFAULT 'draft',
  author_id TEXT,
  created_at TEXT DEFAULT (datetime('now')),
  updated_at TEXT DEFAULT (datetime('now')),
  published_at TEXT,
  deleted_at TEXT,                  -- soft delete
  version INTEGER DEFAULT 1,        -- optimistic locking

  -- Content columns, from field definitions
  title TEXT NOT NULL,
  price REAL
);

Real columns (rather than one table with a JSON blob) give proper indexing, working foreign keys, a schema database tools can inspect, and no per-field JSON parsing.

The concerns stay separated:

Runtime schema changes Copy Section

Adding a field through the admin UI runs three steps:

SQLite supports add, rename, and drop column (drop requires SQLite 3.35+) at runtime. Changing a column's type is not supported in place, so EmDash rebuilds the table transparently: create a new table, copy rows, drop the old table, rename the new one.

Runtime validation Copy Section

EmDash builds Zod schemas from the field definitions at startup and validates every create and update against them:

function buildSchema(fields: Field[]): ZodSchema {
	const shape: Record<string, ZodType> = {};
	for (const field of fields) {
		let zodType = fieldTypeToZod(field.type);
		if (field.required) zodType = zodType.required();
		if (field.validation?.min !== undefined) zodType = zodType.min(field.validation.min);
		shape[field.slug] = zodType;
	}
	return z.object(shape);
}

Data layer Copy Chapter

EmDash uses Kysely for type-safe SQL across every supported database (SQLite, libSQL, Cloudflare D1, and PostgreSQL). The dialect is selected by virtual:emdash/dialect from the configuration the site passes to the integration.

Live Collections loader Copy Chapter

Content is served at runtime through Astro's Live Collections. emdashLoader() implements Astro's LiveLoader interface and is registered as a single _emdash collection:

import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
	_emdash: defineLiveCollection({ loader: emdashLoader() }),
};

The single _emdash collection wraps every content type; the loader filters by type when getEmDashCollection("posts") is called.

Request paths Copy Chapter

A content request from a page:

An admin request:

Admin panel internals Copy Chapter

The admin is one React island. Astro serves the shell and enforces authentication in middleware; everything inside is client-side, built on TanStack Router, TanStack Query, TanStack Table, React Hook Form + Zod, TipTap, and Kumo (Cloudflare's Base UI + Tailwind design system).

The shell route gates access in middleware:

export async function onRequest({ request, locals }, next) {
	const session = await getSession(request);
	if (request.url.includes("/_emdash/admin")) {
		if (!session?.user) return redirect("/_emdash/admin/login");
		locals.user = session.user;
	}
	return next();
}

Manifest-driven UI Copy Section

The admin hardcodes nothing about collections or plugins. It fetches GET /_emdash/api/manifest, which returns the collections, plugins, and taxonomies the requesting user may access, filtered by role:

{
	"collections": [
		{
			"slug": "posts",
			"label": "Blog Posts",
			"icon": "file-text",
			"supports": ["drafts", "revisions", "preview"],
			"fields": [{ "slug": "title", "type": "string", "required": true }]
		}
	],
	"plugins": [{ "id": "audit-log", "label": "Audit Log" }],
	"taxonomies": [{ "name": "category", "label": "Categories", "hierarchical": true }],
	"version": "abc123"
}

Navigation, forms, and field editors are generated from this manifest, so schema and plugin changes appear without an admin rebuild, and Zod schemas stay server-side.

Plugin admin UIs Copy Section

Plugin admin entry points are collected into a generated virtual module of static imports so the bundler can resolve and tree-shake them:

import * as pluginAdmin0 from "@emdash-cms/plugin-seo/admin";

export const pluginAdmins = { seo: pluginAdmin0 };

Rich text conversion Copy Section

Portable Text fields edit in TipTap (ProseMirror). Content is converted at the load and save boundaries by portableTextToProsemirror() and prosemirrorToPortableText(). Unknown blocks from plugins or imports are preserved as read-only placeholders.

Signed uploads Copy Section

Media uploads use direct-to-storage signed URLs when the adapter supports them and a same-origin streaming endpoint otherwise:

Extending the content importer Copy Chapter

The WordPress importer is built on a pluggable ImportSource interface. A custom source implements probe, analyze, and fetch:

interface ImportSource {
	probe(input: ImportInput): Promise;
	analyze(input: ImportInput): Promise<AnalysisResult>;
	fetchContent(input: ImportInput): AsyncIterable<NormalizedEntry>;
}

probe validates the input and reports what it found, analyze maps source post types to EmDash collections and flags schema gaps, and fetchContent streams normalized entries the import pipeline writes through the same repositories the admin uses. Built-in sources cover WordPress WXR, WordPress.com, and the WordPress REST API; register a custom source to import from another system.

File: docs/src/content/docs/contributing/docs-style-guide.mdx Copy Chapter

title: Documentation Style Guide Copy Chapter

This guide defines how EmDash documentation is written. Contributions are edited to match it. You do not need to memorize it — reviewers and editors will help — but following it makes a contribution merge faster.

Documentation exists to help someone do something, then get back to their project. Write for a reader who is tired, in a hurry, reading in a second language, or new to the stack. Serve that reader above all else.

Readability Copy Chapter

Prefer:

• Short sentences and short paragraphs.
• Plain vocabulary over jargon.
• Abbreviations and acronyms written out the first time.
• Headings and lists to break up long passages.
• Active voice.

Document how to build with EmDash, not how EmDash is built. Implementation detail belongs in docs only when it changes a decision the reader has to make (when to pick a non-default value, a caveat that affects their project). It never replaces a usage example.

For non-EmDash topics — TypeScript, the AT Protocol, web fonts, SQL — link to a reputable source instead of explaining them. Document what someone needs to know to use the feature in EmDash.

What to emphasise Copy Chapter

A page's emphasis must be set by what the reader needs to do their task, never by what was interesting or recent to the people who built EmDash. Three habits to actively resist:

• Authoring-recency weight. A decision being new, or fresh in the writer's mind, is not a reason to feature it. The most-changed thing is rarely the most important thing to a reader. Order sections, list items, and headlines by how often a reader needs them, not by when they were added. If you are documenting something because it just changed, you are probably writing a changelog entry, not a doc.

• Builder-salience over reader-salience. Internal architecture and design decisions that were significant to make are usually invisible and irrelevant to use. State the capability the reader gets, not the mechanism behind it. A reader defining a collection does not need to know where the schema is stored, any more than they need to know the parser's language. If the mechanism genuinely helps someone working on EmDash, it belongs in the internals doc, not in a user-facing page.

• Straw-man self-definition. Do not define EmDash by contrast with a caricature of other tools ("Unlike most CMSs…", "Traditional CMSs force you to…", "in many CMSs you declare X in code"). Describe what EmDash does, directly, and let it stand on its own. Comparison is allowed only when the comparison is the reader's own question: on the evaluation page and the "Coming from…" orientation pages. Even there it must be specific and fair — concrete behaviours and trade-offs, not a strawman the reader is invited to dislike.

• Definition by negation. Framing a capability as the work you don't have to do — "no migration to write", "no rebuild", "without touching code", "no separate service" — is a straw-man in disguise: it only lands for a reader who is carrying the alternative you have invented for them. State what the reader does and what happens. "Add a field in the admin panel; it takes effect immediately" — not "add a field with no migration, no rebuild, no code". The exception is a concrete, reader-relevant behaviour stated positively: "content is served at runtime, so edits appear immediately" is a fact about EmDash; "no rebuilds needed" is the same fact phrased as someone else's absent pain — prefer the first.

The test for any sentence: would a reader trying to finish their task be worse off if it were deleted? If not, delete it. If it only makes sense to a reader comparing EmDash to something else, it is in the wrong place or should be cut.

Evergreen, not changelog Copy Chapter

User-facing pages describe how EmDash works now, for a reader who has no prior version in their head. No "now", "no longer", "used to", "instead of the old", "this changed". Version-to-version differences live only in an upgrade guide. A concept being recently introduced is never a reason to mention that it is recent.

Voice and tone Copy Chapter

Write neutral, factual sentences. State facts directly.

✅ Plugins run in an isolated runtime and can only reach the APIs they declare.

❌ Plugins live in a cosy little sandbox where nothing bad can ever happen!

• Do not use we, us, our, or let's. You are not sitting with the reader. Rephrase to address the reader directly or describe the system.
• Never use I. Documentation is not about the author.
• Address the reader as you when needed, especially to flag a step where something can go wrong.
• Do not narrate or tell a story. No "now that we've set up X, let's move on to Y". Start a section with the goal, then the steps.
• Avoid whimsy, mascots, and cultural references. They add reading effort and do not translate.
• Exclamation points are rare. Use one only for something genuinely encouraging or surprising. When unsure, use a period.

Headings Copy Chapter

• Page title is the <h1> (from frontmatter title). Sections start at <h2>.
• Keep headings short. <h2> and <h3> appear in the "On this page" sidebar; preview it and shorten anything that wraps.
• No trailing punctuation, including a colon.
• Format code as <code> in headings the same as in body text.

Lists Copy Chapter

• Use a bulleted list when order does not matter, such as a set of options or properties.
• Use a numbered list for steps that must be followed in sequence. Use the Starlight <Steps> component for procedures.
• When list items grow into multiple paragraphs or carry several code terms, switch to <h3> sections instead.

Examples Copy Chapter

• "for example" in full introduces a single example or hypothetical.
• "e.g." inside parentheses introduces a non-exhaustive list (e.g. GitHub, GitLab).
• A list that covers every option is not a list of examples — use parentheses without "e.g." (the required properties (src, alt)).

Code samples Copy Chapter

Code samples are as important as the prose around them.

Introduce every code block with a full, standalone sentence on its own line, telling the reader what the block does. Do not lead in with a sentence fragment ending in a colon, a bare heading, or "like so:".

✅ The following example registers a plugin in the sandboxed array:

❌ Add the plugin like so:

The introduction primes the reader for what the code does, so they only need to work out how. It also creates a fill-in-the-blank pattern for a reader doing something slightly different.

Within a <Steps> procedure, a direct imperative instruction is the introduction ("Add a tsconfig.json:" followed by the file is fine in a numbered step).

Other rules:

• Use real, working code. No foo/bar. Show one realistic configuration, not every possible value — the reader will only have one.

• Add a title= filename to any block that represents a file, so the reader knows where the code goes.

  md Copy

  ```ts title="src/plugin.ts"

• Use Expressive Code annotations, not raw ```diff fences, for before/after changes. Mark changed lines with del={n} / ins={n} or changed text with del="…" / ins="…". Keep diffs minimal and local to the lines that change.

  The following example shows a single line changing:

  md Copy

  ```ts del={1} ins={2}
  import { definePlugin } from "emdash";
  import type { SandboxedPlugin } from "emdash/plugin";
  ```

• Preview rendered code locally before submitting. A typo can break the display.

Upgrade and migration guides Copy Chapter

A guide that helps a reader move an existing project to a new version follows a fixed structure. The "What should I do?" sections are the part readers value most — do not skimp on them.

Open with: how to upgrade, a note that things may "just work" but to read on if not, and a link to the changelog.

Then list each breaking change as its own entry:

### [Renamed/Changed/Removed/Deprecated]: <feature>

In earlier versions, <one sentence, past tense, what it did>.

<One sentence, present tense, how it works now>.

#### What should I do?

Choose the verb by how the reader feels the impact. If a new default replaces their value, that is a "Changed: default value", not an "Added: option".

A breaking change is one that requires a change to the reader's project or it stops working. Give the action, not just the fact. Not "the minimum Node.js version is now X" but "check your Node.js version with the following command, and upgrade if it is below X".

EmDash specifics Copy Chapter

Conventions for recurring situations, ordered by how often a contributor hits them. This is a list of conventions, not a ranking of which features matter.

Plugins: sandboxed vs native Copy Section

Sandboxed and native plugins are different formats with different authoring shapes. A change to one rarely affects the other. State which format a page or example is about. When editing a sandboxed-plugin page, do not change native-plugin examples, and the reverse.

Localization Copy Section

Do not include messages.po changes in a docs PR. A workflow extracts catalogs on merge to main. Including them creates churn and merge conflicts.

Experimental features Copy Section

A feature behind an experimental flag, or an unstable wire format under an RFC, can change without notice. Keep its documentation lean, flag it with a caution <Aside>, and point to the RFC or discussion as the source of truth. Do not document an unstable surface in exhaustive detail.

Atmosphere accounts Copy Section

When the portable, user-owned identity behind Bluesky and the wider AT Protocol network comes up, call it an Atmosphere account and use that term consistently. Link the first mention to the Atmosphere login guide or atmosphereaccount.com. did:plc:… and handles are its concrete identifiers; use them where a literal value is needed.

Docs are code Copy Chapter

The documentation site is an EmDash-adjacent Astro project. Documentation changes go through the same pull request and review flow as code. Every text change waits for a review; a wording change can shift the meaning of a sentence or need matching edits elsewhere on the site. Small, reviewed, consistent changes keep the whole site coherent.

File: docs/src/content/docs/contributing/index.mdx Copy Chapter

title: Contributing to EmDash Copy Chapter

import { Aside, Steps, Tabs, TabItem } from "@astrojs/starlight/components";

EmDash is a pnpm monorepo. The main package is packages/core (published as emdash) — it contains the Astro integration, REST API, database layer, schema management, and plugin system. The admin UI lives in packages/admin.

For the full contributor reference — repo layout, architecture, code conventions, changeset policy — see CONTRIBUTING.md.

Local Setup Copy Chapter

Development Workflow Copy Chapter

Watch Mode Copy Section

For iterating on core packages alongside the demo, run two terminals:

# Terminal 1 — rebuild packages/core on change
cd packages/core && pnpm dev

# Terminal 2 — run the demo
cd demos/simple && pnpm dev

Checks Copy Section

Run these before committing (from the repo root):

pnpm typecheck    # TypeScript
pnpm lint         # full type-aware lint
pnpm format       # auto-format (oxfmt, tabs)

Tests Copy Section

Tests use real in-memory SQLite — no mocking. Each test gets a fresh database.

What Gets Accepted Copy Chapter

Feature PRs without prior maintainer approval will be closed.

For the full contribution policy, changeset guide, repo layout, and architecture overview, see CONTRIBUTING.md.