2026년 Astro + Decap
Source: Dev.to
저는 오랫동안 생각해오던 프로젝트를 드디어 시작했습니다: 사진과 건축을 위한 유지보수가 쉬운 포트폴리오 블로그입니다.
이 기회를 통해 **Decap**을 탐색했습니다. Decap은 제가 한동안 사용해보고 싶었지만 아직 시도해보지 못한 Git 기반 CMS입니다. 몇 년 전, 비슷한 무언가를 고민하던 중 이 프로젝트를 발견했습니다.
저는 **Astro**와 작업하는 것을 정말 즐깁니다. 개인 블로그에 글을 쓸 때 자주 바랐던 것은 콘텐츠 게시의 마찰을 줄여주는 시각적인 인터페이스였습니다. 저는 사이트가 정적이었으면 좋겠어요—데이터베이스가 필요 없고(원하지도 않으며), 관리형 데이터베이스조차도 필요 없습니다—하지만 IDE나 Obsidian이 아닌, 제 블로그에 맞게 약간 더 맞춤화된 멋진 글쓰기 인터페이스가 있으면 좋겠습니다.
작업을 정상적으로 진행하는 데 예상보다 조금 더 시간이 걸렸기 때문에, 같은 스택을 사용하려는 다른 분들을 돕기 위해 이 글을 쓰기로 했습니다.
Decap 설치
문서에서 Decap을 설치하는 두 가지 방법이 있다는 것을 보았습니다:
- CDN 버전 사용.
npm같은 패키지 매니저 사용.
두 번째 옵션을 선택했지만 약간 막혔습니다: 그 다음은? 모듈을 어디서 import하고 호출하나요?
인증에 대한 간단한 메모
현재는 인증에 신경 쓰지 않았습니다; 에디터만 원했습니다. 이는 이 영역에 다른 솔루션이 있을 수 있음을 생각하게 했고, 테스트를 위해 실제 원격 저장소를 만들고 싶지 않았습니다. 로컬 저장소는 있지만 GitHub이나 GitLab에 푸시하고 싶지는 않았습니다.
그래서 올바르게 설정하는 데 시간이 더 걸리더라도 최소 설치를 원했습니다.
Astro를 사용한 기본 구조
1. /public 안의 config.yml
구성 파일은 공개 폴더에 있어야 합니다. 이는 인덱스에 Astro 페이지를 사용하고, 해당 페이지가 public 루트의 파일들을 참조하기 때문입니다.
# 기본 프록시 서버 포트를 사용할 때
local_backend: true
backend:
name: proxy
proxy_url: "http://localhost:8081/api/v1"
media_folder: "/src/assets/images/uploads"
collections:
- name: posts
folder: /src/pages/blog
label: "Posts"
fields:
- label: Title
name: title
widget: string2. 관리자 라우트 (/admin)
/src/pages/admin.astro 파일을 생성합니다:
---
---
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Admin – Decap CMS</title>
</head>
<body>
<script type="module">
import CMS from "decap-cms-app";
CMS.init();
</script>
</body>
</html>설명 – 스크립트는 Decap 문서에 나오는 코드와 본질적으로 동일합니다. 처음 설정할 때 혼란스러울 수 있어 약간의 추가 설명을 제공했습니다. 모든 정보는 공식 문서와 저장소에서 가져온 것입니다.
Source: …
추가 참고 사항
1. 최소 config.yml
문서에는 많은 설정 옵션이 나열되어 있습니다(여기 보기). 하지만 간결한 시작 예제가 없습니다.
config.yml 파일을 /public에 두는 대신 HTML에 <script> 태그를 삽입할 수 있습니다:
<!-- 인라인 설정을 위한 예시 자리표시자 -->
<script type="module">
// 여기에서 인라인 Decap 설정을 넣을 수 있습니다
</script>이는 Decap 문서와 Astro 가이드에 설명된 대로입니다. 저는 설정을 한 곳에 모아두는 public 폴더 방식을 선호합니다.
2. 로컬 저장소
처음에 test-repo 백엔드를 사용해 보았는데, 빠른 확인에는 편리하지만 완전히 일시적이라 실제 프로젝트에는 적합하지 않았습니다.
로컬 Git 저장소와 작업하기 가이드(링크)가 정확히 필요했던 내용이었지만, 필요한 backend 설정을 명시하지 않았습니다. 제가 사용한 proxy 설정은 decap-server README에서 가져왔습니다.
3. CMS.registerPreviewTemplate
이 코드는 Decap CMS 설치와 수동 초기화 섹션에 나타납니다. 컬렉션 데이터를 렌더링하는 커스텀 미리보기 컴포넌트(React 컴포넌트)를 등록할 때 유용하지만, 기본 설정에는 필수되지 않습니다. 커스텀 미리보기가 필요할 때까지 안전하게 생략할 수 있습니다.
4. 로컬 저장소와 함께 실행하기
로컬에서 실행할 때는 Decap CMS가 Git에 의존하기 때문에 로컬 API가 필요합니다. 다른 종류의 스토리지를 추가하면 Git 기반 워크플로우의 목적에 어긋납니다.
로컬 프록시 서버를 시작하려면:
npx decap-server서버는 http://localhost:8081/api/v1( config.yml의 proxy_url과 일치)에서 청취합니다. local_backend: true로 설정하면 Decap CMS가 이 서버와 통신하여 변경 사항을 로컬 Git 저장소에 직접 커밋합니다.
TL;DR 체크리스트
-
config.yml추가를/public에 (또는<script>태그를 통해 참조). -
/src/pages/admin.astro생성 – Decap을 가져오고 초기화하는 스크립트를 포함. -
패키지 설치:
npm install decap-cms-app decap-server -
로컬 프록시 실행:
npx decap-server -
Astro 개발 서버 시작 (
npm run dev) 후/admin에 접속.
그게 전부입니다! 이제 외부 데이터베이스나 인증 레이어 없이 Astro 블로그용 최소한의 Git 기반 CMS를 갖게 되었습니다. 준비가 되면 커스텀 미리보기, 인증, 혹은 원격 Git 제공자를 추가해도 좋습니다. 즐거운 출판 되세요!
로컬 서버 실행
다른 포트에서 decap-server 를 사용하여 로컬 서버를 실행할 수 있습니다:
npx decap-server자세한 내용은 가이드 Working with a Local Git Repository 를 참고하세요.
보다 캡슐화된 대안
다른 옵션—공식 Astro 문서(CMS 가이드)에 있는 (현재 보관된) **Astro Decap CMS Starter**를 사용한—는 CDN에서 Decap CMS를 로드하고 /public 폴더에서 정적 HTML 파일을 제공하는 것입니다.
기술적인 관점에서 이는 잘 작동합니다:
- Decap 자체가 부팅되므로 Astro는 빌드 시 거의 작업을 하지 않습니다.
- 콘텐츠 관리는 Astro 빌드 프로세스와 완전히 독립적입니다.
더 맞춤화된 버전
이 글을 여기까지 읽었다면 이미 몇 가지 선택을 했다는 것을 알 수 있을 겁니다. 개인적인 취향의 문제이지만, 제가 가장 좋다고 생각하는 접근 방식과 그 이유를 설명합니다.
주요 장점
config.yml대신 코드 기반 설정./public폴더가 오염되지 않음.- 확장·맞춤화가 쉬움.
- 프라이버시 우선: Git 기반이지만 자격 증명을 노출할 필요 없음.
구현 방법
/src/pages/admin에 관리 라우트를 만들었습니다. 해당 페이지는 최소한의 HTML 파일을 포함하고 있으며:
- 일반 레이아웃을 사용하지 않음.
- Decap CMS를 로드하고 설정하는
<script>태그만 포함. - 업로드 파일을
/src/assets에 저장해 Astro가 나중에 처리하도록 함. - 별도 시스템이라기보다 기존 워크플로우를 자동화하는 느낌.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Astro Admin</title>
</head>
<body>
<script type="module">
import CMS from "decap-cms-app";
const config = {
localBackend: true,
backend: {
name: "proxy",
proxy_url: "http://localhost:8081/api/v1",
},
load_config_file: false,
media_folder: "/src/assets/images/",
collections: [
{
name: "posts",
label: "Posts",
folder: "src/blog",
create: true,
fields: [
{ label: "Title", name: "title", widget: "string" },
{ label: "Body", name: "body", widget: "markdown" },
{ label: "Created", name: "created", widget: "datetime" },
{ label: "Tags", name: "tags", widget: "list" },
],
},
],
};
CMS.init({ config });
</script>
</body>
</html>수동 초기화 과정은 Customizing Decap CMS → Manual Initialization 에서 확인할 수 있습니다. window.CMS_MANUAL_INIT = true 라인은 이제 필요하지 않습니다.
인증
현재는 인증을 의도적으로 제외했습니다. 필요하지 않으며, 불필요한 인증을 추가하면 큰 이점 없이 보안 취약점을 초래할 수 있습니다.