Emdash Spin Up Demo

Spin up the EmDash simple demo

This is a one-shot recipe: from a fresh checkout of the EmDash monorepo to a logged-in admin in your browser. Total runtime ~30s on warm caches, ~3 minutes on a cold one.

The default monorepo path is ~/Projects/web design/emdash. If the user is in a different EmDash checkout, treat that as the repo root.

The recipe

All commands run from the repo root unless noted.

# 1. Make sure pnpm is on PATH at the version the repo pins
corepack enable
# (No-op if pnpm@10.28.0 is already shimmed.)

# 2. Install workspace deps (~20s on warm caches)
COREPACK_ENABLE_DOWNLOAD_PROMPT=0 pnpm install

# 3. Build all packages — REQUIRED before bootstrap
pnpm build

# 4. Bootstrap the demo's database (creates data.db, applies seed,
#    downloads 7 Unsplash images into demos/simple/uploads/)
cd demos/simple && pnpm bootstrap

# 5. Start the dev server (long-running; run in background)
pnpm dev

Once the dev server prints astro v6.x.x ready in ... ms and Local http://localhost:4321/, the user logs in via:

http://localhost:4321/_emdash/api/setup/dev-bypass?redirect=/_emdash/admin

This creates dev@emdash.local (role 50 = ADMIN) and sets a session cookie automatically. Works only on a dev server (import.meta.env.DEV === true); returns 403 in prod.

Why each step exists

Warnings that are EXPECTED — do not chase them

If the user reports any of these, reassure them. Don't go fix them — they're known and harmless for this demo.

During pnpm install (40+ lines):

WARN  Failed to create bin at .../node_modules/.bin/emdash. ENOENT:
      no such file or directory, open '.../emdash/dist/cli/index.mjs'

dist/ doesn't exist yet on a clean install. The repo's postbuild hook (scripts/relink-bins-if-needed.mjs) detects missing bins and re-links them after pnpm build. Confirm with ls demos/simple/node_modules/.bin/emdash after the build.

WARN  Ignored build scripts: @parcel/watcher@2.5.4, sharp@0.34.5.

Not in the root's pnpm.onlyBuiltDependencies allowlist. They ship prebuilt binaries; ignore.

WARN  cyclic workspace dependencies:
      packages/auth-atproto, packages/core

Known and accepted in this repo.

During pnpm dev startup:

[content] Content config not loaded

Live collection loads on demand on first request. Harmless.

[hooks] Plugin "audit-log" declares content:beforeSave hook without
        write:content capability — skipping
[hooks] Plugin "audit-log" declares media:afterUpload hook without
        read:media capability — skipping

The simple demo wires auditLogPlugin() without granting capabilities, so its hooks no-op. The CMS works fine; only the audit log is silent. Don't "fix" this in astro.config.mjs — it's the demo's intentional posture.

End-to-end verification (curl)

After step 5, run these to confirm everything works without opening a browser:

# Frontend
curl -sI http://localhost:4321/ | head -1                            # → HTTP/1.1 200 OK
curl -s  http://localhost:4321/ | grep -oE '<title>[^<]+</title>'    # → <title>My Blog</title>

# Auth via dev-bypass — creates session, saves cookie
rm -f /tmp/emdash-cookies.txt
curl -sL -c /tmp/emdash-cookies.txt -o /dev/null \
     "http://localhost:4321/_emdash/api/setup/dev-bypass?redirect=/_emdash/admin"

# Admin loads
curl -sI -b /tmp/emdash-cookies.txt http://localhost:4321/_emdash/admin | head -1
# → HTTP/1.1 200 OK

# Whoami
curl -s -b /tmp/emdash-cookies.txt http://localhost:4321/_emdash/api/auth/me
# → {"data":{"email":"dev@emdash.local","role":50,...}}

Two parsing gotchas when reading the cookie file:

• The session cookie name is astro-session (HttpOnly). EmDash piggybacks on Astro's session, not a custom emdash_* cookie.
• In curl's Netscape cookie format, lines starting with #HttpOnly_ ARE the cookies, not comments. A naive grep -v '^#' filter will hide them.

Expected output of pnpm bootstrap on a fresh DB

The seed produces:

• 35 migrations applied
• 2 collections (posts, pages)
• 6 fields, 7 taxonomy terms (3 categories + 4 tags)
• 2 bylines, 1 menu (3 items), 2 widget areas (6 widgets)
• 9 content items (8 posts including 1 draft + 1 page)
• 7 media files downloaded from Unsplash

If counts are noticeably off, the seed file or schema diverged — investigate before continuing.

Cleanup / reset to clean state

# From the repo root:
rm -f demos/simple/data.db
rm -rf demos/simple/uploads
# Re-run pnpm bootstrap to repopulate.

To stop a backgrounded pnpm dev, either kill its task in the harness or:

pkill -f "astro dev"

Common confusions

• templates/blank is not a runnable demo. Templates are starter scaffolds meant to be copied into demos/ (per CONTRIBUTING.md) or used by create-emdash. Trying to pnpm dev inside templates/blank may work but isn't the intended flow.
• There is no root pnpm dev script. Always cd demos/<name> first. The root package.json only has build/test/check/format/lint scripts.
• create-emdash is for scaffolding a new project outside the monorepo. It's not part of this recipe — use it when the goal is to start a real site, not when the goal is to try EmDash.
• The data.db and uploads/ dirs are gitignored in demos/simple. Recreating them via bootstrap is always cheap.

When this skill does NOT apply

• The user wants to scaffold a new EmDash project from scratch → use create-emdash (pnpm new from the monorepo root, or pnpm dlx create-emdash outside it).
• The user wants to add features, define collections, render content → use the building-emdash-site skill.
• The user wants to author a plugin → use the creating-plugins skill.
• The user wants to manage content via CLI → use the emdash-cli skill.