EmDash CMS 프로젝트 부트스트랩 및 디렉터리 레이아웃

게시일 2026-04-08 작성자 Emdash Cms Everything

이 가이드 대상

빈 저장소에서 시작하면서 다음을 지원하는 디렉터리 구조를 원할 때 이 가이드를 사용하세요.

• 매일 편집 콘텐츠 변경
• CMS 가정을 깨지 않는 프런트엔드 반복
• 나중에 로컬 개발에서 Cloudflare로의 배포 이동

목표는 가장 영리한 폴더 트리가 아니라 장기 유지보수 비용을 줄이는 것입니다.

먼저 런타임 결정하기

파일을 만들기 전에 향후 30~90일에 최적화할 런타임을 정하세요.

• 가장 빠른 로컬 온보딩과 가장 낮은 운영 복잡도를 위한 Node.js + SQLite
• 프로덕션 SSR, 관리형 저장소, EmDash 플러그인 모델과의 긴밀한 통합을 위한 Cloudflare Workers + D1 + R2

팀이 아직 콘텐츠 전략을 검증 중이면 먼저 Node.js로 시작하고 첫날부터 Cloudflare에 맞는 이름을 유지하세요. 초기 플랫폼 종속을 피하면서 이전은 단순하게 유지됩니다.

권장 기준 디렉터리 레이아웃

your-emdash-site/
├── src/
│   ├── components/            # 재사용 UI 조각만
│   ├── layouts/               # 공유 페이지 셸
│   ├── pages/                 # Astro 라우트
│   ├── lib/                   # 도메인 로직 및 통합
│   ├── styles/                # 전역 및 공유 스타일 토큰
│   └── live.config.ts         # 라이브 콘텐츠 컬렉션 매핑
├── seed/                      # 부트스트랩/데모용 시드 데이터
├── public/                    # 정적 자산(파비콘, 정적 이미지)
├── docs/                      # 제품 문서 및 편집 콘텐츠(MDX)
├── astro.config.mjs
├── package.json
├── tsconfig.json
└── emdash-env.d.ts

기존 프로젝트가 이미 lib/ 대신 utils/를 쓴다면 지금은 유지하세요. 명확한 소유 규칙을 강제할 수 있을 때만 이름을 바꿉니다.

디렉터리 소유 모델

구조는 소유가 명확할 때만 동작합니다.

• src/components: 표현 전용 단위; DB나 스토리지 직접 호출 없음
• src/layouts: 공유 프레임 관심사(head 태그, 내비 프레임, 푸터 셸)
• src/pages: 렌더링을 위한 라우트 구성 및 데이터 연결
• src/lib: 비즈니스 규칙, 데이터 어댑터, 플랫폼별 접착 코드
• seed: 새 환경을 위한 재현 가능한 기준 콘텐츠

이 분리는 가장 흔한 이탈인 “유틸 코드가 조용히 비즈니스 로직이 됨”을 막습니다.

재작업을 피하는 부트스트랩 경로

프로덕션 프로젝트에는 다음 순서를 사용하세요.

1. 공식 스캐폴드로 생성
2. 템플릿 하나 선택(블로그, 마케팅, 포트폴리오)
3. 명확한 팀 표준과 충돌하지 않는 한 생성된 관례 유지
4. 구조 커스터마이징은 한 번에 하나만 추가

이 순서가 중요한 이유: 대부분의 런치 지연은 기능 부족이 아니라 나중에 문서·스크립트·온보딩을 깨는 초기 구조적 분기에서 옵니다.

권장 부트스트랩 명령

# 새 EmDash CMS 프로젝트 스캐폴딩
npm create emdash@latest my-emdash-site
cd my-emdash-site

# 설치 및 로컬 개발 시작
npm install
npm run dev

피해야 할 흔한 안티패턴

1) 콘텐츠 모델 결정 없이 라우트 우선 코딩

컬렉션과 분류 체계 형태에 합의하기 전에 페이지 라우트를 짓면 비싼 재작업이 생깁니다.

2) UI 폴더에 배포 관심사 섞기

components나 pages 아래에 배포 전용 스크립트와 설정 헬퍼를 두지 마세요. 플랫폼 관심사는 설정 파일과 src/lib에 두세요.

3) 무제한 utils 폴더

모든 것이 utils로 가면 발견 가능성이 무너집니다. src/lib/content, src/lib/media, src/lib/auth 같은 이름 있는 도메인을 선호하세요.

초기 프로젝트 설정의 완료 정의

다음 검사를 모두 통과할 때만 부트스트랩을 완료로 간주하세요.

• 로컬 개발 서버가 수동 패치 없이 실행됨
• 샘플 콘텐츠 흐름 하나가 끝까지 동작
• 새 환경에서 시드 데이터를 가져올 수 있음
• CI 빌드가 환경별 핵 없이 통과
• 새 기여자가 저장소를 10분 안에 탐색 가능

다음에 할 일

구조가 안정되면:

1. 저장소에 런타임 선택과 이전 기준 문서화
2. 볼륨이 커지기 전에 콘텐츠 타입 명명 규칙 정의
3. 선택한 플랫폼에 대한 배포 런북 구현

디렉터리 구조는 꾸밈이 아니라 아키텍처입니다. 일찍 고정하면 나중에 주를 아낍니다.