Sveltia CMS 스킬
정적 사이트 프로젝트에 Sveltia CMS를 통합하는 완전한 스킬입니다.
Sveltia CMS란?
Sveltia CMS는 Git 기반의 경량 헤드리스 콘텐츠 관리 시스템으로, Decap CMS(구 Netlify CMS)의 현대적인 후속 제품으로 처음부터 새롭게 구축되었습니다. Git 저장소에 저장된 콘텐츠를 위한 빠르고 직관적인 편집 인터페이스를 제공합니다.
주요 기능
-
경량 및 고속
- 번들 크기: <500 KB (minified/brotlied) vs 경쟁사 1.5-2.6 MB
- Svelte 컴파일러로 구축 (가상 DOM 오버헤드 없음)
- GraphQL API를 사용하여 즉각적인 콘텐츠 페칭
- 모든 콘텐츠에 대한 관련성 기반 검색
-
현대적인 사용자 경험
- 전체 뷰포트를 활용하는 직관적인 관리 인터페이스
- 다크 모드 지원 (시스템 환경설정 따름)
- 모바일 및 태블릿 최적화
- 다중 파일 지원 드래그 앤 드롭 업로드
- 즉시 업데이트되는 실시간 미리보기
-
Git-네이티브 아키텍처
- Markdown, MDX, YAML, TOML 또는 JSON으로 콘텐츠 저장
- 전체 버전 관리 및 변경 기록
- 공급업체 종속 없음 - 콘텐츠는 코드와 함께 유지
- GitHub, GitLab, Gitea, Forgejo 백엔드 지원
-
프레임워크에 구애받지 않음
- 바닐라 JavaScript 번들로 제공
- Hugo, Jekyll, 11ty, Gatsby, Astro, Next.js, SvelteKit에서 작동
- React, Vue 또는 프레임워크 런타임 종속성 없음
- 모든 정적 사이트 생성기와 호환
-
일급 국제화 지원
- 다중 언어 지원 내장
- 원클릭 DeepL 번역 통합
- 편집 중 로케일 전환
- 유연한 i18n 구조 (파일, 폴더, 단일 파일)
-
내장 이미지 최적화
- 자동 WebP 변환
- 클라이언트 측 리사이징 및 최적화
- SVG 최적화 지원
- 품질 및 크기 구성 가능
현재 버전
- @sveltia/cms: 0.113.5 (2025년 10월)
- 상태: 공개 베타 (v1.0 2026년 초 예상)
- 성숙도: 프로덕션 준비 완료 (전작에서 265개 이상의 문제 해결)
이 스킬을 사용해야 하는 경우
✅ Sveltia CMS를 사용해야 하는 경우:
-
정적 사이트 구축
- Hugo 블로그 및 문서
- Jekyll 사이트 및 GitHub Pages
- 11ty (Eleventy) 프로젝트
- Gatsby 마케팅 사이트
- Astro 콘텐츠 중심 사이트
-
비기술 편집자가 접근해야 하는 경우
- 페이지를 관리하는 마케팅 팀
- 블로그 포스트를 작성하는 작가
- Git 지식이 없는 콘텐츠 팀
- 쉬운 콘텐츠 업데이트가 필요한 클라이언트
-
Git 기반 워크플로가 필요한 경우
- Git을 통한 콘텐츠 버전 관리
- 풀 리퀘스트를 통한 콘텐츠 검토
- 저장소에 코드와 함께 콘텐츠 저장
- 배포를 위한 CI/CD 통합
-
경량 솔루션이 필요한 경우
- 성능에 민감한 프로젝트
- 모바일 우선 편집 필요
- 빠른 로드 시간이 중요한 경우
- 최소 번들 크기가 중요한 경우
-
Decap/Netlify CMS에서 마이그레이션하는 경우
- 기존 config.yml 재사용 가능
- 드롭인 교체 (1줄 변경)
- 더 나은 성능과 UX
- 활발한 유지보수 및 버그 수정
❌ Sveltia CMS를 사용하지 말아야 하는 경우:
-
실시간 협업이 필요한 경우
- 여러 사용자가 동시에 편집 (Google Docs 스타일)
- Sanity, Contentful 또는 TinaCMS 사용
-
시각적 페이지 빌드가 필요한 경우
- 드래그 앤 드롭 페이지 빌더 필요
- Webflow, Builder.io 또는 TinaCMS (React) 사용
-
매우 동적인 데이터가 필요한 경우
- 실시간 재고가 있는 전자상거래
- 실시간 대시보드 또는 분석
- 기존 데이터베이스 (D1, PostgreSQL) 사용
-
React 특화 시각적 편집이 필요한 경우
- 인컨텍스트 컴포넌트 편집
- TinaCMS 사용 (React 중심)
Sveltia CMS vs TinaCMS
Sveltia 사용 추천:
- Hugo, Jekyll, 11ty, Gatsby (비React SSG)
- 기존 CMS 관리 패널 UX
- 경량 번들 요구 사항
- 프레임워크 중립 프로젝트
TinaCMS 사용 추천:
- React, Next.js, Astro (React 컴포넌트)
- 시각적 인컨텍스트 편집
- 스키마 기반 타입세이프 콘텐츠
- TypeScript를 사용한 현대적인 개발자 경험
둘 다 유효 - Sveltia는 다른 사용 사례에 대해 TinaCMS를 보완합니다.
프레임워크별 설정 패턴
프레임워크 선택에 따라 적절한 설정 패턴을 사용하세요.
1. Hugo 설정 (가장 일반적)
Hugo는 Sveltia CMS에 가장 많이 사용되는 정적 사이트 생성기입니다.
단계:
-
admin 디렉토리 생성:
mkdir -p static/admin -
admin 인덱스 페이지 생성:
<!-- static/admin/index.html --> <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>콘텐츠 관리자</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
설정 파일 생성:
# static/admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: static/images/uploads public_folder: /images/uploads collections: - name: posts label: 블로그 포스트 folder: content/posts create: true slug: '{{year}}-{{month}}-{{day}}-{{slug}}' fields: - { label: '제목', name: 'title', widget: 'string' } - { label: '날짜', name: 'date', widget: 'datetime' } - { label: '초안', name: 'draft', widget: 'boolean', default: true } - { label: '태그', name: 'tags', widget: 'list', required: false } - { label: '본문', name: 'body', widget: 'markdown' } -
Hugo 개발 서버 시작:
hugo server -
admin 접속:
http://localhost:1313/admin/
템플릿: templates/hugo/ 참조
2. Jekyll 설정
Jekyll은 GitHub Pages 및 Sveltia CMS와 함께 자주 사용됩니다.
단계:
-
admin 디렉토리 생성:
mkdir -p admin -
admin 인덱스 페이지 생성:
<!-- admin/index.html --> <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>콘텐츠 관리자</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
설정 파일 생성:
# admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: assets/images/uploads public_folder: /assets/images/uploads collections: - name: posts label: 블로그 포스트 folder: _posts create: true slug: '{{year}}-{{month}}-{{day}}-{{slug}}' fields: - { label: '레이아웃', name: 'layout', widget: 'hidden', default: 'post' } - { label: '제목', name: 'title', widget: 'string' } - { label: '날짜', name: 'date', widget: 'datetime' } - { label: '카테고리', name: 'categories', widget: 'list', required: false } - { label: '본문', name: 'body', widget: 'markdown' } -
Jekyll 개발 서버 시작:
bundle exec jekyll serve -
admin 접속:
http://localhost:4000/admin/
템플릿: templates/jekyll/ 참조
3. 11ty (Eleventy) 설정
11ty는 유연한 정적 사이트를 위해 Sveltia CMS와 잘 작동합니다.
단계:
-
admin 디렉토리 생성:
mkdir -p admin -
admin 인덱스 페이지 생성:
<!-- admin/index.html --> <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>콘텐츠 관리자</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
설정 파일 생성:
# admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: src/assets/images public_folder: /assets/images collections: - name: blog label: 블로그 포스트 folder: src/posts create: true slug: '{{slug}}' fields: - { label: '제목', name: 'title', widget: 'string' } - { label: '설명', name: 'description', widget: 'text' } - { label: '날짜', name: 'date', widget: 'datetime' } - { label: '태그', name: 'tags', widget: 'list', required: false } - { label: '본문', name: 'body', widget: 'markdown' } -
.eleventy.js에 패스스루 복사 추가:module.exports = function(eleventyConfig) { eleventyConfig.addPassthroughCopy('admin'); // ... 나머지 설정 }; -
11ty 개발 서버 시작:
npx @11ty/eleventy --serve -
admin 접속:
http://localhost:8080/admin/
템플릿: templates/11ty/ 참조
4. Astro 설정
Astro는 Sveltia CMS와 잘 작동하는 현대적인 프레임워크입니다.
단계:
-
admin 디렉토리 생성:
mkdir -p public/admin -
admin 인덱스 페이지 생성:
<!-- public/admin/index.html --> <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>콘텐츠 관리자</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
설정 파일 생성:
# public/admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: public/images public_folder: /images collections: - name: blog label: 블로그 포스트 folder: src/content/blog create: true slug: '{{slug}}' format: mdx fields: - { label: '제목', name: 'title', widget: 'string' } - { label: '설명', name: 'description', widget: 'text' } - { label: '발행일', name: 'pubDate', widget: 'datetime' } - { label: '히어로 이미지', name: 'heroImage', widget: 'image', required: false } - { label: '본문', name: 'body', widget: 'markdown' } -
Astro 개발 서버 시작:
npm run dev -
admin 접속:
http://localhost:4321/admin/
템플릿: templates/astro/ 참조
5. 프레임워크 무관 설정
적용 대상: Gatsby, Next.js (SSG 모드), SvelteKit, Remix 또는 모든 프레임워크
단계:
-
public 디렉토리 확인:
- Gatsby:
static/ - Next.js:
public/ - SvelteKit:
static/ - Remix:
public/
- Gatsby:
-
public 폴더에 admin 디렉토리 생성:
mkdir -p <public-folder>/admin -
admin 인덱스 페이지 생성:
<!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>콘텐츠 관리자</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
콘텐츠 구조에 맞게 설정 파일 생성:
backend: name: github repo: owner/repo branch: main media_folder: <미디어-경로> public_folder: <공개-경로> collections: # 콘텐츠 구조에 따라 정의 -
admin 접속:
http://localhost:<port>/admin/
인증 설정
배포 플랫폼에 맞는 인증 방법을 선택하세요.
옵션 1: Cloudflare Workers OAuth (권장) 🔥
적합 대상: Cloudflare Pages, Cloudflare Workers, 모든 배포
공식 sveltia-cms-auth Cloudflare Worker를 OAuth에 사용합니다.
단계:
-
Worker 배포:
# 인증 Worker 클론 git clone https://github.com/sveltia/sveltia-cms-auth cd sveltia-cms-auth # 의존성 설치 npm install # Cloudflare Workers에 배포 npx wrangler deploy또는 원클릭 배포 사용:
- https://github.com/sveltia/sveltia-cms-auth 방문
- "Deploy to Cloudflare Workers" 버튼 클릭
-
GitHub에서 OAuth 앱 등록:
- https://github.com/settings/developers 로 이동
- "New OAuth App" 클릭
- Application name: 사이트 이름 CMS
- Homepage URL: https://yourdomain.com
- Authorization callback URL: https://your-worker.workers.dev/callback
- Client ID와 Client Secret 저장
-
Worker 환경 변수 구성:
# GitHub 자격 증명 설정 npx wrangler secret put GITHUB_CLIENT_ID # Client ID 붙여넣기 npx wrangler secret put GITHUB_CLIENT_SECRET # Client Secret 붙여넣기 # 선택 사항: 특정 도메인으로 제한 npx wrangler secret put ALLOWED_DOMAINS # 예시: yourdomain.com,*.yourdomain.com -
CMS 설정 업데이트:
# admin/config.yml backend: name: github repo: owner/repo branch: main base_url: https://your-worker.workers.dev # ← 이 줄 추가 -
인증 테스트:
- 사이트의
/admin/열기 - "Login with GitHub" 클릭
- 앱 승인
- CMS로 리디렉션되어야 함
- 사이트의
전체 가이드: references/cloudflare-auth-setup.md 참조
템플릿: templates/cloudflare-workers/ 참조
옵션 2: Vercel Serverless Functions
적합 대상: Vercel 배포
단계:
-
API 라우트 생성:
// api/auth.ts export default async function handler(req, res) { // OAuth 처리 로직 // templates/vercel-serverless/api-auth.ts 참조 } -
Vercel에서 환경 변수 설정:
GITHUB_CLIENT_ID=your_client_id GITHUB_CLIENT_SECRET=your_client_secret -
CMS 설정 업데이트:
backend: name: github repo: owner/repo branch: main base_url: https://yourdomain.com/api/auth
... (번역을 위해 잘림)
}