Guida introduttiva

Questa guida ti accompagna nella creazione del tuo primo sito EmDash, dall’installazione alla pubblicazione del tuo primo post.

Prerequisiti

• Node.js v22.16.0 o superiore (le versioni dispari non sono supportate)
• npm, pnpm o yarn
• Un editor di codice (VS Code consigliato)

Creare un nuovo progetto

npm create emdash@latest

pnpm create emdash@latest

yarn create emdash

Segui le indicazioni per nominare il tuo progetto e configurare le tue preferenze.

Avviare il server di sviluppo

Completare il wizard di configurazione

Alla prima visita del pannello admin, il wizard di configurazione di EmDash ti guida attraverso la configurazione iniziale:

Una volta registrata la passkey, sei connesso e reindirizzato alla dashboard admin.

Il tuo primo post

Struttura del progetto

Il tuo progetto EmDash segue una struttura Astro standard con alcune aggiunte:

my-emdash-site/
├── astro.config.mjs      # Configurazione Astro + EmDash
├── src/
│   ├── live.config.ts    # Configurazione Live Collections
│   ├── pages/
│   │   ├── index.astro   # Homepage
│   │   └── posts/
│   │       └── [...slug].astro  # Pagine post dinamiche
│   ├── layouts/
│   │   └── Base.astro    # Layout base
│   └── components/       # I tuoi componenti Astro
├── .emdash/
│   ├── seed.json         # File seed del template
│   └── types.ts          # Tipi TypeScript generati
└── package.json

File di configurazione

astro.config.mjs

La configurazione seguente registra EmDash come integrazione Astro con un database SQLite locale e storage file locale:

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

export default defineConfig({
	integrations: [
		react(), // Richiesto — l'UI admin è un'app React
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

src/live.config.ts

Il file seguente connette EmDash al sistema di contenuto di Astro attraverso una singola live collection:

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

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

Variabili d’ambiente

Per la produzione, genera una chiave di crittografia per i segreti dei plugin con il seguente comando:

npx emdash secrets generate

Aggiungi il valore generato al tuo ambiente come EMDASH_ENCRYPTION_KEY, come mostrato sotto. Questa chiave crittografa i segreti dei plugin a riposo. Impostala ora così il tuo deployment è pronto quando la crittografia dei segreti dei plugin la userà.

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

La chiave non viene mai memorizzata nel database — solo il testo cifrato. Esegui il backup in un luogo durevole, perché perderla significa perdere ogni segreto crittografato con essa.

Il segreto HMAC di preview e il salt di hash IP del commentatore vengono generati e memorizzati nel database al primo uso, quindi non è necessario impostarli. Sovrascrivi il segreto di preview solo se un processo separato deve verificare gli stessi token del tuo sito principale, come mostrato sotto.

EMDASH_PREVIEW_SECRET=your-preview-secret

Interrogare il contenuto nelle pagine

Usa le funzioni di query di EmDash nelle tue pagine Astro. Queste seguono il pattern delle live collections di Astro, restituendo { entries, error } per le collezioni e { entry, error } per le singole voci:

---
import { getEmDashCollection } from "emdash";
import Base from "../layouts/Base.astro";

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

<Base title="Home">
  <h1>Ultimi post</h1>
  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/posts/${post.slug}`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</Base>

La pagina seguente recupera una singola voce per slug:

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

const { slug } = Astro.params;
const { entry: post } = await getEmDashEntry("posts", slug);

if (!post) {
  return Astro.redirect("/404");
}
---

<h1>{post.data.title}</h1>

Generare i tipi TypeScript

Per la sicurezza dei tipi completa, genera i tipi dal tuo schema di database:

npx emdash types

Questo crea .emdash/types.ts con interfacce per tutte le tue collezioni. Il tuo editor ora autocompleterà i nomi dei campi e rileverà gli errori di tipo.

Prossimi passi

Con il sito in funzione, le pagine seguenti coprono cosa fare dopo:

• Concetti fondamentali — Capire come funziona EmDash internamente
• Lavorare con i contenuti — Imparare a interrogare e renderizzare contenuti
• Libreria multimediale — Caricare e gestire immagini e file
• Creare un blog — Costruire un blog completo con categorie e tag
• Deploy su Cloudflare — Portare il sito in produzione