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

[royachiron]

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)

[royachiron]

The cache-undefined symptom in this issue overlaps with #945 and #959

[ascorbic]

Thanks! Great idea for a guide. The cache issue is an Astro bug, but we have a workaround now. The TipTap dependencies are a strange one – we don't have these as dependencies for any of our default templates, so I'm unsure why this is causing an issue.

[royachiron]

(Posting on behalf of @royachiron. He's a QA engineer rather than a JS dev, so this writeup is from me, Claude Opus 4.7, after digging through the repo and his repro. He flagged the issue but can't easily produce maintainer-grade context himself; the audience this matters for is roughly the same: users who graft emdash into an existing site, follow an upgrade path, or rely on LLM/auto-deploy install commands rather than npm create emdash.)

His scenario: existing Astro 4 site on Cloudflare Workers, upgrading to Astro 6, installed via npm install emdash ... --legacy-peer-deps. The --legacy-peer-deps flag is what most LLM and StackOverflow recipes reach for right now because the Astro 6 + React 19 + @astrojs/* peer graph won't resolve under strict npm. That single flag is also what surfaces the TipTap failure.

The four missing packages are unsatisfied peer deps of @tiptap/extension-drag-handle@3.20.0, which @emdash-cms/admin pulls in directly. Drag-handle declares them non-optional:

"peerDependencies": {
  "@tiptap/y-tiptap": "^3.0.2",
  "@tiptap/extension-collaboration": "^3.20.0",
  "@tiptap/extension-node-range": "^3.20.0",
  "@tiptap/core": "^3.20.0",
  "@tiptap/pm": "^3.20.0"
}

y-tiptap then peers yjs and y-protocols. Admin declares node-range, core, pm directly, but not y-tiptap or extension-collaboration, and neither does any template (grep across packages/ and templates/ returns zero hits for those names).

The default templates still work because the monorepo uses pnpm with auto-install-peers=true, which silently installs those peers and hoists them. npm create emdash users on pnpm or bun get the same hoisting for free. The deps are satisfied, but by the package manager, not by anything declared in the repo.

Under npm install --legacy-peer-deps, npm skips peer installation entirely, so those four never land in node_modules. Vite's optimizeDeps then walks into @tiptap/extension-drag-handle/dist/index.js, hits the unconditional import from @tiptap/y-tiptap and @tiptap/extension-collaboration, and esbuild errors at build time (chained with yjs and y-protocols from the y-tiptap import graph). Build-time, not runtime: emdash doesn't have to use the collab features for the bundler to need the modules.

So the symptom is invisible from the scaffold path and only surfaces on consumers that aren't pnpm-with-hoisting. The "vibe-coded graft" population is exactly that group, since --legacy-peer-deps is currently the path of least resistance for getting Astro 6 to install at all.