Añadir EmDash a un proyecto Astro existente

npm create emdash@latest incluye un proyecto preconfigurado, pero EmDash también se puede injertar 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 error 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.16.0 o superior (versiones impares no son compatibles)
• Salida de 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 de pares requeridas. React alimenta la interfaz de administración en /_emdash/admin; es requerido incluso si tu sitio en sí no usa React.

npm install emdash @astrojs/react react react-dom

pnpm add emdash @astrojs/react react react-dom

yarn add emdash @astrojs/react react react-dom

¿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 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 Live Collections

Crea src/live.config.ts para que la capa de contenido de Astro pueda resolver el contenido de EmDash. Sin él, getEmDashCollection / getEmDashEntry no tienen una live collection a través de la cual enrutar.

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

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

Tu src/content.config.ts existente (colecciones basadas en archivos) sigue funcionando junto a él — consulta EmDash para desarrolladores Astro para ver cómo coexisten los dos.

Verificar la instalación

Desplegar en Cloudflare

Sigue Desplegar en Cloudflare para la configuración completa (base de datos D1, bucket de medios R2, cron triggers). Dos cosas tropiezan especialmente a los proyectos existentes:

• Usa Cloudflare Workers, no Pages. El adaptador @astrojs/cloudflare emite un wrangler.json que Pages no acepta. Si tu sitio actualmente se despliega en Pages, mígralo a Workers primero.
• Los bindings deben existir en tu wrangler.jsonc. Como mínimo necesitas un binding D1 para la base de datos y un binding R2 para medios, coincidiendo con los nombres de binding en tu astro.config.mjs.

Solución de problemas

Próximos pasos

• EmDash para desarrolladores Astro — Cómo los conceptos de EmDash se mapean a lo que ya conoces
• Trabajar con contenido — Consultar y renderizar contenido
• Desplegar en Cloudflare — Llevar el sitio a producción