sveltia-cms（斯维尔蒂亚 CMS）

Sveltia CMS Skill

Complete skill for integrating Sveltia CMS into static site projects.

What is Sveltia CMS?

Sveltia CMS is a Git-based lightweight headless content management system built from scratch as the modern successor to Decap CMS (formerly Netlify CMS). It provides a fast, intuitive editing interface for content stored in Git repositories.

Key Features

1. Lightweight & Fast

- Bundle size: <500 KB (minified/brotlied) vs 1.5-2.6 MB for competitors - Built with Svelte compiler (no virtual DOM overhead) - Uses GraphQL APIs for instant content fetching - Relevance-based search across all content

1. Modern User Experience

- Intuitive admin interface with full viewport utilization - Dark mode support (follows system preferences) - Mobile and tablet optimized - Drag-and-drop file uploads with multiple file support - Real-time preview with instant updates

1. Git-Native Architecture

- Content stored as Markdown, MDX, YAML, TOML, or JSON - Full version control and change history - No vendor lock-in - content lives with code - Supports GitHub, GitLab, Gitea, Forgejo backends

1. Framework-Agnostic

- Served as vanilla JavaScript bundle - Works with Hugo, Jekyll, 11ty, Gatsby, Astro, Next.js, SvelteKit - No React, Vue, or framework runtime dependencies - Compatible with any static site generator

1. First-Class Internationalization

- Multiple language support built-in - One-click DeepL translation integration - Locale switching while editing - Flexible i18n structures (files, folders, single file)

1. Built-In Image Optimization

- Automatic WebP conversion - Client-side resizing and optimization - SVG optimization support - Configurable quality and dimensions

Current Versions

• @sveltia/cms: 0.113.5 (October 2025)
• Status: Public Beta (v1.0 expected early 2026)
• Maturity: Production-ready (265+ issues solved from predecessor)

When to Use This Skill

✅ Use Sveltia CMS When:

1. Building Static Sites

- Hugo blogs and documentation - Jekyll sites and GitHub Pages - 11ty (Eleventy) projects - Gatsby marketing sites - Astro content-heavy sites

1. Non-Technical Editors Need Access

- Marketing teams managing pages - Authors writing blog posts - Content teams without Git knowledge - Clients needing easy content updates

1. Git-Based Workflow Desired

- Content versioning through Git - Content review through pull requests - Content lives with code in repository - CI/CD integration for deployments

1. Lightweight Solution Required

- Performance-sensitive projects - Mobile-first editing needed - Quick load times critical - Minimal bundle size important

1. Migrating from Decap/Netlify CMS

- Existing config.yml can be reused - Drop-in replacement (change 1 line) - Better performance and UX - Active maintenance and bug fixes

❌ Don't Use Sveltia CMS When:

1. Real-Time Collaboration Needed

- Multiple users editing simultaneously (Google Docs-style) - Use Sanity, Contentful, or TinaCMS instead

1. Visual Page Building Required

- Drag-and-drop page builders needed - Use Webflow, Builder.io, or TinaCMS (React) instead

1. Highly Dynamic Data

- E-commerce with real-time inventory - Real-time dashboards or analytics - Use traditional databases (D1, PostgreSQL) instead

1. React-Specific Visual Editing Needed

- In-context component editing - Use TinaCMS instead (React-focused)

Sveltia CMS vs TinaCMS

Use Sveltia for:

• Hugo, Jekyll, 11ty, Gatsby (non-React SSGs)
• Traditional CMS admin panel UX
• Lightweight bundle requirements
• Framework-agnostic projects

Use TinaCMS for:

• React, Next.js, Astro (React components)
• Visual in-context editing
• Schema-driven type-safe content
• Modern developer experience with TypeScript

Both are valid - Sveltia complements TinaCMS for different use cases.

Quick Start

Load references/framework-setup.md for complete framework-specific setup (Hugo, Jekyll, 11ty, Astro, Next.js, Gatsby, SvelteKit).

Basic Setup Steps (Framework-Agnostic)

1. Create admin directory in your public folder (e.g., static/admin, public/admin)
2. Create admin/index.html with Sveltia CMS script tag
3. Create admin/config.yml with backend and collections
4. Set up authentication → See references/authentication-guide.md
5. Test locally by visiting /admin/

