Per iniziare

Questa guida ti accompagna dalla creazione del progetto alla pubblicazione del primo articolo.

Prerequisiti

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

Creare un nuovo progetto

npm create emdash@latest

pnpm create emdash@latest

yarn create emdash

Segui le istruzioni per dare un nome al progetto e impostare le preferenze.

Avviare il server di sviluppo

Completare la procedura guidata di configurazione

Alla prima visita del pannello di amministrazione, la procedura guidata di EmDash ti accompagna nella configurazione iniziale:

Quando la passkey è registrata, sei connesso e reindirizzato alla dashboard di amministrazione.

Il tuo primo articolo

Struttura del progetto

Il progetto EmDash segue la 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   # Home page
│   │   └── posts/
│   │       └── [...slug].astro  # Pagine dinamiche degli articoli
│   ├── 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

Configura EmDash come integrazione Astro:

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

Collega EmDash al sistema di contenuti di Astro:

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

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

Variabili d’ambiente

Per il deploy in produzione devi impostare:

# Required for authentication
EMDASH_AUTH_SECRET=your-secret-here

# Optional: for content preview
EMDASH_PREVIEW_SECRET=your-preview-secret

Genera un secret di autenticazione sicuro con:

npx emdash auth secret

Interrogare i contenuti nelle pagine

Usa le funzioni di query EmDash nelle pagine Astro. Seguono il modello delle live collections di Astro e restituiscono { entries, error } per le collection e { entry, error } per singole voci:

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

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

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

Per una singola voce:

---
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 massima sicurezza di tipo, genera i tipi dallo schema del database:

npx emdash types

Crea .emdash/types.ts con interfacce per tutte le collection. L’editor completerà i nomi dei campi e segnalerà errori di tipo.

Passi successivi

Ora hai un sito EmDash funzionante! Continua da qui:

• Concetti fondamentali — Come funziona EmDash sotto il cofano
• Lavorare con i contenuti — Interrogare e renderizzare i contenuti
• Libreria media — Caricare e gestire immagini e file
• Creare un blog — Costruire un blog con categorie e tag
• Distribuire su Cloudflare — Portare il sito in produzione