시작하기

이 가이드는 설치부터 첫 글 게시까지 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

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

환경 변수

프로덕션 배포에서는 다음을 설정해야 합니다:

# Required for authentication
EMDASH_AUTH_SECRET=your-secret-here

# Optional: for content preview
EMDASH_PREVIEW_SECRET=your-preview-secret

안전한 인증 시크릿은 다음으로 생성합니다:

npx emdash auth secret

페이지에서 콘텐츠 조회하기

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

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

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

<Base title="Home">
  <h1>Latest Posts</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 사이트가 있습니다. 계속하려면:

• 핵심 개념 — EmDash 내부 동작 이해
• 콘텐츠 작업 — 조회와 렌더링
• 미디어 라이브러리 — 이미지와 파일 관리
• 블로그 만들기 — 카테고리와 태그가 있는 블로그
• Cloudflare에 배포 — 프로덕션으로 가져가기