DX: "add emdash to existing Astro project" path has 3 unstated requirements that produce silent failures

[khoinguyenpham04]

This Roadmap discussion mirrors #962: DX: "add emdash to existing Astro project" path has 3 unstated requirements that produce silent failures.

Use this discussion to upvote the roadmap item and discuss priority, use cases, and product feedback. Keep implementation tracking, reproduction details, and PR-specific feedback on the source issue.

• Source issue: #962
• Status: Open
• Labels: roadmap/1.0, roadmap/migration-onboarding
• Original author: royachiron

Original Issue

Description

The "add emdash to an existing Astro project" path has at least three requirements that aren't surfaced by the docs or the install flow. Each one produces a silent failure (build OK, runtime crash or non-hydrating UI) which is hard to diagnose for someone vibe-coding a site, especially when an AI agent is driving the install.

I hit all three back-to-back today while wiring emdash 0.10.0 into an existing Astro project (Astro 4 -> 6 upgrade) deployed to Cloudflare Workers. None of these blocked npm create emdash@latest, presumably because the starter template ships them pre-wired.

Three friction points

1. experimental.cache.provider is required, undocumented

/_emdash/api/content/posts/<id>/publish and .../unpublish destructure cache from the route context and call cache.invalidate({ tags: [...] }) / cache.enabled directly. If the host project hasn't enabled experimental.cache with a provider, cache is undefined at runtime and every publish/unpublish returns HTTP 500 with TypeError: Cannot read properties of undefined (reading 'enabled').

17:42:40 [ERROR] TypeError: Cannot read properties of undefined (reading 'enabled')
    at Module.POST (chunks/publish_B7GTarhw.mjs:50:13)

Fix that worked for me:

// astro.config.mjs
import { defineConfig, memoryCache } from 'astro/config';
export default defineConfig({
  experimental: { cache: { provider: memoryCache() } },
  // ...
});

Suggested upstream fix: ship a no-op cache fallback in the route handler (if (cache?.enabled) await cache.invalidate(...)), or call this requirement out in the "Adding to an existing project" docs.

2. @​astrojs/react must be registered in host astro.config

emdash declares @​astrojs/react as a peer dependency, but installing it isn't enough. The admin React shell builds successfully without react() in the host's integrations: [...], and the page even returns 200 with the boot loader markup. The bundle just never hydrates, so the admin sits forever on "Loading EmDash...".

Suggested upstream fix: emit a clear build-time error or postinstall warning if the host config lacks @​astrojs/react. Or have the emdash integration assert it's been registered.

3. Tiptap collaboration peer deps not declared

After install, the build fails with a chain of Could not resolve "@​tiptap/extension-collaboration", "@​tiptap/y-tiptap", "yjs", "y-protocols". They are pulled in transitively from @​tiptap/extension-drag-handle but not as direct deps that npm/pnpm will guarantee. On a vibe-coded install this manifests as a wall of esbuild errors.

Fix that worked:

npm i @​tiptap/extension-collaboration @​tiptap/y-tiptap yjs y-protocols --legacy-peer-deps

Suggested upstream fix: pin these as direct deps of @​emdash-cms/admin or list them in the docs.

4. No graft guide

Most of the friction would evaporate if there were a docs page parallel to "Getting Started" titled something like "Add emdash to an existing Astro project" that walked through:

• Required Astro / Tailwind / React versions
• experimental.cache requirement
• Required integrations (react(), cloudflare() for CF)
• Peer deps that need explicit npm install
• The bare minimum wrangler.jsonc for D1 + R2 + KV
• Cloudflare Pages -> Workers caveat (Pages config doesn't accept the adapter's emitted wrangler.json)

Steps to reproduce

1. Start with an existing Astro 4 project deployed on Cloudflare Pages (any vibe-coded site).
2. Upgrade Astro to 6 and add @​astrojs/cloudflare.
3. npm install emdash @​astrojs/cloudflare @​emdash-cms/cloudflare --legacy-peer-deps.
4. Update astro.config.mjs per the "Adding to an existing project" instructions in the docs.
5. Build. Hit the missing tiptap peer deps. Install them. Build again.
6. Deploy. Visit /_emdash/admin. Page sits on "Loading EmDash..." because @​astrojs/react isn't registered.
7. Add react(). Rebuild + redeploy. Admin loads.
8. Create a post. Click Publish. HTTP 500.
9. Tail Worker logs. See the cache.enabled TypeError. Add experimental.cache.provider: memoryCache(). Rebuild + redeploy. Publish works.

Expected

The official docs path for "add to existing site" should land you in a working state, or at least surface a single actionable error per missing piece, not a silent 500 on the publish flow.

Actual

Three silent failures in sequence, each requiring server-side log access and source-of-@​emdash-cms/admin reading to diagnose.

Environment

• emdash version: 0.10.0
• Node.js version: 24.13.1
• Runtime: Cloudflare Workers
• OS: Linux (WSL2 / Ubuntu)