Templates available in templates/ directory for each framework.

Authentication Setup

Load references/authentication-guide.md for complete OAuth setup instructions.

Quick Overview

Recommended: Cloudflare Workers OAuth (official, fast, free)

Templates: See templates/cloudflare-workers/ and templates/vercel-serverless/

Configuration

Load references/configuration-guide.md for complete config.yml documentation, collection patterns, and i18n setup.

Essential Config Structure

backend:
  name: github
  repo: owner/repo
  branch: main
  base_url: https://your-worker.workers.dev

media_folder: static/images
public_folder: /images

collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    create: true
    fields:
      - { label: Title, name: title, widget: string }
      - { label: Body, name: body, widget: markdown }

Collection templates available in templates/collections/ for blogs, docs, and landing pages.

i18n support: Multiple files, folders, or single file structures - see reference guide.

Common Errors & Solutions

This skill prevents 8 common errors. Top 3 shown below - load references/error-catalog.md for all 8 with complete solutions.

1. ❌ OAuth Authentication Failures

Error: "Error: Failed to authenticate" / redirects to wrong domain

Quick Fix:

• Verify base_url in config.yml points to your OAuth proxy
• Check GitHub OAuth callback URL matches Worker URL
• Test Worker: curl https://your-worker.workers.dev/health

→ Load references/error-catalog.md Error #1 for complete solution

2. ❌ Content Not Listing in CMS

Error: "No entries found" / empty content list

Quick Fix:

• Verify folder path matches actual file location
• Match format to actual file format (yaml vs toml)
• Check file extensions match config

→ Load references/error-catalog.md Error #4 for complete solution

3. ❌ CORS / COOP Policy Errors

Error: "Authentication Aborted" / OAuth popup closes

Quick Fix:

• Set Cross-Origin-Opener-Policy: same-origin-allow-popups in headers
• Add OAuth proxy to CSP connect-src

→ Load references/error-catalog.md Error #8 for complete solution

All 8 errors with detailed solutions: See references/error-catalog.md

Migration from Decap CMS

Sveltia is a drop-in replacement - just change the script tag!

<!-- OLD: Decap CMS -->
<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>

<!-- NEW: Sveltia CMS -->
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>

Your existing config.yml works as-is. Load references/migration-from-decap.md for complete migration guide and testing checklist.

Deployment

Load references/deployment-guide.md for platform-specific deployment instructions (Cloudflare Pages, Vercel, Netlify, GitHub Pages).

Quick Deployment Checklist

• Admin directory in correct public folder
• OAuth proxy deployed and configured
• base_url set in config.yml
• Build command configured
• Test /admin/ route after deployment

When to Load References

Load references/framework-setup.md when:

• User needs framework-specific setup (Hugo, Jekyll, 11ty, Astro, etc.)
• Setting up new Sveltia CMS installation
• Troubleshooting framework-specific admin directory issues

Load references/authentication-guide.md when:

• Setting up GitHub OAuth authentication
• Deploying Cloudflare Workers OAuth proxy
• Troubleshooting authentication errors
• User asks about base_url configuration

Load references/configuration-guide.md when:

• User needs complete config.yml examples
• Setting up collections, fields, or widgets
• Configuring media uploads, i18n, or workflows
• User asks about specific configuration options

Load references/error-catalog.md when:

• User encounters any errors during setup
• Troubleshooting authentication, parsing, or deployment issues
• User reports errors beyond the top 3 shown above

Load references/deployment-guide.md when:

• Deploying to Cloudflare Pages, Netlify, or Vercel
• Setting up OAuth proxy deployment
• Troubleshooting production deployment issues

Load references/migration-from-decap.md when:

• Migrating from Decap CMS / Netlify CMS
• User asks about compatibility or migration steps

Resources

Templates: templates/hugo/, templates/jekyll/, templates/cloudflare-workers/ Official Docs: https://github.com/sveltia/sveltia-cms OAuth Worker: https://github.com/sveltia/sveltia-cms-auth

Package Information

Current Version: @sveltia/cms@0.113.5 (October 2025) Status: Production-ready, v1.0 expected early 2026

Last Updated: 2025-10-24