Primeros Pasos

Esta guía te llevará a través de 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 con números impares no están soportadas)
• npm, pnpm o yarn
• Un editor de código (se recomienda VS Code)

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 visites el panel de administración por primera vez, el Asistente de Configuración de EmDash te guiará a través de la configuración inicial:

Una vez que tu passkey esté registrado, habrás iniciado sesión y serás redirigido al panel de administración.

Tu primera entrada

Estructura del proyecto

Tu proyecto EmDash sigue una estructura estándar de Astro 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 de inicio
│   │   └── 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 una integración de Astro con una base de datos SQLite local y almacenamiento de archivos local:

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

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 secretos de plugins con el siguiente comando:

npx emdash secrets generate

Agrega el valor generado a tu entorno como EMDASH_ENCRYPTION_KEY, como se muestra a continuación. Esta clave cifra los secretos de plugins en reposo. Configúrala ahora para que tu despliegue esté listo cuando el cifrado de secretos de plugins lo use.

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

La clave nunca se almacena en la base de datos — solo se almacena el texto cifrado. Haz una copia de seguridad en algún lugar duradero, porque perderla significa perder todos los secretos cifrados con ella.

El secreto HMAC de vista previa y el salt de hash de IP de comentarista se generan y almacenan en la base de datos en el primer uso, por lo que no necesitas configurarlos. Sobrescribe el secreto de vista previa 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="Home">
  <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 una 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 básicos — 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