On September 28, 2026, EmDash 1.0 was officially released.
EmDash is an open-source CMS built on Astro by Cloudflare. The admin UI is embedded directly into the Astro site and runs on Cloudflare Workers, D1, and R2.
If you're familiar with WordPress, think of it as a WordPress-like CMS built on Astro.
Our internal blog, "Yuruillog," which we migrated from microCMS in a previous article, had been stuck on version 0.22 since June, so this time I upgraded it all the way to the latest 1.2.0.
The highlights of 1.0 are stability, safer upgrades, plugins that run in a sandbox, and an MCP server for agents.
To cut a long story short, the migration took one day, but there were plenty of pitfalls.
If you start with the assumption that "it's 1.0 now, so it must be stable," you'll get stuck not on EmDash itself but on its surrounding dependencies.
Premise: Upgrading from 0.22 to 1.2 had to be done manually.
Version 1.2 introduced an official upgrade CLI called upgrade-emdash.
It updates dependencies and generates a site-specific UPGRADE.md, but it only supports 0.35 and later, so it couldn't be used from 0.22.
Between 0.22 and 1.2 there are 47 database migrations, along with several fairly breaking changes.
It wasn't a case of simply running "npm install emdash@latest" and being done.
1. Take a backup and replicate the production DB locally
npx wrangler d1 export <database-name> --remote --output=backups/pre-1.2.sql
I then ran this against local D1 and tested the migrations using the same data as production.
2. Update dependencies
Package | Before migration | After migration |
|---|---|---|
emdash / @emdash-cms/cloudflare / @emdash-cms/admin | 0.22.0 | 1.2.0 |
@emdash-cms/plugin-forms | 0.1.1 | 0.2.9 |
astro | 6.1.2 | 6.4.8 |
wrangler | 4.80 | 4.148 |
Because wrangler had to be raised to meet the peer requirement of emdash 1.2 (4.99 or later), we also removed the workarounds from the 0.22 era at this point. @astrojs/cloudflare already met the peer requirement, so we left it at 13.1.6 for now. This is what causes the next pitfall.
- patch-package on the OAuth routes: applied to work around a bug in 0.22. Fixed upstream.
- CSS injected into the admin: the 0.22 admin CSS was written for the kumo 2.4 UI library, but the lockfile pulled in 2.6, so the login and publish highlight buttons showed white text on a transparent background and became invisible. This is fixed upstream in 1.2.
3. Dev server won't start (pitfall: miniflare generation mismatch)
After updating dependencies, npm run dev would not start. The cause was a miniflare generation mismatch.
wrangler 4.148 uses miniflare 5 and updates the _cf_ALARM table in the local D1 state (.wrangler/state/v3/) to three columns.
Meanwhile, miniflare bundled with @astrojs/cloudflare 13.1.6 is generation 4, and due to the column count mismatch, it cannot read the local state.
The fix is to also raise @astrojs/cloudflare, which we had left in place, so that its miniflare generation matches wrangler's. If you just remember "wrangler and the adapter's miniflare generation must match," you'll get it right the next time.
In addition, the emdash dev command in 0.22 has been removed, so the dev script has been reverted to astro dev. Migrations and type generation now run when astro dev starts.
4. The staging menu disappeared (trap: menus in seed.json)
After dev started, the 90 migrations passed, and when I pushed to staging and opened the admin panel, the Japanese global navigation was empty.
The cause was the menus and widgetAreas in seed/seed.json.
EmDash's seed process, when a menu or widget area with the same name exists, deletes all of its items and then recreates it empty.
Because seed.json still contained menu definitions with "items": [] as a template, the menus were reset every time the seed ran.
The fix is to delete the menus and widgetAreas keys entirely.
Menu contents are managed in the admin panel, so there is no reason to keep them in the seed.
5. English post links become /en/posts/en/slug (trap: locale prefix on entry.id)
This is a specification change in 1.2.
On multilingual sites, getEmDashCollection() now returns entry.id with a locale prefix. For an English post, it is en/my-post.
Yurulog built article URLs from entry.id, so English post links were doubled as /en/posts/en/my-post.
I replaced every place that builds URLs—the listing, pickups, search results, RSS, and canonical—with entry.data.slug. entry.data.slug is typed as string | null, so the receiving types also need to be updated to match.
It helps to keep the roles separate: entry.id is the key, entry.data.slug is the URL, and entry.data.id is the DB ULID (used for API calls).
6. Errors appear every minute (trap: Cron Trigger and Worker entry)
In 1.x, the Worker's scheduled() handler drives scheduled post publishing and periodic plugin tasks.
On Cloudflare, there is no internal timer, so scheduled posts won't publish at their scheduled time without a Cron Trigger.
For that reason, I added a Cron Trigger to wrangler.jsonc.
"triggers": { "crons": ["* * * * *"] }Then every minute, "Handler does not export a scheduled() function" appears.
This is because the Worker entry does not export scheduled().
The fix is to replace src/worker.ts with the official entry.
export { default, PluginBridge } from "@emdash-cms/cloudflare/worker";With this, along with fetch and scheduled, the PluginBridge for sandboxed plugins is also in place.
From actual use:
What went well after upgrading to 1.2.
- The editor has been redesigned and is easier to use. The slash menu is now grouped, and the toolbar follows you as you scroll. It also works on mobile.
- A video block is now included as standard. I had been embedding videos with a custom plugin, so I'd like to replace that eventually.
- All the stopgap fixes from the 0.22 era could be removed. Neither patch-package nor the CSS injection is needed anymore.
Things to watch out for.
- Going from 1.0 to 1.2 took only 10 days, so releases are moving fast. For now, it seems we'll need to verify each minor version on staging before upgrading.
Summary
- Upgrading from 0.22 to 1.2 is a manual migration.
upgrade-emdashCLI supports version 0.35 and later. - Keep the wrangler and adapter miniflare generations aligned. If they're mismatched, dev won't start.
- Don't leave empty
menus/widgetAreasplaceholders in seed.json. They get wiped out every time you seed. - On multilingual sites,
entry.idincludes a locale prefix, so build URLs fromentry.data.sluginstead. - If you add a Cron Trigger, set the Worker entry to
@emdash-cms/cloudflare/worker.
Each of these fixes takes only a few lines once you know the cause, but working through them one by one takes far longer than you'd expect.
That said, being able to remove all the patches and CSS workarounds I applied in 0.22 is proof that many small bugs have been ironed out on the way to the stable release.
Six months ago, it felt like an experimental switch, but after 1.0, I think it has become a CMS worth serious consideration for production use, as long as you're prepared for the effort of keeping up with updates.
Starting out in DTP and moving into the web, he now handles markup, frontend, direction, and accessibility alike. A "master of all trades" who has been versatile since Liberogic's early days and is now a walking encyclopedia of the company. Lately he has been hooked on exploring efficiency through prompts, asking, "Can't we rely more on AI for accessibility work?" Both his skills and his thinking are still evolving.
Ayumu Futamata
IAAP Certified Web Accessibility Specialist (WAS) / Markup Engineer / Frontend Engineer / Web Director