Blog

The EmDash 1.4 upgrade guide: what changed and how to upgrade

Everything that breaks in 1.4 (cache headers, empty media fields, test selectors), the three-step upgrade, and what you get for it: autosave flushes, 409 conflict guards, and faster pages.

Cover for the EmDash 1.4 upgrade guide: neon terminal, shield and version stairs on a dark navy background

EmDash 1.4 shipped on 29 October with 75 changes from 22 contributors. The upgrade itself is one command and needs no database migrations, but three behavior changes will bite unprepared sites: removed cache headers, stricter media fields, and reshuffled admin buttons that break test suites. This guide covers the upgrade path, each breaking change with its fix, and what you get in return. Facts checked against the release notes and merged pull requests on 31 October 2026, when 1.4.0 was still the latest tag.

Before you start

Node.js
18.20.0+ or 20.9.0+ LTS
Astro
4.0.0 or higher
Git tree
Clean, all local edits committed
Database
No migrations needed for 1.4 core; still take a backup
Cloudflare plugins
Workers Paid if you run sandboxed plugins

Upgrade in three steps

The upgrade

  1. Commit and back up

    Get to a clean git tree, then snapshot your database (a D1 backup, or a SQLite or Postgres dump) so a rollback is one restore away.

  2. Run the upgrade CLI

    npx upgrade-emdash@latest bumps emdash and every official @emdash-cms/* plugin, updates your lockfile through the package manager it detects, and emits upgrade work orders if your astro.config.mjs or emdash.config.ts needs manual edits.

  3. Rebuild and verify

    pnpm build must pass clean. On Cloudflare, pnpm wrangler dev and confirm the D1, R2 and KV bindings answer; on a VPS, restart the container and check the logs for a clean workerd start. Then open /_emdash/admin, log in, and confirm Settings, Media usage tracking reads Ready.

Prefer explicit dependency review in CI? Skip the CLI and drive the package manager yourself:

bash
pnpm up --latest emdash @emdash-cms/*

The three breaking changes

Cache headers: the silent one. 1.4 stopped auto-populating cacheHint.lastModified (PR #4243). The old header caused stale 304 Not Modified responses at the Cloudflare edge when related content changed while the main entry did not. The catch: pages that used those hints also lose Astro's implicit Cache-Control: no-cache, so browsers and proxies may cache longer than you want. If your templates show a modification date, read entry.data.updatedAt directly. If you need revalidation on every request, set the header yourself:

src/pages/blog/[slug].astrotypescript
---
Astro.response.headers.set('Cache-Control', 'public, max-age=0, must-revalidate');
---

Blank media fields save as null. A cleared image or file field used to serialize an empty object; in 1.4 it saves strictly as null (PR #3129). Human editors in the admin never sent empty strings, so they see nothing. But custom API scripts, MCP agent tooling and CLI imports that send "" for an unset media field now get an HTTP 400, and a required media field rejects empty strings outright. Send null or omit the field:

json
{
  "title": "Article title",
  "featured_image": null
}

On the frontend, guard components that read media fields, since entry.data.featured_image.url on a null value will throw:

typescript
{entry.data.featured_image ? (
  <img src={entry.data.featured_image.url} alt={entry.data.featured_image.alt ?? ''} />
) : null}

Media usage tracking on collections with `title` or `name` reference fields. A field-name collision stopped the reference extractor from recording media usage in those collections (PR #4296). After upgrading, open Settings, Media usage tracking, and let the background scan finish. If it reads Ready, you are done. If it reads Needs attention, repair each affected collection:

bash
npx emdash media repair-usage --collection <collection-name>

One more for test suites: the content list replaced per-row action buttons with an ellipsis menu (PR #4446). Playwright and Cypress selectors that click Edit or Move to trash directly will fail; click the menu trigger first (accessible label: Actions for <Entry Title>) and then the action inside it.

What you get for it

The 1.4 payoff

  • Autosave flushes before you navigate away, with an explicit Autosave failed banner if the flush drops (PR #4298)
  • Concurrent saves return 409 CONFLICT instead of silently overwriting, which matters with two editors or several agents in one site (PR #4286)
  • Menu edits on Cloudflare D1 run as atomic transactions, no more half-applied translated menus (PR #4364)
  • admin.hiddenNavItems prunes sidebar sections, with a build failure on typos instead of silent ignores (PR #3856)
  • Admin complete in Simplified Chinese, Brazilian Portuguese and Turkish; RTL isolates slugs and URLs so they render left to right (PRs #4124, #4037, #3572, #4299)
  • External-auth sessions stop writing Workers KV on every request, so Cloudflare Free sites stop exhausting the 1,000 writes per day cap (PR #4157)
  • Widget object caching and consolidated byline queries cut 2 to 6 database round trips per page (PRs #3596, #4167)

Client-facing sites will use the sidebar pruning most. Hide what editors never touch:

emdash.config.tstypescript
import { defineConfig } from 'emdash';

export default defineConfig({
  admin: {
    hiddenNavItems: ["comments", "redirects", "widgets"],
  },
});

Sandboxed plugins: three notes

Sandboxed plugins still require Workers Paid on Cloudflare. Three things beyond that: first, plugin RPC calls now survive requests being distributed across Worker isolates, but any call made after a route or hook returns will fail, so await everything inside handlers (PR #4394). Second, plugins declared in your config's sandboxed: [] array skipped their install and activate hooks in 1.4.0, which silently killed cron schedules; the fix is merged on main (PR #4358) but not in a release yet, so verify cron tasks fire after upgrading. Third, a 1.4.1 patch is staged (PR #4506, not published as of 31 October) that shares plugin KV storage across execution modes and will require running pnpm emdash migrate when it lands. Not released when you read this? Nothing to do.

Done means

  • pnpm build passes with no type errors
  • Admin loads and Media usage tracking reads Ready
  • Public pages return the Cache-Control headers you set, not stale 304s
  • Plugin cron tasks and webhooks fire after first boot
  • End-to-end tests click the row actions menu, not dead buttons

Primary sources

That is the whole upgrade. One command, three checks, and an admin that stops losing edits. If something on your site behaved differently after upgrading, the GitHub discussions are watched closely; 1.4.1 is already taking shape there.