Adicionar EmDash a um projeto Astro existente

npm create emdash@latest fornece um projeto pré-configurado, mas o EmDash também se integra a um site Astro que você já tem. Este guia percorre cada requisito que o template inicial normalmente cuida para você — cada um produz um erro confuso quando está faltando, então siga a lista na ordem.

Pré-requisitos

Astro 6 ou posterior — atualize primeiro se estiver em uma versão major anterior (npx @astrojs/upgrade)
Node.js v22.16.0 ou superior (versões ímpares não são suportadas)
Saída de servidor — EmDash serve conteúdo em tempo de execução, então seu projeto precisa de output: "server" e um adaptador (Node, Cloudflare, …)

Instalar os pacotes

Instale o EmDash junto com suas dependências peer necessárias. O React alimenta a interface admin em /_emdash/admin; é necessário mesmo que seu site em si não use React.

npm

npm install emdash @astrojs/react react react-dom

pnpm

pnpm add emdash @astrojs/react react react-dom

yarn

yarn add emdash @astrojs/react react react-dom

Implantando no Cloudflare? Adicione os pacotes Cloudflare também — o guia Implantar no Cloudflare os cobre em detalhes:

npm install @astrojs/cloudflare @emdash-cms/cloudflare

Registrar as integrações

Adicione tanto react() quanto emdash() ao seu array integrations. Registrar @astrojs/react não é opcional: instalar apenas o pacote não é suficiente, e sem a integração o admin compila bem mas nunca hidrata — a página fica em “Loading EmDash…” para sempre.

import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import react from "@astrojs/react";
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	output: "server",
	adapter: node({ mode: "standalone" }),
	integrations: [
		react(),
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

Adicionar o loader de Live Collections

Crie src/live.config.ts para que a camada de conteúdo do Astro possa resolver o conteúdo EmDash. Sem ele, getEmDashCollection / getEmDashEntry não têm uma live collection para rotear.

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

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

Seu src/content.config.ts existente (coleções baseadas em arquivos) continua funcionando ao lado — veja EmDash para desenvolvedores Astro para como os dois coexistem.

Verificar a instalação

Inicie o servidor de desenvolvimento:
```
npm run dev
```
Abra http://localhost:4321/_emdash/admin e complete o assistente de configuração.

Crie e publique um post, depois consulte-o de uma página:

---
import { getEmDashCollection } from "emdash";

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

<ul>{posts.map((post) => <li>{post.data.title}</li>)}</ul>

Implantar no Cloudflare

Siga Implantar no Cloudflare para a configuração completa (banco de dados D1, bucket de mídia R2, cron triggers). Duas coisas atrapalham projetos existentes em particular:

Use Cloudflare Workers, não Pages. O adaptador @astrojs/cloudflare emite um wrangler.json que Pages não aceita. Se seu site atualmente implanta no Pages, migre-o para Workers primeiro.
Os bindings devem existir no seu wrangler.jsonc. No mínimo você precisa de um binding D1 para o banco de dados e um binding R2 para mídia, correspondendo aos nomes de binding no seu astro.config.mjs.

Solução de problemas

Sintoma	Causa	Solução
Admin travado em “Loading EmDash…”	`@astrojs/react` não registrado	Adicionar `react()` a `integrations`
`Could not resolve "astro:content"` em `live.config.ts`	Astro anterior à 6	Atualizar Astro
`getEmDashCollection` retorna um erro	`src/live.config.ts` ausente	Adicionar o loader de live collections
Erros de build sobre pacotes não resolvidos	Dependências peer não instaladas	Instalar `@astrojs/react`, `react`, `react-dom` explicitamente
Alterações de conteúdo não aparecem	Página é pré-renderizada	Definir `export const prerender = false` em páginas dinâmicas

Próximos passos

EmDash para desenvolvedores Astro — Como os conceitos do EmDash se mapeiam ao que você já conhece
Trabalhando com conteúdo — Consultar e renderizar conteúdo
Implantar no Cloudflare — Levar o site para produção