Architecture
Sveltia CMS inherits a unique architecture from Netlify CMS (now Decap CMS) that sets it apart from traditional content management systems and even other headless CMSs. Netlify itself touted it as “a different kind of CMS”, and Sveltia CMS follows that philosophy closely while introducing its own innovations.
This document explores the architecture of headless CMSs in general, highlighting key distinctions among them, and then delves into the specific architecture of Sveltia CMS to illustrate how it works and what makes it special.
What Is a Headless CMS?
As a quick refresher, a headless CMS is a content management system without a built-in presentation layer. It provides pure content management decoupled from how that content is displayed, enabling separation of concerns between content and presentation. This architecture offers several key benefits:
- Flexibility: Use any frontend framework, static site generator, or platform to consume and display your content
- Scalability: Scale your content distribution independently from your presentation layer
- Performance: Deliver content through fast, distributed networks without the overhead of traditional CMS presentation layers
- Security: Reduce the attack surface by keeping your content API separate from your public-facing application
- Future-proof: Change your frontend technology without affecting your content infrastructure
Types of Headless CMSs
The headless CMS directory on Jamstack.org showcases a wide variety of headless CMSs, each with its own architecture and features. Here are some common architectural distinctions among them:
API-Driven vs. Git-Based
Most headless CMSs are API-driven, providing REST or GraphQL APIs to fetch and manage content with a backend server for storage. Git-based CMSs use a Git repository as the primary data store, enabling version control, collaboration, and easy change tracking. While API-driven CMSs are scalable for large applications, they require more complex infrastructure.
Git-based CMSs like Sveltia CMS are simpler to set up and maintain, avoid vendor lock-in, and are better suited to smaller projects or teams.
Framework-Agnostic vs. Framework-Specific vs. Built-in SSG
Headless CMSs vary in framework support. Some integrate with specific frameworks for optimized workflows and features, while most are framework-agnostic and work with any generator or framework. A few provide built-in static site generators for direct deployment.
Sveltia CMS is framework-agnostic, supporting Astro, Eleventy, Hugo, Jekyll, SvelteKit, and more.
Cloud vs. Self-Hosted
CMSs are offered as SaaS solutions with provider-managed hosting and subscription pricing, or as self-hosted options for greater control but requiring more expertise.
Sveltia CMS is semi-self-hosted: the CMS is served from a CDN (no maintenance needed), but each project has its own instance with content stored in your Git repository for full control.
Web vs. Desktop
Most headless CMSs are web applications accessible from any device with an internet connection. Some desktop alternatives offer offline capabilities but require installation and updates.
Sveltia CMS is the best of both worlds: a web app that runs in the browser while supporting local file access via a modern web API.
How Sveltia CMS Works
Now let’s take a closer look at how Sveltia CMS is architected and what makes it unique among headless CMSs.
CDN-Served JavaScript
In the start guide, we showed you how to set up Sveltia CMS with just two files:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="robots" content="noindex" />
<title>Sveltia CMS</title>
</head>
<body>
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
</body>
</html># yaml-language-server: $schema=https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json
backend:
name: github
repo: user/repo
media_folder: /static/media
public_folder: /media
collections:
- name: posts
label: Posts
folder: /content/posts
fields:
- { label: Title, name: title, widget: string }
- { label: Body, name: body, widget: markdown }Sveltia CMS is distributed as an npm package but is easiest to use via UNPKG, a content delivery network (CDN) that serves npm packages. The HTML file is simply a container that loads the Sveltia CMS JavaScript file from there.
Since the CDN always serves the latest version, you never need to manually update the CMS. Just include the script tag and you’re ready to go. The entire CMS — all features and UI — runs within that single JavaScript file. No build step is required.
Single-Page Application
When you open the HTML file in your browser, Sveltia CMS initializes completely client-side as a single-page application (SPA) using hash routing for navigation. All content processing and user interface rendering happen in your browser without needing a backend server (authentication with GitHub is the only exception).
YAML Configuration
On startup, Sveltia CMS automatically reads config.yml from the same directory as your HTML file — no path specification needed. This configuration file defines your backend, media folders, and content collections.
Git Backend
Once you authenticate with your Git service provider, you can access and manage content through a user-friendly interface. End-users never need to interact with Git directly; all operations are handled through the provider’s API behind the scenes.
All Files in One Place
The index.html and config.yml files live alongside your other project files in your repository, allowing your code, content, assets, CMS instance, and configuration to coexist seamlessly. This simplifies deployment and maintenance, and eliminates the need for a database.
SSG-Friendly
Sveltia CMS focuses solely on content management without building your site, making it compatible with any framework. It’s particularly well-suited for static site generators (SSGs), which pair naturally with Git-based workflows.
Local File Access
Sveltia CMS allows developers to work with local files directly from the browser, making it easy to update your configuration, content, and media assets without pushing changes to a remote repository first. This also enables offline editing capabilities.
JavaScript API
Advanced users can leverage the JavaScript API to customize and extend Sveltia CMS functionality, such as manual initialization, registering custom preview styles, and adding editor components.
Differences from Netlify/Decap CMS
While Sveltia CMS is heavily inspired by Netlify CMS, we’re committed to building a modern platform with unique features. Key differences include:
- Built with Svelte: Smaller bundle sizes, faster performance, fewer crashes, and simpler reactivity compared to React, thanks to efficient compile-time optimizations.
- Lean codebase: Provides only the core CMS with no extra packages, reducing complexity and maintenance overhead while enabling frequent releases.
- Modular dependencies: Dynamically loads additional dependencies from UNPKG rather than bundling everything into one large file, reducing initial download size.
- Seamless local workflow: First CMS to leverage the File System Access API for direct browser access to local files, eliminating the need for an insecure proxy server.
- Modern web application: Uses IndexedDB for caching, Intersection Observer for lazy loading, View Transition API for smooth visual transitions, and more.
- Improved config validation: TypeScript types and JSON schema are generated from a single source of truth, ensuring consistency between the codebase and editor support.
- Startup content fetching: Enables instant full text search, advanced relation fields, entry-asset linking, and better performance by fetching all entries in one go.
Choosing a Headless CMS
In addition to the architectural differences explained above, here are other factors to consider when choosing a headless CMS:
- License & Pricing: open source, commercial, freemium, or enterprise models
- Activity & Roadmap: update frequency, new features, bug fixes, and future plans
- Backend Support: Git providers, databases, file storage, and API capabilities
- Content Modeling: flexible schemas, custom fields, relationships, validations and i18n
- User Experience: intuitive UI, personalization, accessibility, performance, and mobile support
- Security & Access Control: roles, permissions, SSO, encryption, and vulnerability management
- Documentation & Support: tutorials, API reference, examples, FAQs, forums, and professional support
- Extensibility: plugins, integrations, APIs, SDKs, and customization options
- Media Management: image handling, file uploads, optimization, and gallery features
- Collaboration Features: editorial workflows, versioning, comments, and notifications
Sveltia CMS aims to excel in many of these areas while maintaining a simple, developer-friendly experience. We encourage you to explore its features and see how well it fits your project’s needs!