Primeiros passos

Este guia te acompanha na criação do seu primeiro site EmDash, da instalação à publicação do seu primeiro post.

Pré-requisitos

• Node.js v22.12.0 ou superior (versões ímpares não são suportadas)
• npm, pnpm ou yarn
• Um editor de código (VS Code recomendado)

Criar um novo projeto

npm create emdash@latest

pnpm create emdash@latest

yarn create emdash

Siga as instruções para nomear seu projeto e configurar suas preferências.

Iniciar o servidor de desenvolvimento

Completar o assistente de configuração

Quando você visita o painel admin pela primeira vez, o Assistente de Configuração do EmDash te guia pela configuração inicial:

Uma vez que sua passkey está registrada, você está logado e redirecionado para o painel admin.

Seu primeiro post

Estrutura do projeto

Seu projeto EmDash segue uma estrutura Astro padrão com algumas adições:

my-emdash-site/
├── astro.config.mjs      # Configuração Astro + EmDash
├── src/
│   ├── live.config.ts    # Configuração Live Collections
│   ├── pages/
│   │   ├── index.astro   # Página inicial
│   │   └── posts/
│   │       └── [...slug].astro  # Páginas de posts dinâmicas
│   ├── layouts/
│   │   └── Base.astro    # Layout base
│   └── components/       # Seus componentes Astro
├── .emdash/
│   ├── seed.json         # Arquivo seed do template
│   └── types.ts          # Tipos TypeScript gerados
└── package.json

Arquivos de configuração

astro.config.mjs

A seguinte configuração registra EmDash como integração Astro com banco de dados SQLite local e armazenamento de arquivos 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(), // Obrigatório — a interface admin é uma app React
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

src/live.config.ts

O seguinte arquivo conecta EmDash ao sistema de conteúdo do Astro através de uma única coleção ao vivo:

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

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

Variáveis de ambiente

Para produção, gere uma chave de criptografia para secrets de plugins com o seguinte comando:

npx emdash secrets generate

Adicione o valor gerado ao seu ambiente como EMDASH_ENCRYPTION_KEY, como mostrado abaixo. Esta chave criptografa secrets de plugins em repouso. Configure-a agora para que seu deploy esteja pronto quando a criptografia de secrets de plugins a usar.

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

A chave nunca é armazenada no banco de dados — apenas texto cifrado criptografado. Faça backup em um lugar durável, porque perdê-la significa perder cada secret criptografado com ela.

O secret HMAC de preview e o salt de hash de IP de comentaristas são gerados e armazenados no banco de dados no primeiro uso, então você não precisa configurá-los. Sobrescreva o secret de preview apenas se um processo separado precisar verificar os mesmos tokens do seu site principal, como mostrado abaixo.

EMDASH_PREVIEW_SECRET=your-preview-secret

Consultar conteúdo nas páginas

Use as funções de consulta do EmDash nas suas páginas Astro. Estas seguem o padrão de coleções ao vivo do Astro, retornando { entries, error } para coleções e { entry, error } para entradas individuais:

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

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

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

A seguinte página busca uma 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>

Gerar tipos TypeScript

Para segurança de tipos completa, gere tipos a partir do schema do seu banco de dados:

npx emdash types

Isso cria .emdash/types.ts com interfaces para todas as suas coleções. Seu editor agora irá autocompletar nomes de campos e detectar erros de tipo.

Próximos passos

Com o site rodando, as seguintes páginas cobrem o que fazer a seguir:

• Conceitos fundamentais — Entenda como o EmDash funciona internamente
• Trabalhando com conteúdo — Aprenda a consultar e renderizar conteúdo
• Biblioteca de mídia — Faça upload e gerencie imagens e arquivos
• Criar um blog — Construa um blog completo com categorias e tags
• Deploy no Cloudflare — Leve seu site para produção