Primi passi

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

Prerequisiti

• Node.js v22.12.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 istruzioni per dare un nome al tuo progetto e configurare le tue preferenze.

Avviare il server di sviluppo

Completare la procedura guidata

Quando visiti il pannello admin per la prima volta, la procedura guidata di EmDash ti guida attraverso la configurazione iniziale:

Una volta registrato il passkey, sei connesso e reindirizzato alla dashboard admin.

Il tuo primo articolo

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 articoli dinamiche
│   ├── layouts/
│   │   └── Base.astro    # Layout di 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 seguente configurazione 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'interfaccia 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 seguente file connette EmDash al sistema di contenuti di Astro attraverso una singola collezione live:

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 secret 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 secret dei plugin a riposo. Impostala ora così il tuo deployment è pronto quando la crittografia dei secret dei plugin la usa.

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

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

Il secret HMAC di preview e il salt dell’hash IP dei commentatori vengono generati e memorizzati nel database al primo utilizzo, quindi non hai bisogno di impostarli. Sovrascrivi il secret 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 i contenuti nelle pagine

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

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

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

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

La seguente pagina 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 completa dei tipi, genera i tipi dallo schema del tuo database:

npx emdash types

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

Prossimi passi

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

• Concetti fondamentali — Comprendi come funziona EmDash sotto il cofano
• Lavorare con i contenuti — Impara a interrogare e renderizzare i contenuti
• Libreria media — Carica e gestisci immagini e file
• Creare un blog — Costruisci un blog completo con categorie e tag
• Deploy su Cloudflare — Porta il tuo sito in produzione