Primeros pasos

Esta guía te lleva paso a paso a crear tu primer sitio EmDash, desde la instalación hasta la publicación de tu primer post.

Prerrequisitos

• Node.js v22.16.0 o superior (versiones impares no son compatibles)
• npm, pnpm o yarn
• Un editor de código (VS Code recomendado)

Crear un nuevo proyecto

npm create emdash@latest

pnpm create emdash@latest

yarn create emdash

Sigue las indicaciones para nombrar tu proyecto y configurar tus preferencias.

Iniciar el servidor de desarrollo

Completar el asistente de configuración

Al visitar el panel de administración por primera vez, el asistente de configuración de EmDash te guía a través de la configuración inicial:

Una vez registrado tu passkey, estás conectado y redirigido al panel de administración.

Tu primer post

Estructura del proyecto

Tu proyecto EmDash sigue una estructura Astro estándar con algunas adiciones:

my-emdash-site/
├── astro.config.mjs      # Configuración de Astro + EmDash
├── src/
│   ├── live.config.ts    # Configuración de Live Collections
│   ├── pages/
│   │   ├── index.astro   # Página principal
│   │   └── posts/
│   │       └── [...slug].astro  # Páginas dinámicas de posts
│   ├── layouts/
│   │   └── Base.astro    # Layout base
│   └── components/       # Tus componentes Astro
├── .emdash/
│   ├── seed.json         # Archivo seed del template
│   └── types.ts          # Tipos TypeScript generados
└── package.json

Archivos de configuración

astro.config.mjs

La siguiente configuración registra EmDash como una integración de Astro con una base de datos SQLite local y almacenamiento de archivos local:

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(), // Requerido — la UI de admin es una app React
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

src/live.config.ts

El siguiente archivo conecta EmDash con el sistema de contenido de Astro a través de una única live collection:

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

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

Variables de entorno

Para producción, genera una clave de cifrado para los secretos de plugins con el siguiente comando:

npx emdash secrets generate

Añade el valor generado a tu entorno como EMDASH_ENCRYPTION_KEY, como se muestra abajo. Esta clave cifra los secretos de plugins en reposo. Establécela ahora para que tu despliegue esté listo cuando el cifrado de secretos de plugins la use.

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

La clave nunca se almacena en la base de datos — solo texto cifrado. Haz una copia de seguridad en un lugar duradero, porque perderla significa perder cada secreto cifrado con ella.

El secreto HMAC de preview y el salt de hash de IP del comentarista se generan y almacenan en la base de datos en el primer uso, por lo que no necesitas establecerlos. Sobrescribe el secreto de preview solo si un proceso separado necesita verificar los mismos tokens que tu sitio principal, como se muestra abajo.

EMDASH_PREVIEW_SECRET=your-preview-secret

Consultar contenido en páginas

Usa las funciones de consulta de EmDash en tus páginas Astro. Estas siguen el patrón de live collections de Astro, devolviendo { entries, error } para colecciones y { entry, error } para entradas individuales:

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

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

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

La siguiente página obtiene una entrada individual por 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>

Generar tipos TypeScript

Para seguridad de tipos completa, genera tipos desde tu esquema de base de datos:

npx emdash types

Esto crea .emdash/types.ts con interfaces para todas tus colecciones. Tu editor ahora autocompletará los nombres de campos y detectará errores de tipos.

Próximos pasos

Con el sitio funcionando, las siguientes páginas cubren qué hacer a continuación:

• Conceptos fundamentales — Entender cómo funciona EmDash internamente
• Trabajar con contenido — Aprender a consultar y renderizar contenido
• Biblioteca de medios — Subir y gestionar imágenes y archivos
• Crear un blog — Construir un blog completo con categorías y etiquetas
• Desplegar en Cloudflare — Llevar tu sitio a producción