Adicionar EmDash a um projeto Astro existente

Este guia adiciona EmDash a um projeto Astro e verifica a integração com uma entrada publicada. Ele usa o adaptador Node.js, SQLite e armazenamento local de mídia para que o caminho completo funcione em uma única máquina.

Antes de começar

Use Astro 6 ou posterior e Node.js 22.16 ou posterior. Verifique ambas as versões no projeto:

node --version
npx astro --version

Este guia altera o site para a saída server do Astro e configura o adaptador Node.js. Isso muda como o site é construído e implantado. Se o projeto já usa outro adaptador de servidor, não adicione um segundo. Mantenha esse adaptador e siga seus requisitos de deploy; para Cloudflare, use o guia Cloudflare Workers.

Faça commit ou salve de outra forma o projeto atual antes de alterar sua configuração.

Instalar o EmDash

Instale o EmDash, o adaptador Node.js e suporte a React:
npm
```
npm install emdash @astrojs/node @astrojs/react react react-dom
```
pnpm
```
pnpm add emdash @astrojs/node @astrojs/react react react-dom
```
yarn
```
yarn add emdash @astrojs/node @astrojs/react react react-dom
```
EmDash usa React para o painel de administração mesmo quando o site público não tem componentes React.

Registre o adaptador, React e EmDash em astro.config.mjs. Se o arquivo já contém outras integrações ou configurações, mantenha-as e adicione as entradas relevantes deste exemplo:

import node from "@astrojs/node";
import react from "@astrojs/react";
import { defineConfig } from "astro/config";
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",
            }),
        }),
    ],
});

SQLite armazena o conteúdo e o modelo de conteúdo em data.db. O adaptador de armazenamento local escreve mídia em uploads/ e a serve pela rota de mídia do EmDash. Adicione ambos os caminhos ao .gitignore se não estiverem já excluídos.

Crie src/live.config.ts para conectar o EmDash ao sistema de conteúdo do Astro:
```
import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
    _emdash: defineLiveCollection({ loader: emdashLoader() }),
};
```
Se o projeto já tem src/live.config.ts, adicione a entrada _emdash ao objeto collections exportado em vez de substituir o arquivo. Um src/content.config.ts separado para coleções baseadas em arquivo continua funcionando junto.
Gere uma chave de criptografia local e escreva-a em .env:
```
npx emdash secrets generate --write .env
```
Confirme que .env está excluído pelo .gitignore. A chave protege secrets de plugins armazenados no banco de dados. Substituir ou perder a chave torna esses valores criptografados ilegíveis, então mantenha um backup protegido antes de implantar o site.

Configurar o site e conteúdo

Inicie o servidor de desenvolvimento:
```
npm run dev
```
Abra http://localhost:4321/_emdash/admin/. A primeira visita redireciona para o assistente de configuração. Insira os detalhes do site, crie a conta de administrador e registre um passkey.

Como este projeto não tem arquivo seed, a configuração aplica o modelo inicial integrado do EmDash. Ele cria coleções de Posts e Pages, campos de Título e conteúdo, e taxonomias de Categoria e Tag. Não adiciona entradas de exemplo.
Abra Posts, selecione New Post e insira EmDash is connected como título. Selecione Save para criar a entrada, depois selecione Publish.

O banco de dados agora contém uma entrada publicada na coleção integrada posts. O próximo passo a lê de uma página Astro.

Consultar a entrada

Crie uma página de teste renderizada no servidor que liste os posts publicados:

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

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

if (error) {
	throw error;
}
---

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

Abra http://localhost:4321/emdash-test/. A página exibe EmDash is connected. Se você alterar e republicar o título no painel de admin, recarregar esta página exibe o título atualizado.

Durante o desenvolvimento local, EmDash também gera emdash-env.d.ts do modelo de conteúdo atual. As declarações geradas dão ao TypeScript o nome da coleção posts e seu campo title. Não edite esse arquivo gerado manualmente.

Se a verificação falhar

Se o admin permanecer em Loading EmDash…, verifique se react() aparece no array integrations do Astro. Instalar @astrojs/react sem registrá-lo não é suficiente.
Se getEmDashCollection() retornar um erro sobre a coleção live, verifique se src/live.config.ts exporta _emdash com emdashLoader().
Se a página funciona no desenvolvimento mas edições implantadas não aparecem, verifique se a página não está pré-renderizada e se a aplicação implantada usa saída de servidor.
Se o build não consegue resolver uma das importações, execute novamente o comando de instalação e confirme que os cinco pacotes foram adicionados a este projeto e não a outro diretório do workspace.

Leia Configuração para outros bancos de dados, adaptadores de armazenamento e opções de autenticação. O guia de consulta de conteúdo cobre filtros, paginação, previews e dicas de cache.