sveltia-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
2. Bundle size: <500 KB (minified/brotlied) vs 1.5-2.6 MB for competitors
3. Built with Svelte compiler (no virtual DOM overhead)
4. Uses GraphQL APIs for instant content fetching
5. Relevance-based search across all content

1. Modern User Experience
2. Intuitive admin interface with full viewport utilization
3. Dark mode support (follows system preferences)
4. Mobile and tablet optimized
5. Drag-and-drop file uploads with multiple file support
6. Real-time preview with instant updates

1. Git-Native Architecture
2. Content stored as Markdown, MDX, YAML, TOML, or JSON
3. Full version control and change history
4. No vendor lock-in - content lives with code
5. Supports GitHub, GitLab, Gitea, Forgejo backends

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

1. First-Class Internationalization
2. Multiple language support built-in
3. One-click DeepL translation integration
4. Locale switching while editing
5. Flexible i18n structures (files, folders, single file)

1. Built-In Image Optimization
2. Automatic WebP conversion
3. Client-side resizing and optimization
4. SVG optimization support
5. 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
2. Hugo blogs and documentation
3. Jekyll sites and GitHub Pages
4. 11ty (Eleventy) projects
5. Gatsby marketing sites
6. Astro content-heavy sites

1. Non-Technical Editors Need Access
2. Marketing teams managing pages
3. Authors writing blog posts
4. Content teams without Git knowledge
5. Clients needing easy content updates

1. Git-Based Workflow Desired
2. Content versioning through Git
3. Content review through pull requests
4. Content lives with code in repository
5. CI/CD integration for deployments

1. Lightweight Solution Required
2. Performance-sensitive projects
3. Mobile-first editing needed
4. Quick load times critical
5. Minimal bundle size important

1. Migrating from Decap/Netlify CMS
2. Existing config.yml can be reused
3. Drop-in replacement (change 1 line)
4. Better performance and UX
5. Active maintenance and bug fixes

❌ Don't Use Sveltia CMS When:

1. Real-Time Collaboration Needed
2. Multiple users editing simultaneously (Google Docs-style)
3. Use Sanity, Contentful, or TinaCMS instead

1. Visual Page Building Required
2. Drag-and-drop page builders needed
3. Use Webflow, Builder.io, or TinaCMS (React) instead

1. Highly Dynamic Data
2. E-commerce with real-time inventory
3. Real-time dashboards or analytics
4. Use traditional databases (D1, PostgreSQL) instead

1. React-Specific Visual Editing Needed
2. In-context component editing
3. 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

| 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"></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 afte