Primeros pasos

Esta guía te acompaña en la creación de tu primer sitio EmDash, desde la instalación hasta la publicación de tu primera entrada.

Requisitos previos

• Node.js v22.12.0 o superior (las 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

Cuando visitas por primera vez el panel de administración, 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 primera entrada

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 entradas
│   ├── layouts/
│   │   └── Base.astro    # Layout base
│   └── components/       # Tus componentes Astro
├── .emdash/
│   ├── seed.json         # Archivo seed de plantilla
│   └── types.ts          # Tipos TypeScript generados
└── package.json

Archivos de configuración

astro.config.mjs

La siguiente configuración registra EmDash como integración 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 interfaz 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 al sistema de contenido de Astro a través de una única colección en vivo:

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 secrets 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 a continuación. Esta clave cifra los secrets de plugins en reposo. Configúrala ahora para que tu despliegue esté listo cuando el cifrado de secrets de plugins la use.

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

La clave nunca se almacena en la base de datos — solo texto cifrado. Resguárdala en un lugar duradero, porque perderla significa perder cada secret cifrado con ella.

El secret HMAC de preview y el salt de hash de IP de comentaristas se generan y almacenan en la base de datos en el primer uso, por lo que no necesitas configurarlos. Sobrescribe el secret de preview solo si un proceso separado necesita verificar los mismos tokens que tu sitio principal, como se muestra a continuación.

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 colecciones en vivo 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="Inicio">
  <h1>Últimas entradas</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 el esquema de tu base de datos:

npx emdash types

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

Próximos pasos

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

• Conceptos fundamentales — Comprende cómo funciona EmDash internamente
• Trabajar con contenido — Aprende a consultar y renderizar contenido
• Biblioteca de medios — Sube y gestiona imágenes y archivos
• Crear un blog — Construye un blog completo con categorías y etiquetas
• Desplegar en Cloudflare — Lleva tu sitio a producción