Communitygithub.com

ovachiever/droid-tings

Sveltia CMS 설정 — Decap/Netlify CMS의 차세대 경량 Git 기반 CMS로, 번들 크기는 5배 작고(300KB), GraphQL 성능을 제공하며, 260개 이상의 선행 문제를 해결했습니다. Hugo, Jekyll, 11ty, Gatsby, Astro 등 프레임워크에 구애받지 않습니다. 사용 시점: 정적 사이트에 CMS 추가, Decap/Netlify CMS에서 마이그레이션, 비기술 편집자 지원, 또는 OAuth 인증 실패, YAML 파싱 오류, CORS/COOP 정책 문제, 콘텐츠 목록 표시 안됨 등의 문제 해결 시.

droid-tings란 무엇인가요?

이 스킬은 Sveltia CMS를 정적 사이트 프로젝트에 통합하는 방법을 안내합니다. Sveltia CMS는 Decap CMS(구 Netlify CMS)의 현대적인 후속 제품으로, Svelte 컴파일러로 빌드되어 500KB 미만의 초경량 번들(경쟁사의 1.5~2.6MB 대비)을 제공하며, GraphQL API를 통한 즉각적인 콘텐츠 페칭, 다크 모드, 드래그 앤 드롭 파일 업로드, 실시간 미리보기 등 향상된 UX를 제공합니다. GitHub, GitLab, Gitea, Forgejo 등 다양한 Git 백엔드를 지원하며, Hugo, Jekyll, 11ty, Gatsby, Astro, Next.js, SvelteKit 등 프레임워크에 구애받지 않습니다. 이 스킬은 프레임워크별 설정 패턴, Cloudflare Workers 또는 Vercel Serverless Functions를 통한 OAuth 인증 설정, 일반적인 문제 해결(인증 오류, YAML 파싱 오류, CORS/COOP 정책 문제, 콘텐츠 목록 표시 안 됨) 등을 다루며, 정적 사이트에 CMS를 추가하거나 Decap/Netlify CMS에서 마이그레이션할 때 유용합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ovachiever/droid-tings/tree/HEAD/skills/sveltia-cms

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Sveltia CMS 스킬

정적 사이트 프로젝트에 Sveltia CMS를 통합하는 완전한 스킬입니다.


Sveltia CMS란?

Sveltia CMS는 Git 기반의 경량 헤드리스 콘텐츠 관리 시스템으로, Decap CMS(구 Netlify CMS)의 현대적인 후속 제품으로 처음부터 새롭게 구축되었습니다. Git 저장소에 저장된 콘텐츠를 위한 빠르고 직관적인 편집 인터페이스를 제공합니다.

주요 기능

  1. 경량 및 고속

    • 번들 크기: <500 KB (minified/brotlied) vs 경쟁사 1.5-2.6 MB
    • Svelte 컴파일러로 구축 (가상 DOM 오버헤드 없음)
    • GraphQL API를 사용하여 즉각적인 콘텐츠 페칭
    • 모든 콘텐츠에 대한 관련성 기반 검색
  2. 현대적인 사용자 경험

    • 전체 뷰포트를 활용하는 직관적인 관리 인터페이스
    • 다크 모드 지원 (시스템 환경설정 따름)
    • 모바일 및 태블릿 최적화
    • 다중 파일 지원 드래그 앤 드롭 업로드
    • 즉시 업데이트되는 실시간 미리보기
  3. Git-네이티브 아키텍처

    • Markdown, MDX, YAML, TOML 또는 JSON으로 콘텐츠 저장
    • 전체 버전 관리 및 변경 기록
    • 공급업체 종속 없음 - 콘텐츠는 코드와 함께 유지
    • GitHub, GitLab, Gitea, Forgejo 백엔드 지원
  4. 프레임워크에 구애받지 않음

    • 바닐라 JavaScript 번들로 제공
    • Hugo, Jekyll, 11ty, Gatsby, Astro, Next.js, SvelteKit에서 작동
    • React, Vue 또는 프레임워크 런타임 종속성 없음
    • 모든 정적 사이트 생성기와 호환
  5. 일급 국제화 지원

    • 다중 언어 지원 내장
    • 원클릭 DeepL 번역 통합
    • 편집 중 로케일 전환
    • 유연한 i18n 구조 (파일, 폴더, 단일 파일)
  6. 내장 이미지 최적화

    • 자동 WebP 변환
    • 클라이언트 측 리사이징 및 최적화
    • SVG 최적화 지원
    • 품질 및 크기 구성 가능

