Añadir EmDash a un Proyecto Astro Existente

npm create emdash@latest proporciona un proyecto preconfigurado, pero EmDash también se integra en un sitio Astro que ya tienes. Esta guía recorre cada requisito que la plantilla de inicio normalmente maneja por ti — cada uno produce un fallo confuso cuando falta, así que trabaja la lista de verificación en orden.

Prerrequisitos

Astro 6 o posterior — actualiza primero si estás en una versión major anterior (npx @astrojs/upgrade)
Node.js v22.12.0 o superior (las versiones impares no son compatibles)
Salida del servidor — EmDash sirve contenido en tiempo de ejecución, por lo que tu proyecto necesita output: "server" y un adaptador (Node, Cloudflare, …)

Instalar los Paquetes

Instala EmDash junto con sus dependencias peer requeridas. React alimenta la interfaz de administración en /_emdash/admin; es obligatorio incluso si tu sitio no usa React.

npm

npm install emdash @astrojs/react react react-dom

pnpm

pnpm add emdash @astrojs/react react react-dom

yarn

yarn add emdash @astrojs/react react react-dom

Para una base de datos SQLite local (por defecto para desarrollo), instala también el driver:

npm install better-sqlite3

¿Desplegando en Cloudflare? Añade también los paquetes de Cloudflare — la guía Desplegar en Cloudflare los cubre en detalle:

npm install @astrojs/cloudflare @emdash-cms/cloudflare

Registrar las Integraciones

Añade tanto react() como emdash() a tu array integrations. Registrar @astrojs/react no es opcional: instalar solo el paquete no es suficiente, y sin la integración el admin se compila bien pero nunca se hidrata — la página se queda en “Loading EmDash…” para siempre.

import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import react from "@astrojs/react";
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	output: "server",
	adapter: node({ mode: "standalone" }),
	integrations: [
		react(),
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

Añadir el Loader de Colecciones en Vivo

Crea src/live.config.ts para que la capa de contenido de Astro pueda resolver el contenido de EmDash.

import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
	_emdash: defineLiveCollection({ loader: emdashLoader() }),
};

Verificar la Instalación

Inicia el servidor de desarrollo:
```
npm run dev
```
Abre http://localhost:4321/_emdash/admin y completa el Asistente de Configuración.

Crea y publica un post, luego consúltalo desde una página:

---
import { getEmDashCollection } from "emdash";

const { entries: posts } = await getEmDashCollection("posts", {
	status: "published",
});
---

<ul>{posts.map((post) => <li>{post.data.title}</li>)}</ul>

Desplegar en Cloudflare

Sigue Desplegar en Cloudflare para la configuración completa. Dos cosas causan problemas especialmente en proyectos existentes:

Usa Cloudflare Workers, no Pages.
Los bindings deben existir en tu wrangler.jsonc.

Solución de Problemas

Síntoma	Causa	Solución
Admin atascado en “Loading EmDash…”	`@astrojs/react` no registrado	Añadir `react()` a `integrations`
`Could not resolve "astro:content"` en `live.config.ts`	Astro anterior a 6	Actualizar Astro
`getEmDashCollection` devuelve un error	Falta `src/live.config.ts`	Añadir el loader de colecciones en vivo
Errores de compilación sobre paquetes no resueltos	Dependencias peer no instaladas	Instalar `@astrojs/react`, `react`, `react-dom` explícitamente
Los cambios de contenido no aparecen	La página está prerenderizada	Establecer `export const prerender = false` en páginas dinámicas