Skill Sveltia CMS
Skill completa para integrar o Sveltia CMS em projetos de sites estáticos.
O que é o Sveltia CMS?
Sveltia CMS é um sistema de gerenciamento de conteúdo headless leve e baseado em Git, construído do zero como sucessor moderno do Decap CMS (antigo Netlify CMS). Ele fornece uma interface de edição rápida e intuitiva para conteúdo armazenado em repositórios Git.
Principais Características
-
Leve e Rápido
- Tamanho do bundle: <500 KB (minificado/brotli) vs 1.5-2.6 MB dos concorrentes
- Construído com o compilador Svelte (sem overhead de DOM virtual)
- Utiliza APIs GraphQL para busca instantânea de conteúdo
- Pesquisa baseada em relevância em todo o conteúdo
-
Experiência do Usuário Moderna
- Interface administrativa intuitiva com aproveitamento total da viewport
- Suporte a modo escuro (segue as preferências do sistema)
- Otimizado para dispositivos móveis e tablets
- Upload de arquivos por arrastar e soltar com suporte a múltiplos arquivos
- Visualização em tempo real com atualizações instantâneas
-
Arquitetura Nativa Git
- Conteúdo armazenado como Markdown, MDX, YAML, TOML ou JSON
- Controle de versão completo e histórico de alterações
- Sem dependência de fornecedor - o conteúdo vive com o código
- Suporte aos backends GitHub, GitLab, Gitea, Forgejo
-
Agnóstico de Framework
- Servido como bundle JavaScript vanilla
- Funciona com Hugo, Jekyll, 11ty, Gatsby, Astro, Next.js, SvelteKit
- Sem dependências de runtime de React, Vue ou framework
- Compatível com qualquer gerador de site estático
-
Internacionalização de Primeira Classe
- Suporte a múltiplos idiomas integrado
- Integração de tradução DeepL com um clique
- Alternância de localidade durante a edição
- Estruturas i18n flexíveis (arquivos, pastas, arquivo único)
-
Otimização de Imagem Integrada
- Conversão automática para WebP
- Redimensionamento e otimização no lado do cliente
- Suporte a otimização SVG
- Qualidade e dimensões configuráveis
Versões Atuais
- @sveltia/cms: 0.113.5 (Outubro de 2025)
- Status: Beta Público (v1.0 esperada para início de 2026)
- Maturidade: Pronto para produção (265+ problemas resolvidos do antecessor)
Quando Usar Esta Skill
✅ Use o Sveltia CMS Quando:
-
Construindo Sites Estáticos
- Blogs e documentação com Hugo
- Sites Jekyll e GitHub Pages
- Projetos 11ty (Eleventy)
- Sites de marketing com Gatsby
- Sites com muito conteúdo em Astro
-
Editores Não Técnicos Precisam de Acesso
- Equipes de marketing gerenciando páginas
- Autores escrevendo posts de blog
- Equipes de conteúdo sem conhecimento de Git
- Clientes precisando de atualizações fáceis de conteúdo
-
Fluxo de Trabalho Baseado em Git Desejado
- Versionamento de conteúdo através do Git
- Revisão de conteúdo através de pull requests
- Conteúdo vive com o código no repositório
- Integração CI/CD para deployments
-
Solução Leve Necessária
- Projetos sensíveis a desempenho
- Edição mobile-first necessária
- Tempos de carregamento rápidos críticos
- Tamanho mínimo do bundle importante
-
Migrando do Decap/Netlify CMS
- O config.yml existente pode ser reutilizado
- Substituição direta (alterar 1 linha)
- Melhor desempenho e UX
- Manutenção ativa e correções de bugs
❌ Não Use o Sveltia CMS Quando:
-
Colaboração em Tempo Real Necessária
- Múltiplos usuários editando simultaneamente (estilo Google Docs)
- Use Sanity, Contentful ou TinaCMS
-
Construção Visual de Páginas Necessária
- Construtores de página por arrastar e soltar necessários
- Use Webflow, Builder.io ou TinaCMS (React)
-
Dados Altamente Dinâmicos
- E-commerce com inventário em tempo real
- Dashboards ou análises em tempo real
- Use bancos de dados tradicionais (D1, PostgreSQL)
-
Edição Visual Específica para React Necessária
- Edição de componente em contexto
- Use TinaCMS (focado em React)
Sveltia CMS vs TinaCMS
Use Sveltia para:
- Hugo, Jekyll, 11ty, Gatsby (SSGs não-React)
- Experiência tradicional de painel admin CMS
- Requisitos de bundle leve
- Projetos agnósticos de framework
Use TinaCMS para:
- React, Next.js, Astro (componentes React)
- Edição visual em contexto
- Conteúdo type-safe orientado por esquema
- Experiência de desenvolvedor moderna com TypeScript
Ambos são válidos - Sveltia complementa o TinaCMS para diferentes casos de uso.
Padrões de Configuração por Framework
Use o padrão de configuração apropriado com base na sua escolha de framework.
1. Configuração Hugo (Mais Comum)
Hugo é o gerador de site estático mais popular para o Sveltia CMS.
Passos:
-
Criar diretório admin:
mkdir -p static/admin -
Criar página de índice 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>Gerenciador de Conteúdo</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
Criar arquivo de configuração:
# 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: Posts do Blog folder: content/posts create: true slug: '{{year}}-{{month}}-{{day}}-{{slug}}' fields: - { label: 'Título', name: 'title', widget: 'string' } - { label: 'Data', name: 'date', widget: 'datetime' } - { label: 'Rascunho', name: 'draft', widget: 'boolean', default: true } - { label: 'Tags', name: 'tags', widget: 'list', required: false } - { label: 'Corpo', name: 'body', widget: 'markdown' } -
Iniciar servidor de desenvolvimento Hugo:
hugo server -
Acessar admin:
http://localhost:1313/admin/
Modelo: Veja templates/hugo/
2. Configuração Jekyll
Jekyll é comumente usado com GitHub Pages e Sveltia CMS.
Passos:
-
Criar diretório admin:
mkdir -p admin -
Criar página de índice 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>Gerenciador de Conteúdo</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
Criar arquivo de configuração:
# 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: Posts do Blog folder: _posts create: true slug: '{{year}}-{{month}}-{{day}}-{{slug}}' fields: - { label: 'Layout', name: 'layout', widget: 'hidden', default: 'post' } - { label: 'Título', name: 'title', widget: 'string' } - { label: 'Data', name: 'date', widget: 'datetime' } - { label: 'Categorias', name: 'categories', widget: 'list', required: false } - { label: 'Corpo', name: 'body', widget: 'markdown' } -
Iniciar servidor de desenvolvimento Jekyll:
bundle exec jekyll serve -
Acessar admin:
http://localhost:4000/admin/
Modelo: Veja templates/jekyll/
3. Configuração 11ty (Eleventy)
11ty funciona bem com Sveltia CMS para sites estáticos flexíveis.
Passos:
-
Criar diretório admin:
mkdir -p admin -
Criar página de índice 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>Gerenciador de Conteúdo</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
Criar arquivo de configuração:
# admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: src/assets/images public_folder: /assets/images collections: - name: blog label: Posts do Blog folder: src/posts create: true slug: '{{slug}}' fields: - { label: 'Título', name: 'title', widget: 'string' } - { label: 'Descrição', name: 'description', widget: 'text' } - { label: 'Data', name: 'date', widget: 'datetime' } - { label: 'Tags', name: 'tags', widget: 'list', required: false } - { label: 'Corpo', name: 'body', widget: 'markdown' } -
Adicionar cópia passthrough ao
.eleventy.js:module.exports = function(eleventyConfig) { eleventyConfig.addPassthroughCopy('admin'); // ... resto da configuração }; -
Iniciar servidor de desenvolvimento 11ty:
npx @11ty/eleventy --serve -
Acessar admin:
http://localhost:8080/admin/
Modelo: Veja templates/11ty/
4. Configuração Astro
Astro é um framework moderno que funciona bem com Sveltia CMS.
Passos:
-
Criar diretório admin:
mkdir -p public/admin -
Criar página de índice 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>Gerenciador de Conteúdo</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
Criar arquivo de configuração:
# public/admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: public/images public_folder: /images collections: - name: blog label: Posts do Blog folder: src/content/blog create: true slug: '{{slug}}' format: mdx fields: - { label: 'Título', name: 'title', widget: 'string' } - { label: 'Descrição', name: 'description', widget: 'text' } - { label: 'Data de Publicação', name: 'pubDate', widget: 'datetime' } - { label: 'Imagem de Destaque', name: 'heroImage', widget: 'image', required: false } - { label: 'Corpo', name: 'body', widget: 'markdown' } -
Iniciar servidor de desenvolvimento Astro:
npm run dev -
Acessar admin:
http://localhost:4321/admin/
Modelo: Veja templates/astro/
5. Configuração Agnóstica de Framework
Aplica-se a: Gatsby, Next.js (modo SSG), SvelteKit, Remix, ou qualquer framework
Passos:
-
Determinar diretório público:
- Gatsby:
static/ - Next.js:
public/ - SvelteKit:
static/ - Remix:
public/
- Gatsby:
-
Criar diretório admin na pasta pública:
mkdir -p <pasta-publica>/admin -
Criar página de índice admin:
<!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Gerenciador de Conteúdo</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
Criar arquivo de configuração adaptado à sua estrutura de conteúdo:
backend: name: github repo: owner/repo branch: main media_folder: <seu-caminho-de-midia> public_folder: <seu-caminho-publico> collections: # Defina com base na sua estrutura de conteúdo -
Acessar admin:
http://localhost:<porta>/admin/
Configuração de Autenticação
Escolha o método de autenticação que se adequa à sua plataforma de implantação.
Opção 1: Cloudflare Workers OAuth (Recomendado) 🔥
Melhor para: Cloudflare Pages, Cloudflare Workers, qualquer implantação
Isso usa o worker oficial sveltia-cms-auth do Cloudflare para OAuth.
Passos:
-
Implantar Worker:
# Clone o auth worker git clone https://github.com/sveltia/sveltia-cms-auth cd sveltia-cms-auth # Instale dependências npm install # Implante no Cloudflare Workers npx wrangler deployOu use implantação com um clique:
- Visite https://github.com/sveltia/sveltia-cms-auth
- Clique no botão "Deploy to Cloudflare Workers"
-
Registrar App OAuth no GitHub:
- Vá para https://github.com/settings/developers
- Clique em "New OAuth App"
- Nome da Aplicação: CMS do Nome do Seu Site
- Homepage URL: https://seudominio.com
- Authorization callback URL: https://seu-worker.workers.dev/callback
- Salve o Client ID e o Client Secret
-
Configurar Variáveis de Ambiente do Worker:
# Configure credenciais do GitHub npx wrangler secret put GITHUB_CLIENT_ID # Cole seu Client ID npx wrangler secret put GITHUB_CLIENT_SECRET # Cole seu Client Secret # Opcional: Restringir a domínios específicos npx wrangler secret put ALLOWED_DOMAINS # Exemplo: seudominio.com,*.seudominio.com -
Atualizar configuração do CMS:
# admin/config.yml backend: name: github repo: owner/repo branch: main base_url: https://seu-worker.workers.dev # ← Adicione esta linha -
Testar autenticação:
- Abra o
/admin/do seu site - Clique em "Login with GitHub"
- Autorize o app
- Você deve ser redirecionado de volta ao CMS
- Abra o
Guia completo: Veja references/cloudflare-auth-setup.md
Modelo: Veja templates/cloudflare-workers/
Opção 2: Vercel Serverless Functions
Melhor para: Implantações Vercel
Passos:
-
Criar rota de API:
// api/auth.ts export default async function handler(req, res) { // Lógica de manipulação OAuth // Veja templates/vercel-serverless/api-auth.ts } -
Definir variáveis de ambiente na Vercel:
GITHUB_CLIENT_ID=seu_client_id GITHUB_CLIENT_SECRET=seu_client_secret -
Atualizar configuração do CMS:
backend: name: github repo: owner/repo branch: main base_url: https://seudominio.com/api/auth
Opção 3: Netlify Functions
Melhor para: Implantações Netlify
Passos:
-
Criar função Netlify:
// netlify/functions/auth.js exports.handler = async (event) => { // Lógica de manipulação OAuth // Veja templates/netlify-functions/auth.js }; -
Definir variáveis de ambiente na Netlify:
GITHUB_CLIENT_ID=seu_client_id GITHUB_CLIENT_SECRET=seu_client_secret -
Atualizar configuração do CMS:
backend: name: github repo: owner/repo branch: main base_url: https://seudominio.com/.netlify/functions/auth
Suporte a Múltiplos Backends Git
O Sveltia CMS suporta vários provedores Git. Use a configuração de backend correspondente.
GitHub
backend:
name: github
repo: owner/repo
branch: main
base_url: https://seu-worker.workers.dev
GitLab
backend:
name: gitlab
repo: owner/repo
branch: main
app_id: seu_app_id_gitlab
base_url: https://seudominio.com/api/auth
Gitea / Forgejo
backend:
name: gitea
repo: owner/repo
branch: main
api_root: https://git.exemplo.com/api/v1
base_url: https://seudominio.com/api/auth
Configuração de Coleções
Adapte estas configurações de coleção para se adequar à estrutura do seu conteúdo.
Coleção de Blog (Markdown)
collections:
- name: blog
label: Blog
folder: content/blog
create: true
delete: true
slug: '{{slug}}'
preview_path: blog/{{slug}}
fields:
- { label: 'Título', name: 'title', widget: 'string' }
- { label: 'Data de Publicação', name: 'date', widget: 'datetime' }
- { label: 'Imagem de Destaque', name: 'image', widget: 'image', required: false }
- { label: 'Tags', name: 'tags', widget: 'list', required: false }
- { label: 'Corpo', name: 'body', widget: 'markdown' }
Coleção de Páginas (Markdown)
collections:
- name: pages
label: Páginas
folder: content/pages
create: true
delete: true
slug: '{{slug}}'
preview_path: '{{slug}}'
fields:
- { label: 'Título', name: 'title', widget: 'string' }
- { label: 'URL Amigável', name: 'slug', widget: 'string', hint: 'O caminho da URL para esta página' }
- { label: 'Ordem no Menu', name: 'menu_order', widget: 'number', required: false }
- { label: 'Descrição', name: 'description', widget: 'text', required: false }
- { label: 'Conteúdo', name: 'body', widget: 'markdown' }
Configuração (JSON/YAML)
collections:
- name: settings
label: Configurações
files:
- label: Configurações Gerais
name: general
file: src/data/settings.json
format: json
fields:
- { label: 'Título do Site', name: 'site_title', widget: 'string' }
- { label: 'Descrição', name: 'description', widget: 'text' }
- { label: 'URL Base', name: 'base_url', widget: 'string' }
- { label: 'Email de Contato', name: 'contact_email', widget: 'string', required: false }
Internacionalização
Configure múltiplos idiomas no Sveltia CMS.
Configuração de Idiomas
i18n:
structure: multiple_folders # ou multiple_files, single_file
locales: [pt, en, es]
default_locale: pt
Coleção com i18n (Estrutura de Pastas Múltiplas)
collections:
- name: blog
label: Blog
folder: content/blog
create: true
i18n: true
fields:
- label: Título
name: title
widget: string
i18n: true
- label: Corpo
name: body
widget: markdown
i18n: true
Integração DeepL
Para habilitar tradução automática via DeepL:
- Obter chave de API DeepL em https://www.deepl.com/pro-api
- Adicionar ao config.yml:
i18n: deepl_api_key: sua_chave_depl
Solução de Problemas
Erros de Autenticação OAuth
Sintoma: Tela de login em branco ou redirecionamento falha
Soluções:
- Verifique se
base_urlcorresponde exatamente à URL do seu provedor de autenticação - No GitHub OAuth, verifique se o
Authorization callback URLestá correto - Confirme que as variáveis de ambiente (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET) estão definidas corretamente
- Verifique logs do seu provedor de autenticação para erros
- Se estiver usando Cloudflare Workers, execute
npx wrangler tailpara logs ao vivo
Erros de Parse YAML
Sintoma: "Erro ao parsear arquivo de configuração" ou seção de configuração não carregando
Soluções:
- Valide seu YAML com https://www.yamllint.com/
- Verifique se a indentação está consistente (use espaços, não tabs)
- Certifique-se de que os caminhos
folderexistam no seu repositório - Verifique se as strings com caracteres especiais estão devidamente escapadas
Exemplo de Config YAML Inválido (Corrigido)
# Inválido: indentação com tab
collections:
- name: blog
# Válido: indentação com espaços
collections:
- name: blog
Problemas de Política CORS/COOP
Sintoma: Admin carrega vazio ou console exibe erros de rede
Soluções:
- Certifique-se de que seu site serve arquivos estáticos corretamente
- Se estiver atrás de um proxy (Nginx, Apache), verifique a configuração de cabeçalhos CORS
- Para Cloudflare Pages, verifique as regras de transform HTTP
- Adicione cabeçalhos apropriados se necessário:
Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corp
Conteúdo Não Listando
Sintoma: Páginas admin carregam mas nenhum conteúdo é exibido
Soluções:
- Verifique se os caminhos da coleção
foldercorrespondem aos diretórios reais - Se estiver usando GitLab/Gitea, certifique-se de que o token de API tenha escopos de repositório
- Para repositórios privados, certifique-se de que o app OAuth tenha acesso
- Verifique o formato do arquivo: Sveltia CMS espera arquivos .md, .mdx, .yml, .yaml, .json, .toml