현재 버전

  • @sveltia/cms: 0.113.5 (2025년 10월)
  • 상태: 공개 베타 (v1.0 2026년 초 예상)
  • 성숙도: 프로덕션 준비 완료 (전작에서 265개 이상의 문제 해결)

이 스킬을 사용해야 하는 경우

✅ Sveltia CMS를 사용해야 하는 경우:

  1. 정적 사이트 구축

    • Hugo 블로그 및 문서
    • Jekyll 사이트 및 GitHub Pages
    • 11ty (Eleventy) 프로젝트
    • Gatsby 마케팅 사이트
    • Astro 콘텐츠 중심 사이트
  2. 비기술 편집자가 접근해야 하는 경우

    • 페이지를 관리하는 마케팅 팀
    • 블로그 포스트를 작성하는 작가
    • Git 지식이 없는 콘텐츠 팀
    • 쉬운 콘텐츠 업데이트가 필요한 클라이언트
  3. Git 기반 워크플로가 필요한 경우

    • Git을 통한 콘텐츠 버전 관리
    • 풀 리퀘스트를 통한 콘텐츠 검토
    • 저장소에 코드와 함께 콘텐츠 저장
    • 배포를 위한 CI/CD 통합
  4. 경량 솔루션이 필요한 경우

    • 성능에 민감한 프로젝트
    • 모바일 우선 편집 필요
    • 빠른 로드 시간이 중요한 경우
    • 최소 번들 크기가 중요한 경우
  5. Decap/Netlify CMS에서 마이그레이션하는 경우

    • 기존 config.yml 재사용 가능
    • 드롭인 교체 (1줄 변경)
    • 더 나은 성능과 UX
    • 활발한 유지보수 및 버그 수정

❌ Sveltia CMS를 사용하지 말아야 하는 경우:

  1. 실시간 협업이 필요한 경우

    • 여러 사용자가 동시에 편집 (Google Docs 스타일)
    • Sanity, Contentful 또는 TinaCMS 사용
  2. 시각적 페이지 빌드가 필요한 경우

    • 드래그 앤 드롭 페이지 빌더 필요
    • Webflow, Builder.io 또는 TinaCMS (React) 사용
  3. 매우 동적인 데이터가 필요한 경우

    • 실시간 재고가 있는 전자상거래
    • 실시간 대시보드 또는 분석
    • 기존 데이터베이스 (D1, PostgreSQL) 사용
  4. 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에 가장 많이 사용되는 정적 사이트 생성기입니다.

단계:

  1. admin 디렉토리 생성:

    mkdir -p static/admin
    
  2. 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>
    
  3. 설정 파일 생성:

    # 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' }
    
  4. Hugo 개발 서버 시작:

    hugo server
    
  5. admin 접속:

    http://localhost:1313/admin/
    

템플릿: templates/hugo/ 참조


2. Jekyll 설정

Jekyll은 GitHub Pages 및 Sveltia CMS와 함께 자주 사용됩니다.

단계:

  1. admin 디렉토리 생성:

    mkdir -p admin
    
  2. 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>
    
  3. 설정 파일 생성:

    # 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' }
    
  4. Jekyll 개발 서버 시작:

    bundle exec jekyll serve
    
  5. admin 접속:

    http://localhost:4000/admin/
    

템플릿: templates/jekyll/ 참조


