Aggiungere EmDash a un progetto Astro esistente

npm create emdash@latest fornisce un progetto preconfigurato, ma EmDash si innesta anche su un sito Astro che hai già. Questa guida percorre ogni requisito che il template di partenza normalmente gestisce per te — ciascuno produce un errore confuso quando manca, quindi lavora la checklist in ordine.

Prerequisiti

Astro 6 o successivo — aggiorna prima se sei su una major precedente (npx @astrojs/upgrade)
Node.js v22.16.0 o superiore (le versioni dispari non sono supportate)
Output server — EmDash serve contenuti a runtime, quindi il tuo progetto ha bisogno di output: "server" e di un adapter (Node, Cloudflare, …)

Installare i pacchetti

Installa EmDash insieme alle sue dipendenze peer richieste. React alimenta l’interfaccia admin su /_emdash/admin; è richiesto anche se il tuo sito non 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

Deploy su Cloudflare? Aggiungi anche i pacchetti Cloudflare — la guida Deploy su Cloudflare li copre in dettaglio:

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

Registrare le integrazioni

Aggiungi sia react() che emdash() al tuo array integrations. Registrare @astrojs/react non è opzionale: installare solo il pacchetto non è sufficiente, e senza l’integrazione l’admin compila bene ma non si idrata mai — la pagina resta su “Loading EmDash…” per sempre.

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",
			}),
		}),
	],
});

Aggiungere il loader Live Collections

Crea src/live.config.ts così che il content layer di Astro possa risolvere il contenuto EmDash. Senza di esso, getEmDashCollection / getEmDashEntry non hanno una live collection attraverso cui instradare.

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

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

Il tuo src/content.config.ts esistente (collezioni basate su file) continua a funzionare parallelamente — vedi EmDash per sviluppatori Astro per come i due coesistono.

Verificare l’installazione

Avvia il server di sviluppo:
```
npm run dev
```
Apri http://localhost:4321/_emdash/admin e completa il wizard di setup.

Crea e pubblica un post, poi interrogalo da una pagina:

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

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

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

Deploy su Cloudflare

Segui Deploy su Cloudflare per il setup completo (database D1, bucket media R2, cron trigger). Due cose inciampano i progetti esistenti in particolare:

Usa Cloudflare Workers, non Pages. L’adapter @astrojs/cloudflare emette un wrangler.json che Pages non accetta. Se il tuo sito attualmente fa deploy su Pages, migralo a Workers prima.
I binding devono esistere nel tuo wrangler.jsonc. Come minimo servono un binding D1 per il database e un binding R2 per i media, corrispondenti ai nomi dei binding nel tuo astro.config.mjs.

Risoluzione dei problemi

Sintomo	Causa	Soluzione
Admin bloccato su “Loading EmDash…”	`@astrojs/react` non registrato	Aggiungere `react()` a `integrations`
`Could not resolve "astro:content"` in `live.config.ts`	Astro precedente alla 6	Aggiornare Astro
`getEmDashCollection` restituisce un errore	`src/live.config.ts` mancante	Aggiungere il loader live collections
Errori di build per pacchetti non risolti	Dipendenze peer non installate	Installare `@astrojs/react`, `react`, `react-dom` esplicitamente
Le modifiche ai contenuti non appaiono	La pagina è prerenderizzata	Impostare `export const prerender = false` sulle pagine dinamiche

Prossimi passi

EmDash per sviluppatori Astro — Come i concetti EmDash si mappano su ciò che già conosci
Lavorare con i contenuti — Interrogare e renderizzare contenuti
Deploy su Cloudflare — Portare il sito in produzione