Decap CMS 유저가 Sveltia로 넘어올 때 가장 많이 묻는 질문

"Decap CMS에 설정 파일 하나만 던져도 된다면서요? 진짜예요?"

Sveltia CMS의 GitHub 저장소를 처음 열어본 사람이 가장 많이 하는 질문이다. 답은 "거의 그렇다"다. config.yml을 그대로 가져다 놓으면 Sveltia가 알아서 읽고 동작한다. 컬렉션 정의, 필드 타입, 위젯 설정까지 Decap CMS 문법과 호환되도록 설계되어 있기 때문에 별도 마이그레이션 유틸리티를 돌리거나 설정을 전면 재작성할 필요가 없다. 다만 Decap CMS에서만 동작하던 커스텀 프리뷰 템플릿이나 수동 등록한 커스텀 위젯은 Sveltia의 컴포넌트 모델에 맞춰 다시 작성해야 한다. Sveltia는 Svelte로 처음부터 새로 짰기 때문에 React 기반의 Decap CMS 프리뷰 컴포넌트를 그대로 쓸 수 없다는 점만 염두에 두면 된다.

"300KB라고 들었는데, 진짜 그 정도인가?"

맞다. Sveltia CMS의 전체 자바스크립트 번들은 gzip 기준 약 300KB 수준이다. 이게 왜 대단한 숫자인지 이해하려면 Decap CMS의 번들 크기를 떠올려야 한다. Decap CMS는 React, Immutable.js, Draft.js, 기타 유틸리티를 포함해 gzip 기준으로도 1MB를 훌쩍 넘겼다. Sveltia는 Svelte의 컴파일러가 프레임워크 런타임 자체를 제거해주는 특성 덕분에 처음부터 가벼울 수밖에 없는 구조다. 여기에 CodeMirror 같은 무거운 에디터 대신 경량 마크다운 에디터를 기본으로 채택하고, 아이콘 라이브러리도 필요한 것만 트리 셰이킹해 넣었다.

그런데 이 숫자가 단순히 자랑거리인 건 아니다. CMS 관리자 패널은 편집자가 매일 수십 번, 심지어 모바일 네트워크에서도 열어야 하는 도구다. 1MB짜리 자바스크립트를 3G 회선에서 로딩하는 경험과 300KB를 로딩하는 경험은 완전히 다르다. 무엇보다 Sveltia는 초기 로딩 이후 라우트 전환이 클라이언트 사이드에서 즉시 일어나도록 설계되어 있어서, 컬렉션 목록에서 에디터로 넘어갈 때마다 스피너를 바라보는 일이 거의 없다.

"GraphQL 미들웨어 없이 바로 쓴다는 게 무슨 뜻인가요?"

Decap CMS의 구조에서 가장 많은 불만이 나왔던 지점 중 하나다. Decap CMS는 Git 저장소에서 콘텐츠를 가져올 때 중간에 GraphQL 미들웨어를 거친다. 로컬 백엔드에서도 이 계층이 동작하기 때문에 npm run dev로 띄워도 미들웨어 초기화 시간이 소요됐다. 특히 콘텐츠가 수백 건 이상 쌓인 프로젝트라면 첫 로딩에 몇 초씩 걸리는 게 예사였다.

Sveltia는 이 GraphQL 계층을 없앴다. 대신 Git 저장소의 파일 트리를 직접 읽고 Svelte의 반응형 스토어에 매핑하는 구조다. 엔트리 목록을 가져올 때 필요한 메타데이터만 먼저 로드하고, 실제 콘텐츠 본문은 편집기가 열릴 때 가져오는 지연 로딩 전략을 쓴다. 결과적으로 수백 개의 마크다운 파일이 있는 저장소에서도 관리자 패널이 1초 안에 반응한다. 이건 단순한 구현 차이가 아니라, "Git 기반 CMS에서 중간 계층이 정말 필요한가"라는 질문에 대한 설계 철학의 차이다.

"모바일에서 진짜 편집이 되나요? 터치 키보드로 프론트매터 입력하는 건 미친 짓 아닌가?"

이 질문을 하는 사람은 십중팔구 Decap CMS를 모바일에서 열어본 경험이 있다. 툴바 버튼이 손가락보다 작고, 마크다운 에디터와 프리뷰가 화면을 반씩 차지하며, 드롭다운 위젯이 화면 밖으로 튀어나가던 그 경험 말이다.

Sveltia는 처음부터 모바일을 1등 시민으로 설계했다. 전체 레이아웃이 CSS Container Query와 반응형 그리드로 구성되어 있어 화면 폭에 따라 편집기, 미디어 라이브러리, 메타데이터 패널이 자연스럽게 재배치된다. 이미지 업로드는 모바일 카메라로 직접 촬영해 인라인 삽입할 수 있고, 터치 인터페이스에 최적화된 날짜 선택기와 슬러그 생성기도 들어 있다. 블로그 포스팅 하나쯤은 카페에서 폰으로 쓰고 바로 퍼블리시할 수 있다는 말이 과장이 아닌 CMS가 여태까지 드물었다는 사실이 더 놀라울 정도다.