3. 11ty (Eleventy) 설정

11ty는 유연한 정적 사이트를 위해 Sveltia CMS와 잘 작동합니다.

단계:

  1. admin 디렉토리 생성:

    mkdir -p admin
    
  2. 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>
    
  3. 설정 파일 생성:

    # 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' }
    
  4. .eleventy.js에 패스스루 복사 추가:

    module.exports = function(eleventyConfig) {
      eleventyConfig.addPassthroughCopy('admin');
      // ... 나머지 설정
    };
    
  5. 11ty 개발 서버 시작:

    npx @11ty/eleventy --serve
    
  6. admin 접속:

    http://localhost:8080/admin/
    

템플릿: templates/11ty/ 참조


4. Astro 설정

Astro는 Sveltia CMS와 잘 작동하는 현대적인 프레임워크입니다.

단계:

  1. admin 디렉토리 생성:

    mkdir -p public/admin
    
  2. 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>
    
  3. 설정 파일 생성:

    # 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' }
    
  4. Astro 개발 서버 시작:

    npm run dev
    
  5. admin 접속:

    http://localhost:4321/admin/
    

템플릿: templates/astro/ 참조


5. 프레임워크 무관 설정

적용 대상: Gatsby, Next.js (SSG 모드), SvelteKit, Remix 또는 모든 프레임워크

단계:

  1. public 디렉토리 확인:

    • Gatsby: static/
    • Next.js: public/
    • SvelteKit: static/
    • Remix: public/
  2. public 폴더에 admin 디렉토리 생성:

    mkdir -p <public-folder>/admin
    
  3. 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>
    
  4. 콘텐츠 구조에 맞게 설정 파일 생성:

    backend:
      name: github
      repo: owner/repo
      branch: main
    
    media_folder: <미디어-경로>
    public_folder: <공개-경로>
    
    collections:
      # 콘텐츠 구조에 따라 정의
    
  5. admin 접속:

    http://localhost:<port>/admin/
    

인증 설정

배포 플랫폼에 맞는 인증 방법을 선택하세요.

옵션 1: Cloudflare Workers OAuth (권장) 🔥

적합 대상: Cloudflare Pages, Cloudflare Workers, 모든 배포

공식 sveltia-cms-auth Cloudflare Worker를 OAuth에 사용합니다.

단계:

  1. Worker 배포:

    # 인증 Worker 클론
    git clone https://github.com/sveltia/sveltia-cms-auth
    cd sveltia-cms-auth
    
    # 의존성 설치
    npm install
    
    # Cloudflare Workers에 배포
    npx wrangler deploy
    

    또는 원클릭 배포 사용:

  2. GitHub에서 OAuth 앱 등록:

  3. 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
    
  4. CMS 설정 업데이트:

    # admin/config.yml
    backend:
      name: github
      repo: owner/repo
      branch: main
      base_url: https://your-worker.workers.dev  # ← 이 줄 추가
    
  5. 인증 테스트:

    • 사이트의 /admin/ 열기
    • "Login with GitHub" 클릭
    • 앱 승인
    • CMS로 리디렉션되어야 함

전체 가이드: references/cloudflare-auth-setup.md 참조

템플릿: templates/cloudflare-workers/ 참조


옵션 2: Vercel Serverless Functions

적합 대상: Vercel 배포

단계:

  1. API 라우트 생성:

    // api/auth.ts
    export default async function handler(req, res) {
      // OAuth 처리 로직
      // templates/vercel-serverless/api-auth.ts 참조
    }
    
  2. Vercel에서 환경 변수 설정:

    GITHUB_CLIENT_ID=your_client_id
    GITHUB_CLIENT_SECRET=your_client_secret
    
  3. CMS 설정 업데이트:

    backend:
      name: github
      repo: owner/repo
      branch: main
      base_url: https://yourdomain.com/api/auth
    
  ... (번역을 위해 잘림)
}

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

관련 스킬