Añadir EmDash a un proyecto Astro existente

Esta guía añade EmDash a un proyecto Astro y verifica la integración con una entrada publicada. Usa el adaptador Node.js, SQLite y almacenamiento local de medios para que la ruta completa funcione en una sola máquina.

Antes de empezar

Usa Astro 6 o posterior y Node.js 22.16 o posterior. Verifica ambas versiones en el proyecto:

node --version
npx astro --version

Esta guía cambia el sitio al output server de Astro y configura el adaptador Node.js. Eso cambia cómo se construye y despliega el sitio. Si el proyecto ya usa otro adaptador de servidor, no añadas un segundo. Mantén ese adaptador y sigue sus requisitos de despliegue; para Cloudflare, usa la guía de Cloudflare Workers.

Haz commit o guarda de otra manera el proyecto actual antes de cambiar su configuración.

Instalar EmDash

Instala EmDash, el adaptador Node.js y el soporte de React:
npm
```
npm install emdash @astrojs/node @astrojs/react react react-dom
```
pnpm
```
pnpm add emdash @astrojs/node @astrojs/react react react-dom
```
yarn
```
yarn add emdash @astrojs/node @astrojs/react react react-dom
```
EmDash usa React para el panel de administración incluso cuando el sitio público no tiene componentes React.

Registra el adaptador, React y EmDash en astro.config.mjs. Si el archivo ya contiene otras integraciones o configuraciones, mantenlas y añade las entradas relevantes de este ejemplo:

import node from "@astrojs/node";
import react from "@astrojs/react";
import { defineConfig } from "astro/config";
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",
            }),
        }),
    ],
});

SQLite almacena el contenido y el modelo de contenido en data.db. El adaptador de almacenamiento local escribe medios en uploads/ y los sirve a través de la ruta de medios de EmDash. Añade ambas rutas a .gitignore si no están ya excluidas.

Crea src/live.config.ts para conectar EmDash al sistema de contenido de Astro:
```
import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
    _emdash: defineLiveCollection({ loader: emdashLoader() }),
};
```
Si el proyecto ya tiene src/live.config.ts, añade la entrada _emdash al objeto collections exportado en lugar de reemplazar el archivo. Un src/content.config.ts separado para colecciones basadas en archivos sigue funcionando junto a este.
Genera una clave de cifrado local y escríbela en .env:
```
npx emdash secrets generate --write .env
```
Confirma que .env está excluido por .gitignore. La clave protege los secrets de plugins almacenados en la base de datos. Reemplazar o perder la clave hace que esos valores cifrados sean ilegibles, así que mantén una copia de seguridad protegida antes de desplegar el sitio.

Configurar el sitio y el contenido

Inicia el servidor de desarrollo:
```
npm run dev
```
Abre http://localhost:4321/_emdash/admin/. La primera visita redirige al asistente de configuración. Introduce los detalles del sitio, crea la cuenta de administrador y registra un passkey.

Como este proyecto no tiene archivo seed, la configuración aplica el modelo inicial incorporado de EmDash. Crea colecciones de Posts y Pages, campos de Título y contenido, y taxonomías de Categoría y Etiqueta. No añade entradas de ejemplo.
Abre Posts, selecciona New Post e introduce EmDash is connected como título. Selecciona Save para crear la entrada, luego selecciona Publish.

La base de datos ahora contiene una entrada publicada en la colección incorporada posts. El siguiente paso la lee desde una página Astro.

Consultar la entrada

Crea una página de prueba renderizada en servidor que liste los posts publicados:

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

const { entries: posts, error } = await getEmDashCollection("posts");

if (error) {
	throw error;
}
---

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

Abre http://localhost:4321/emdash-test/. La página muestra EmDash is connected. Si cambias y republicas el título en el panel de administración, al recargar esta página se muestra el título actualizado.

Durante el desarrollo local, EmDash también genera emdash-env.d.ts desde el modelo de contenido actual. Las declaraciones generadas proporcionan a TypeScript el nombre de la colección posts y su campo title. No edites ese archivo generado manualmente.

Si la verificación falla

Si el admin se queda en Loading EmDash…, verifica que react() aparece en el array integrations de Astro. Instalar @astrojs/react sin registrarlo no es suficiente.
Si getEmDashCollection() devuelve un error sobre la colección live, verifica que src/live.config.ts exporta _emdash con emdashLoader().
Si la página funciona en desarrollo pero las ediciones desplegadas no aparecen, verifica que la página no está prerenderizada y que la aplicación desplegada usa output de servidor.
Si la construcción no puede resolver una de las importaciones, vuelve a ejecutar el comando de instalación y confirma que los cinco paquetes se añadieron a este proyecto y no a otro directorio del workspace.

Lee Configuración para otras bases de datos, adaptadores de almacenamiento y opciones de autenticación. La guía de consulta de contenido cubre filtros, paginación, previsualizaciones y sugerencias de caché.