기존 Astro 프로젝트에 EmDash 추가하기

npm create emdash@latest는 사전 구성된 프로젝트를 제공하지만, EmDash는 이미 가지고 있는 Astro 사이트에도 통합할 수 있습니다. 이 가이드는 스타터 템플릿이 일반적으로 처리해주는 모든 요구 사항을 안내합니다 — 각각이 빠지면 혼란스러운 오류를 발생시키므로 체크리스트를 순서대로 진행하세요.

사전 요구 사항

Astro 6 이상 — 이전 메이저 버전이라면 먼저 업그레이드하세요 (npx @astrojs/upgrade)
Node.js v22.16.0 이상 (홀수 버전은 지원되지 않습니다)
서버 출력 — EmDash는 런타임에 콘텐츠를 제공하므로 프로젝트에 output: "server"와 어댑터 (Node, Cloudflare, …)가 필요합니다

패키지 설치

EmDash를 필요한 피어 의존성과 함께 설치합니다. React는 /_emdash/admin의 관리 UI를 구동합니다. 사이트 자체가 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

Cloudflare에 배포하시나요? Cloudflare 패키지도 추가하세요 — Cloudflare에 배포 가이드에서 자세히 다룹니다:

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

통합 등록

react()와 emdash() 모두 integrations 배열에 추가합니다. @astrojs/react 등록은 선택 사항이 아닙니다: 패키지만 설치하는 것으로는 충분하지 않으며, 통합 없이는 관리 화면이 빌드는 되지만 하이드레이션되지 않습니다 — 페이지가 “Loading EmDash…”에서 영원히 멈춥니다.

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",
			}),
		}),
	],
});

Live Collections 로더 추가

src/live.config.ts를 생성하여 Astro의 콘텐츠 레이어가 EmDash 콘텐츠를 해석할 수 있도록 합니다. 이것이 없으면 getEmDashCollection / getEmDashEntry에 라우팅할 라이브 컬렉션이 없습니다.

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

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

기존 src/content.config.ts(파일 기반 컬렉션)은 그대로 작동합니다 — 두 가지가 어떻게 공존하는지는 Astro 개발자를 위한 EmDash를 참조하세요.

설치 확인

개발 서버 시작:
```
npm run dev
```
http://localhost:4321/_emdash/admin을 열고 설정 마법사를 완료합니다.

게시물을 만들고 게시한 다음 페이지에서 쿼리합니다:

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

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

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

Cloudflare에 배포

전체 설정(D1 데이터베이스, R2 미디어 버킷, 크론 트리거)은 Cloudflare에 배포를 따르세요. 기존 프로젝트에서 특히 문제가 되는 두 가지:

Cloudflare Workers를 사용하세요, Pages가 아닙니다. @astrojs/cloudflare 어댑터는 Pages가 받아들이지 않는 wrangler.json을 출력합니다. 사이트가 현재 Pages에 배포되고 있다면 먼저 Workers로 마이그레이션하세요.
바인딩이 wrangler.jsonc에 있어야 합니다. 최소한 데이터베이스용 D1 바인딩과 미디어용 R2 바인딩이 필요하며, astro.config.mjs의 바인딩 이름과 일치해야 합니다.

문제 해결

증상	원인	해결
관리 화면이 “Loading EmDash…”에서 멈춤	`@astrojs/react` 미등록	`react()`를 `integrations`에 추가
`live.config.ts`에서 `Could not resolve "astro:content"`	Astro 6 미만	Astro 업그레이드
`getEmDashCollection`이 오류 반환	`src/live.config.ts` 없음	Live Collections 로더 추가
미해결 패키지에 대한 빌드 오류	피어 의존성 미설치	`@astrojs/react`, `react`, `react-dom` 명시적으로 설치
콘텐츠 변경이 표시되지 않음	페이지가 프리렌더링됨	동적 페이지에 `export const prerender = false` 설정

다음 단계

Astro 개발자를 위한 EmDash — EmDash 개념이 이미 알고 있는 것에 어떻게 매핑되는지
콘텐츠 작업하기 — 콘텐츠 쿼리 및 렌더링
Cloudflare에 배포 — 사이트를 프로덕션으로