"다국어 사이트인데, 로케일마다 폴더를 따로 파야 하나요?"

Decap CMS의 다국어 설정은 솔직히 말해 고통이었다. i18n 설정을 config.yml에 수동으로 작성하고, 로케일별로 별도 컬렉션을 정의하거나 파일 경로에 로케일 접두사를 붙이는 방식을 써야 했다. Hugo나 Next.js에서 흔히 쓰는 파일 기반 라우팅과 충돌하는 경우도 많았다.

Sveltia는 다국어를 내장 기능으로 처리한다. config.yml에 i18n 구조를 한 번 정의하면 모든 필드에 대해 언어별 입력기가 자동으로 생성된다. 동일한 엔트리 안에서 언어 탭을 전환하며 각 로케일의 제목, 본문, 슬러그를 동시에 편집할 수 있다. 백엔드에서는 단일 파일에 모든 언어 데이터를 저장할지, 언어별로 파일을 분리할지 선택할 수 있다. 후자의 경우에도 Sveltia가 파일 간 연결을 자동으로 추적해준다. 무엇보다 번역이 누락된 필드는 편집기에서 시각적으로 표시되기 때문에, 일부 언어만 업데이트하고 배포하는 불상사를 막을 수 있다.

"OAuth 인증은 어떻게 하나요? GitHub App을 새로 만들어야 하나?"

Sveltia도 Decap CMS와 동일한 OAuth 방식을 사용한다. GitHub, GitLab, Bitbucket, Gitea, Azure DevOps를 공식 지원하며, 이미 Decap CMS용으로 발급받은 OAuth App 클라이언트 ID와 시크릿을 그대로 쓸 수 있다. 인증 플로우는 /admin/index.html에 Sveltia 스크립트를 로드하고 config.yml의 backend 섹션에 리포지토리 정보와 OAuth 설정을 넣는 것만으로 동작한다.

한 가지 알아둘 점은, Sveltia는 Netlify Identity 서비스가 필요하지 않다는 사실이다. Decap CMS가 Netlify에 묶여 있던 시절의 잔재다. Sveltia는 순수 Git 제공자의 OAuth만으로 인증을 완료하기 때문에 Netlify 계정이 없어도, Vercel이나 Cloudflare Pages에 호스팅해도 문제없이 돌아간다.

"커스텀 프리뷰 템플릿 없이도 내 사이트 디자인으로 미리보기가 되나요?"

이건 Sveltia가 Decap CMS보다 확실히 앞서는 지점이다. Sveltia는 인라인 프리뷰를 위해 별도의 React 컴포넌트를 요구하지 않는다. 대신 실제 사이트의 스타일시트 URL을 config.yml에 지정하면 편집기가 그 CSS를 로드해 마크다운 렌더링에 적용한다. 리스트 위젯이나 객체 위젯 같은 중첩 필드도 실시간으로 스타일이 반영된 채로 보여준다.

물론 이 방식의 한계도 명확하다. 정적 CSS만으로 표현할 수 없는 레이아웃, 예컨대 복잡한 그리드나 동적 컴포넌트 구조는 미리보기에서 재현되지 않는다. 그런 경우에는 Svelte 컴포넌트로 커스텀 프리뷰를 작성해야 한다. Svelte를 모르는 팀이라면 진입 장벽이 될 수 있지만, 컴포넌트 API 자체가 단순해서 몇 개의 prop을 받아 마크업을 반환하는 패턴만 익히면 금방 적응할 수 있다.

"기존 콘텐츠를 Sveltia로 옮기는 작업에서 가장 많이 실수하는 게 뭔가요?"

미디어 파일 경로 문제다. Decap CMS에서 업로드한 이미지의 경로는 보통 public/images/나 static/uploads/에 저장되고, 마크다운 본문에는 상대 경로나 절대 경로로 참조된다. Sveltia로 전환할 때 config.yml의 media_folder와 public_folder 설정이 Decap CMS 시절과 정확히 일치해야 기존 이미지가 그대로 보인다. 이걸 확인하지 않고 Sveltia를 먼저 띄우면 모든 이미지가 깨진 것처럼 보여서 당황하게 된다.

또 하나는 slug 템플릿의 차이다. Decap CMS는 {{slug}} 변수를 특정 방식으로 처리하는데, Sveltia는 더 엄격한 슬러그 정규화를 적용한다. 한글 제목의 경우 Decap CMS에서는 URL 인코딩되지 않은 유니코드 문자열이 그대로 슬러그가 되는 경우가 있었지만, Sveltia는 기본적으로 ASCII로 변환한다. 기존 파일명과 달라질 수 있으니 슬러그 생성 설정을 먼저 확인하는 게 좋다.

"에디터에서 갑자기 저장이 안 되는데, Git 충돌 때문인가요?"

