시작하기

이 가이드는 설치부터 첫 게시물 발행까지 첫 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 emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	integrations: [
		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="Home">
  <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에 배포 — 사이트를 프로덕션으로 이동