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

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

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

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

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

First-Class Internationalization

• Multiple language support built-in

• One-click DeepL translation integration

• Locale switching while editing

• Flexible i18n structures (files, folders, single file)

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:

Building Static Sites

• Hugo blogs and documentation

• Jekyll sites and GitHub Pages

• 11ty (Eleventy) projects

• Gatsby marketing sites

• Astro content-heavy sites

Non-Technical Editors Need Access

• Marketing teams managing pages

• Authors writing blog posts

• Content teams without Git knowledge

• Clients needing easy content updates

Git-Based Workflow Desired

• Content versioning through Git

• Content review through pull requests

• Content lives with code in repository

• CI/CD integration for deployments

Lightweight Solution Required

• Performance-sensitive projects

• Mobile-first editing needed

• Quick load times critical

• Minimal bundle size important

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:

Real-Time Collaboration Needed

• Multiple users editing simultaneously (Google Docs-style)

• Use Sanity, Contentful, or TinaCMS instead

Visual Page Building Required

• Drag-and-drop page builders needed

• Use Webflow, Builder.io, or TinaCMS (React) instead

Highly Dynamic Data

• E-commerce with real-time inventory

• Real-time dashboards or analytics

• Use traditional databases (D1, PostgreSQL) instead

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)

• Create admin directory in your public folder (e.g., static/admin , public/admin )

• Create admin/index.html with Sveltia CMS script tag

• Create admin/config.yml with backend and collections

• Set up authentication → See references/authentication-guide.md

• 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

Method Best For Complexity

Cloudflare Workers All deployments Easy ⭐

Vercel Serverless Vercel projects Medium

Local Development Dev only Easy

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">&#x3C;/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