Primeiros passos

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

Pré-requisitos

• Node.js v22.16.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

Ao visitar o painel admin pela primeira vez, o assistente de configuração do EmDash guia você pela configuração inicial:

Uma vez que sua passkey é registrada, você está logado e redirecionado para o dashboard de administração.

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 de Live Collections
│   ├── pages/
│   │   ├── index.astro   # Página inicial
│   │   └── posts/
│   │       └── [...slug].astro  # Páginas dinâmicas de posts
│   ├── 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 o EmDash como integração Astro com um 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 UI admin é um 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 o EmDash ao sistema de conteúdo do Astro através de uma única live collection:

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 segredos 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 segredos de plugins em repouso. Defina-a agora para que sua implantação esteja pronta quando a criptografia de segredos de plugins a usar.

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

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

O segredo HMAC de preview e o salt de hash de IP do comentarista são gerados e armazenados no banco de dados no primeiro uso, então você não precisa defini-los. Sobrescreva o segredo 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. Elas seguem o padrão de live collections 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="Home">
  <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 única entrada 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 do seu esquema de banco de dados:

npx emdash types

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

Próximos passos

Com o site rodando, as seguintes páginas cobrem o que fazer em seguida:

• Conceitos fundamentais — Entender como o EmDash funciona internamente
• Trabalhando com conteúdo — Aprender a consultar e renderizar conteúdo
• Biblioteca de mídia — Fazer upload e gerenciar imagens e arquivos
• Criar um blog — Construir um blog completo com categorias e tags
• Implantar no Cloudflare — Levar seu site para produção