맞을 확률이 높다. Git 기반 CMS가 공통으로 겪는 문제인데, 같은 엔트리를 두 명이 동시에 편집하거나, CMS가 열려 있는 동안 누군가 GitHub에서 직접 파일을 수정하면 충돌이 발생한다. Decap CMS는 충돌 상황에서 에디터가 묵묵부답이 되거나 "알 수 없는 오류"만 띄우는 경우가 많았다.

Sveltia는 충돌 감지 방식을 개선했다. 편집 세션을 시작할 때 엔트리의 Git 해시를 스냅샷으로 저장해두고, 저장 시점에 원격 저장소의 최신 해시와 비교한다. 충돌이 감지되면 구체적인 오류 메시지와 함께 "원격 변경 사항 덮어쓰기" 또는 "변경 사항 버리고 새로 로드" 옵션을 명시적으로 제시한다. 아무 설명 없이 빨간 토스트 메시지 하나 띄우는 게 아니라, 실제로 선택지를 준다는 점에서 운영 환경에서의 신뢰도가 다르다.

"Nested Collection이나 Polymorphic 관계 같은 고급 기능도 지원하나요?"

지원한다. Sveltia는 Decap CMS에서 가능했던 컬렉션 중첩과 참조 필드를 모두 계승했고, 여기에 타입 안전성을 더했다. 특히 선택적 타입 시스템을 도입해 특정 필드가 특정 타입일 때만 나타나는 조건부 필드를 config.yml에서 정의할 수 있다. Decap CMS에서는 이런 동적 폼을 구현하려면 커스텀 위젯을 작성해야 했지만, Sveltia는 선언적 설정만으로 충분하다.

다만 Decap CMS에는 있었지만 아직 Sveltia에 구현되지 않은 기능도 있다. 예를 들어 편집 워크플로우 중 "초안 → 리뷰 → 게시" 같은 커스텀 상태를 정의하는 Editorial Workflow는 로드맵에 올라와 있지만 2025년 기준으로 완전히 구현되지는 않았다. 편집 플로우를 엄격하게 통제해야 하는 대규모 팀이라면 이 부분을 먼저 확인해야 한다.

"Svelte를 전혀 모르는 팀인데, Sveltia를 도입해도 괜찮을까?"

Sveltia 자체는 프레임워크에 구애받지 않는다. 관리자 패널은 정적 HTML과 자바스크립트로 배포되기 때문에 사이트가 Hugo든, Next.js든, Astro든, Eleventy든, 심지어 순수 HTML이든 전혀 문제가 없다. config.yml 하나와 /admin/index.html 하나만 있으면 어떤 정적 사이트에도 관리자 패널을 붙일 수 있다는 점에서 Decap CMS와 완전히 동일한 철학을 따른다.

Svelte 지식이 필요한 순간은 오직 커스텀 프리뷰 컴포넌트나 커스텀 위젯을 직접 작성할 때뿐이다. 그마저도 Svelte의 컴포넌트 문법은 HTML, CSS, 자바스크립트 경험이 있는 사람이면 하루 만에 익힐 수 있을 정도로 직관적이다. 오히려 Decap CMS 시절 React와 Immutable.js의 개념을 익히느라 고생했던 기억이 있는 팀이라면 Sveltia의 접근 방식이 훨씬 가볍게 느껴질 것이다.

"근데 왜 이렇게까지 가벼운 CMS가 필요한가?"

이 질문에 답하려면 정적 사이트 생태계가 지난 몇 년간 어떻게 변했는지 잠깐 돌아볼 필요가 있다. Jamstack이 한창 주목받던 시절에는 "모든 걸 정적으로 빌드하고 CDN에 올리자"는 철학이 미덕이었다. 그런데 사이트 규모가 커지고 콘텐츠가 쌓이면서 빌드 시간이 10분, 20분으로 늘어나기 시작했고, CMS 관리자 패널조차 무거워져서 편집 경험이 나빠졌다. 거대한 자바스크립트 번들을 매번 로딩하고, 그래프큐엘 미들웨어가 콘텐츠를 인덱싱하는 동안 기다리고, 커스텀 위젯을 붙일 때마다 의존성 트리가 꼬였다.

Sveltia가 300KB라는 숫자로 보여주는 건 단순히 "더 적은 코드로 같은 일을 한다"는 기술적 우월함이 아니다. 정적 사이트의 무게 중심이 "빌드 속도"와 "편집자 경험"이라는 두 축으로 재편되고 있다는 신호다. 콘텐츠 편집자는 프레임워크가 뭔지 모르는 게 당연하고, 모바일에서 촬영한 사진을 바로 올리고 싶어 하는 게 당연하고, 저장 버튼을 눌렀을 때 1초 안에 완료되길 바라는 게 당연하다. 그 당연한 것들을 Git 기반 CMS가 이제야 제대로 해내기 시작했다는 점이 Sveltia를 주목해야 하는 진짜 이유다.

댓글

댓글을 읽어오는 중입니다.