Deploy to Cloudflare

Cloudflare Workers provides a fast, globally distributed runtime for EmDash. This guide covers deploying with D1 for the database and R2 for media storage.

Prerequisites

• A Cloudflare account
• Wrangler CLI installed (npm install -g wrangler)
• Authenticated with Cloudflare (wrangler login)

Configure Bindings

Create wrangler.jsonc in your project root with D1 and R2 bindings. Wrangler provisions both resources on the first deploy if they don’t already exist.

wrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-emdash-site",
  "compatibility_date": "2025-01-15",
  "compatibility_flags": ["nodejs_compat"],

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

  "r2_buckets": [
    {
      "binding": "MEDIA",
      "bucket_name": "emdash-media",
    },
  ],
}

Configure EmDash

Update your Astro configuration to use D1 and R2:

astro.config.mjs

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import emdash from "emdash/astro";
import { d1, r2 } from "@emdash-cms/cloudflare";

export default defineConfig({
  output: "server",
  adapter: cloudflare(),
  integrations: [
    emdash({
      database: d1({ binding: "DB" }),
      storage: r2({ binding: "MEDIA" }),
    }),
  ],
});

First Boot

Database migrations run automatically on the first request after deployment, and on every subsequent boot if there’s anything new to apply.

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

To change the schema or content model of a site that is already deployed, see Evolving a Deployed Site.

Deploy

Deploy to Cloudflare Workers:

wrangler deploy

Your site is now live at https://my-emdash-site.<your-subdomain>.workers.dev.

Read Replicas

For globally distributed sites, enable D1 read replication to route read queries to nearby replicas instead of always hitting the primary database. This significantly reduces latency for visitors far from the primary region.

astro.config.mjs

emdash({
  database: d1({
    binding: "DB",
    session: "auto",
  }),
  storage: r2({ binding: "MEDIA" }),
}),

You also need to enable read replication on the D1 database itself in the Cloudflare dashboard or via the REST API.

Caution

Read replica sessions are incompatible with the global_fetch_strictly_public compatibility flag. With that flag in your wrangler.jsonc, the internal request the D1 Sessions API makes to route queries to replicas is silently blocked, and every SSR request hangs until the Worker is killed — with nothing in the logs (outcome: "canceled", no exceptions). The hang may only begin once replicas finish provisioning, so it can pass an initial post-deploy check and surface hours later. If your Worker needs that flag (for example, to fetch its own origin), keep session disabled. See #1273.

See Database Options — Read Replicas for session modes and how bookmark-based consistency works.

Object Cache

To reduce read load on D1, cache content and configuration query results in Cloudflare KV. Reads are served from KV instead of querying the database on every request:

astro.config.mjs

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

emdash({
  database: d1({ binding: "DB" }),
  storage: r2({ binding: "MEDIA" }),
  objectCache: kvCache({ binding: "CACHE" }),
}),

See Object Cache for KV setup, options, and invalidation behavior.

Custom Domain

Add a custom domain in the Cloudflare dashboard:

1. Go to Workers & Pages > your worker
2. Click Custom Domains > Add Custom Domain
3. Enter your domain and follow the DNS setup instructions

Public R2 Access

To serve media directly from R2 (recommended for performance):

1. In the Cloudflare dashboard, go to R2 > your bucket
2. Click Settings > Public access
3. Enable public access and note the public URL
4. Update your storage config:

astro.config.mjs

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

Tip

For production, connect a custom domain to your R2 bucket for better URLs and caching control.

Cloudflare Access Authentication

If your organization uses Cloudflare Access, you can use it as the authentication provider instead of passkeys, giving single sign-on through your existing identity provider. The following configuration enables it:

astro.config.mjs

emdash({
  database: d1({ binding: "DB" }),
  storage: r2({ binding: "MEDIA" }),
  auth: access({
    teamDomain: "myteam.cloudflareaccess.com",
    audience: "your-app-audience-tag",
    roleMapping: {
      "Admins": 50,
      "Editors": 40,
    },
  }),
}),

See the Authentication guide for full configuration options.

Email

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

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

Declare a send_email binding in wrangler.jsonc:

wrangler.jsonc

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

3. Register the provider

Add the plugin to your emdash() integration:

astro.config.mjs

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: "cms@mails.example.com", name: "My Site CMS" },
      replyTo: "hello@example.com", // optional
      binding: "EMAIL", // optional, defaults to "EMAIL"
    }),
  ],
}),

4. Activate and select it

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

Options

Option	Type	Default	Description
from	string | { email, name? }	— (required)	Sender address on a domain onboarded for Email Sending.
replyTo	string	—	Optional Reply-To, useful when from is a no-reply subdomain address.
binding	string	"EMAIL"	Name of the send_email binding in wrangler.jsonc.

Note

BCC and attachments are out of scope (not modeled in EmDash’s EmailMessage), and the provider is never auto-selected — you must choose it under Settings → Email.

Environment Variables

Recommended: encryption key

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

Caution

Never commit the encryption key to your repository, and back it up somewhere durable (a password manager, KMS, or your team’s secret store). The plain text value lives only in your environment.

Optional: stable-value overrides

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.

Variable	Purpose
EMDASH_PREVIEW_SECRET	Override for the auto-generated preview HMAC secret.
EMDASH_IP_SALT	Override for the auto-generated commenter-IP hash salt.
EMDASH_AUTH_SECRET	Optional. If set, it is used as the IP-salt source (unless EMDASH_IP_SALT is also set, which takes precedence), keeping commenter-IP hashes stable for installs that already rely on it. Leave it unset for a new deployment.

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

Preview Deployments

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

”D1 binding not found”

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

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

“R2 binding not found”

Check that the R2 bucket is correctly bound:

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

Migration errors

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.