Aggiungere EmDash a un progetto Astro esistente

Questa guida aggiunge EmDash a un progetto Astro e verifica l’integrazione con una voce pubblicata. Usa l’adattatore Node.js, SQLite e lo storage locale dei media in modo che il percorso completo funzioni su una singola macchina.

Prima di iniziare

Usa Astro 6 o successivo e Node.js 22.16 o successivo. Verifica entrambe le versioni nel progetto:

node --version
npx astro --version

Questa guida cambia il sito all’output server di Astro e configura l’adattatore Node.js. Questo cambia il modo in cui il sito viene costruito e distribuito. Se il progetto usa già un altro adattatore server, non aggiungerne un secondo. Mantieni quell’adattatore e segui i suoi requisiti di deployment; per Cloudflare, usa la guida Cloudflare Workers.

Fai commit o salva in altro modo il progetto attuale prima di cambiare la sua configurazione.

Installare EmDash

Installa EmDash, l’adattatore Node.js e il supporto 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 per il pannello admin anche quando il sito pubblico non ha componenti React.

Registra l’adattatore, React ed EmDash in astro.config.mjs. Se il file contiene già altre integrazioni o impostazioni, mantienile e aggiungi le voci rilevanti da questo esempio:

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 memorizza il contenuto e il content model in data.db. L’adattatore di storage locale scrive i media in uploads/ e li serve tramite la route media di EmDash. Aggiungi entrambi i percorsi a .gitignore se non sono già esclusi.

Crea src/live.config.ts per connettere EmDash al sistema di contenuto di Astro:
```
import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
    _emdash: defineLiveCollection({ loader: emdashLoader() }),
};
```
Se il progetto ha già src/live.config.ts, aggiungi la voce _emdash all’oggetto collections esportato invece di sostituire il file. Un src/content.config.ts separato per le collection basate su file continua a funzionare accanto ad esso.
Genera una chiave di crittografia locale e scrivila in .env:
```
npx emdash secrets generate --write .env
```
Conferma che .env è escluso da .gitignore. La chiave protegge i secret dei plugin memorizzati nel database. Sostituire o perdere la chiave rende quei valori crittografati illeggibili, quindi conserva un backup protetto prima di distribuire il sito.

Configurare il sito e i contenuti

Avvia il server di sviluppo:
```
npm run dev
```
Apri http://localhost:4321/_emdash/admin/. La prima visita reindirizza alla procedura guidata di setup. Inserisci i dettagli del sito, crea l’account amministratore e registra un passkey.

Poiché questo progetto non ha un file seed, il setup applica il modello iniziale integrato di EmDash. Crea le collection Posts e Pages, i campi Titolo e contenuto, e le tassonomie Categoria e Tag. Non aggiunge voci di esempio.
Apri Posts, seleziona New Post e inserisci EmDash is connected come titolo. Seleziona Save per creare la voce, poi seleziona Publish.

Il database ora contiene una voce pubblicata nella collection integrata posts. Il passo successivo la legge da una pagina Astro.

Interrogare la voce

Crea una pagina di test resa dal server che elenchi i post pubblicati:

---
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>

Apri http://localhost:4321/emdash-test/. La pagina mostra EmDash is connected. Se cambi e ripubblichi il titolo nel pannello admin, ricaricare questa pagina mostra il titolo aggiornato.

Durante lo sviluppo locale, EmDash genera anche emdash-env.d.ts dal content model corrente. Le dichiarazioni generate forniscono a TypeScript il nome della collection posts e il suo campo title. Non modificare manualmente quel file generato.

Se la verifica fallisce

Se l’admin rimane su Loading EmDash…, verifica che react() appaia nell’array integrations di Astro. Installare @astrojs/react senza registrarlo non basta.
Se getEmDashCollection() restituisce un errore sulla live collection, verifica che src/live.config.ts esporti _emdash con emdashLoader().
Se la pagina funziona in sviluppo ma le modifiche distribuite non appaiono, verifica che la pagina non sia prerenderizzata e che l’applicazione distribuita usi l’output server.
Se il build non riesce a risolvere una delle importazioni, riesegui il comando di installazione e conferma che i cinque pacchetti sono stati aggiunti a questo progetto e non a un’altra directory del workspace.

Leggi Configurazione per altri database, adattatori di storage e opzioni di autenticazione. La guida all’interrogazione dei contenuti copre filtri, paginazione, anteprime e suggerimenti di cache.