EmDash & Astro

EmDash는 Astro를 위해 특별히 구축된 오픈 소스 풀스택 CMS로, 사이트에 데이터베이스 기반 콘텐츠, 관리자 UI, 미디어 라이브러리, 메뉴 및 분류 체계를 추가합니다.

새 Astro + EmDash 프로젝트를 처음부터 시작하려면, EmDash CLI를 사용하여 미리 구성된 프로젝트를 생성하세요:

npm create emdash@latest

pnpm create emdash@latest

yarn create emdash@latest

Astro와 통합

EmDash는 Astro 프로젝트 내에서 실행되며 데이터베이스를 사용합니다. /_emdash/admin에서 관리 인터페이스에 접근하여 콘텐츠를 편집할 수 있습니다. 페이지는 라이브 콘텐츠 컬렉션을 사용하여 데이터베이스를 쿼리함으로써 콘텐츠를 표시합니다.

이 가이드에서는 Node.js 어댑터와 로컬 SQLite 데이터베이스를 사용합니다. 지원되는 데이터베이스 목록은 EmDash 문서를 참조하세요.

전제 조건

어댑터와 함께 구성되고 output: "server"로 설정된 기존 Astro 프로젝트 (Astro 6 이상).
Node.js v22.16.0 이상.

종속성 설치

React는 EmDash 관리 인터페이스를 구동하며 필수 종속성입니다. 프로젝트에서 React를 사용하지 않는다면, 패키지 관리자에 맞는 astro add 명령을 사용하여 설치하세요:

npx astro add react

pnpm astro add react

yarn astro add react

EmDash 패키지도 설치해야 합니다:

npm install emdash

pnpm add emdash

yarn add emdash

통합 추가하기

Astro 구성 파일에 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",
      }),
    }),
  ],
});

라이브 컬렉션 로더 추가하기

Astro의 콘텐츠 계층이 EmDash 콘텐츠를 해석할 수 있도록 src/live.config.ts 파일을 생성하세요:

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

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

_emdash 컬렉션은 내부적으로 콘텐츠 타입(예: posts와 pages)으로 라우팅됩니다. src/content.config.ts에 있는 기존 파일 기반 컬렉션은 그대로 함께 계속 동작합니다.

EmDash 로컬에서 실행하기

자체 페이지를 테스트하기 전에 설정 마법사를 완료해야 합니다. 설정이 완료될 때까지 게시된 콘텐츠가 없으며 쿼리는 빈 결과를 반환합니다.

데이터베이스를 초기화하고 관리 UI를 실행하려면 Astro 개발 서버를 시작하세요:
- npm
- pnpm
- Yarn
터미널 창
npm run dev
터미널 창
pnpm run dev
터미널 창
yarn run dev
처음 실행하면 EmDash는 스키마와 두 개의 기본 컬렉션인 pages와 posts를 포함하는 data.db를 생성합니다.
브라우저에서 http://localhost:4321/_emdash/admin을 방문하세요. EmDash가 설정 마법사로 리디렉션합니다.
Site 단계에서 사이트 제목과 선택 사항인 태그라인을 입력하세요.
Account 단계에서 이메일 주소와 이름을 입력하세요. 이렇게 하면 관리자 계정이 생성됩니다.
Sign In 단계에서 계정을 보호하세요. 기기의 생체 인식 인증, 보안 키 또는 PIN으로 패스키를 등록하려면 Create Passkey를 선택하세요.
새 패스키로 로그인하여 대시보드로 이동하세요.

첫 게시물 만들기

대시보드에서 + Post 버튼을 클릭하세요.
제목과 콘텐츠를 추가하세요. EmDash는 리치 텍스트를 블록 편집기에서 편집되는 Portable Text로 저장합니다. URL 슬러그는 제목에서 생성되며 사이드바에서 편집할 수 있습니다.
Save를 클릭한 다음 Publish를 클릭하세요. 게시된 게시물만 사이트 방문자에게 표시됩니다.

EmDash 콘텐츠 렌더링하기

getEmDashCollection()과 getEmDashEntry()로 콘텐츠를 쿼리하세요. 둘 다 라이브 컬렉션 패턴을 따르며 요청 시점에 결과를 반환하므로, 다시 빌드하지 않아도 게시된 변경 사항이 표시됩니다.

게시물 목록 표시하기

다음 예시는 게시된 모든 게시물 제목 목록을 표시하며, 각 제목은 개별 게시물 페이지로 연결됩니다:

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

const { entries: posts } = await getEmDashCollection("posts", {
  status: "published",
});
---
<ul>
  {posts.map((post) => (
    <li>
      <a href={`/posts/${post.data.slug}`}>{post.data.title}</a>
    </li>
  ))}
</ul>

단일 게시물 표시하기

개별 게시물의 콘텐츠를 표시하려면 슬러그로 게시물을 가져온 뒤 <PortableText /> 컴포넌트로 Portable Text 콘텐츠를 렌더링하세요:

---
import { getEmDashEntry } from "emdash";
import { PortableText } from "emdash/ui";

const { slug } = Astro.params;
const { entry: post } = await getEmDashEntry("posts", slug);

if (!post) {
  return Astro.redirect("/404");
}
---
<article>
  <h1>{post.data.title}</h1>
  <PortableText value={post.data.content} />
</article>