시작하기

이 가이드에서는 설치부터 첫 번째 게시물 발행까지 EmDash 사이트 만들기를 안내합니다.

사전 요구 사항

• Node.js v22.12.0 이상 (홀수 버전은 지원되지 않음)
• npm, pnpm 또는 yarn
• 코드 에디터 (VS Code 권장)

새 프로젝트 만들기

npm create emdash@latest

pnpm create emdash@latest

yarn create emdash

프롬프트에 따라 프로젝트 이름을 지정하고 설정을 구성합니다.

개발 서버 시작

설정 마법사 완료

관리 패널을 처음 방문하면 EmDash 설정 마법사가 초기 설정을 안내합니다:

패스키가 등록되면 로그인되어 관리 대시보드로 리디렉션됩니다.

첫 번째 게시물

프로젝트 구조

EmDash 프로젝트는 몇 가지 추가 사항이 있는 표준 Astro 구조를 따릅니다:

my-emdash-site/
├── astro.config.mjs      # Astro + EmDash 설정
├── src/
│   ├── live.config.ts    # Live Collections 설정
│   ├── pages/
│   │   ├── index.astro   # 홈페이지
│   │   └── posts/
│   │       └── [...slug].astro  # 동적 게시물 페이지
│   ├── layouts/
│   │   └── Base.astro    # 기본 레이아웃
│   └── components/       # Astro 컴포넌트
├── .emdash/
│   ├── seed.json         # 템플릿 시드 파일
│   └── types.ts          # 생성된 TypeScript 타입
└── package.json

설정 파일

astro.config.mjs

다음 설정은 로컬 SQLite 데이터베이스와 로컬 파일 스토리지로 EmDash를 Astro 통합으로 등록합니다:

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(), // 필수 — 관리 UI는 React 앱
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

src/live.config.ts

다음 파일은 단일 라이브 컬렉션을 통해 EmDash를 Astro의 콘텐츠 시스템에 연결합니다:

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

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

환경 변수

프로덕션용으로 다음 명령어로 플러그인 시크릿 암호화 키를 생성합니다:

npx emdash secrets generate

생성된 값을 아래와 같이 EMDASH_ENCRYPTION_KEY로 환경에 추가합니다. 이 키는 플러그인 시크릿을 저장 시 암호화합니다. 플러그인 시크릿 암호화가 사용할 때 배포가 준비되도록 지금 설정하세요.

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

키는 데이터베이스에 저장되지 않습니다 — 암호화된 암호문만 저장됩니다. 영구적인 곳에 백업하세요. 잃으면 그것으로 암호화된 모든 시크릿을 잃게 됩니다.

프리뷰 HMAC 시크릿과 댓글 작성자 IP 해시 솔트는 첫 사용 시 생성되어 데이터베이스에 저장되므로 설정할 필요가 없습니다. 아래와 같이 별도 프로세스가 메인 사이트와 동일한 토큰을 검증해야 하는 경우에만 프리뷰 시크릿을 오버라이드하세요.

EMDASH_PREVIEW_SECRET=your-preview-secret

페이지에서 콘텐츠 쿼리

Astro 페이지에서 EmDash의 쿼리 함수를 사용합니다. 이들은 Astro의 라이브 컬렉션 패턴을 따르며 컬렉션에는 { entries, error }, 단일 항목에는 { entry, error }를 반환합니다:

---
import { getEmDashCollection } from "emdash";
import Base from "../layouts/Base.astro";

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

<Base title="홈">
  <h1>최신 게시물</h1>
  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/posts/${post.slug}`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</Base>

다음 페이지는 슬러그로 단일 항목을 가져옵니다:

---
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>

TypeScript 타입 생성

완전한 타입 안전성을 위해 데이터베이스 스키마에서 타입을 생성합니다:

npx emdash types

이것은 모든 컬렉션의 인터페이스가 포함된 .emdash/types.ts를 생성합니다. 이제 에디터에서 필드 이름이 자동 완성되고 타입 오류가 감지됩니다.

다음 단계

사이트가 실행 중인 상태에서 다음 페이지들이 이후 할 일을 안내합니다:

• 핵심 개념 — EmDash가 내부적으로 어떻게 작동하는지 이해
• 콘텐츠 작업 — 콘텐츠 쿼리 및 렌더링 학습
• 미디어 라이브러리 — 이미지와 파일 업로드 및 관리
• 블로그 만들기 — 카테고리와 태그가 있는 완전한 블로그 구축
• Cloudflare에 배포 — 사이트를 프로덕션에 배포