Iniziare

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

Prerequisiti

• Node.js v22.12.0 o superiore (le versioni con numeri 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 nominare il tuo progetto e configurare le tue preferenze.

Avviare il server di sviluppo

Completare la procedura guidata di configurazione

Quando visiti il pannello di amministrazione per la prima volta, la Procedura Guidata di Configurazione di EmDash ti guida attraverso la configurazione iniziale:

Una volta registrata la tua passkey, hai effettuato l’accesso e vieni reindirizzato al pannello di amministrazione.

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 di 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 seguente configurazione registra EmDash come integrazione Astro con un database SQLite locale e archiviazione file locale:

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

export default defineConfig({
	integrations: [
		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 segreti dei plugin con il seguente comando:

npx emdash secrets generate

Aggiungi il valore generato al tuo ambiente come EMDASH_ENCRYPTION_KEY, come mostrato di seguito. Questa chiave crittografa i segreti dei plugin a riposo. Impostala ora in modo che il tuo deployment sia pronto quando la crittografia dei segreti dei plugin la utilizza.

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

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

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

EMDASH_PREVIEW_SECRET=your-preview-secret

Interrogare il contenuto nelle pagine

Utilizza le funzioni di query di EmDash nelle tue pagine Astro. Queste seguono il modello delle collezioni live 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>Post più recenti</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 tramite 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 tipi TypeScript

Per una sicurezza dei tipi completa, genera i tipi dal tuo schema del 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 esecuzione, le seguenti pagine coprono cosa fare dopo:

• Concetti di base — Comprendere come funziona EmDash sotto il cofano
• Lavorare con i contenuti — Imparare a interrogare e renderizzare i contenuti
• Libreria multimediale — Caricare e gestire immagini e file
• Creare un blog — Costruire un blog completo con categorie e tag
• Distribuire su Cloudflare — Portare il tuo sito in produzione