Insights / Artigos técnicos

Guia de instalação do Sveltia CMS

Guia prático para adicionar Sveltia CMS a um site Astro ou estático, cobrindo GitHub backend, OAuth Worker, uploads de imagem, operação multilíngue, PRs de CMS e aprendizados reais.

GuiPublicado7 de junho de 2026Atualizado 2 de agosto de 2026

Tecnologia
CMS
Astro
Cloudflare
Segurança

Sumário

Quando usar Sveltia CMS
Arquitetura geral
1. Colocar o admin em public/admin
2. Configurar GitHub backend
3. Adicionar OAuth Worker
4. Definir a pasta de mídia cedo
5. Separar collections
6. Usar relation e select
7. Editar JSON fonte em japonês
8. Manter credenciais de escrita somente em produção
9. Validar e publicar diretamente com o proxy
10. Tradução só para commits CMS
11. CSP próprio para /admin
Separar Turnstile
Lições de PRs e commits
Ponto inicial mínimo
Referências
Resumo

Sveltia CMS é útil quando você quer adicionar uma tela de edição a um site estático sem mover conteúdo para um banco externo. Este guia resume como ele foi introduzido no site Astro da Acecore e quais ajustes aprendemos com PRs e commits reais.

Atualizado em 28 de julho de 2026: os salvamentos do CMS agora são validados de forma síncrona e gravados como um único commit cms: direto em main. GitHub OAuth confirma o editor e sua permissão atual; uma GitHub App exclusiva de acecore-net executa as operações do repositório. Schemas JSON/Markdown, assinaturas de imagem, HTML/URLs ativos e o HEAD esperado são verificados antes da gravação.

O título é simples de propósito: Guia de instalação do Sveltia CMS. A meta é ajudar quem quer usar o CMS em outro site, não comparar ferramentas de forma abstrata.

Quando usar Sveltia CMS

Sveltia CMS não controla um banco de dados próprio nem entrega conteúdo por API separada. Ele é um app de administração em SPA que edita arquivos do repositório por meio do GitHub backend.

Ele combina bem quando:

o conteúdo vive como Markdown ou JSON no repositório
mudanças de artigo, autor, tag e textos de página devem ser revisadas como Git diff
você não quer adicionar banco de dados ou serviço administrativo separado
uploads podem ficar em public/uploads
salvamentos do CMS devem iniciar a publicação imediatamente, enquanto mudanças de código continuam protegidas por Pull Request

Se você precisa de permissões editoriais complexas, publicação agendada avançada, grande DAM ou edição em tempo real, um headless CMS completo pode ser melhor.

Arquitetura geral

public/admin/index.html
  -> carrega @sveltia/cms via CDN

public/admin/config.yml
  -> define GitHub backend, collections e pastas de mídia

workers/sveltia-cms-auth
  -> Cloudflare Worker para GitHub OAuth

main branch
  -> única fonte de verdade para produção

CMS save proxy
  -> valida caminhos e conteúdo e grava um commit cms: com expected HEAD em main

.github/workflows/submit-openai-translation-batch.yml
  -> agrupa por 15 minutos as atualizações da fonte em japonês e as envia ao OpenAI Batch

Instalar a página de admin é só a primeira etapa. Autenticação, mídia, preview, tradução e merge strategy precisam ser parte do desenho.

1. Colocar o admin em `public/admin`

No Astro, arquivos em public são servidos como estáticos. A documentação do Sveltia CMS também aponta public como pasta estática para Astro, Next.js, Nuxt, Remix e VitePress.

<!doctype html>
<html lang="pt">
  <head>
    <meta charset="utf-8" />
    <meta name="robots" content="noindex,nofollow" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>CMS</title>
  </head>
  <body>
    <script src="https://unpkg.com/@sveltia/cms@0.172.4/dist/sveltia-cms.js"></script>
  </body>
</html>

Não adicione CSS extra ou type="module" sem motivo. O bundle do Sveltia CMS já inclui os estilos da UI.

Na Acecore usamos inicialização manual para configurar o backend explicitamente. A branch de publicação permanece main em todos os ambientes.

CMS.init({
  config: {
    backend: {
      branch: "main",
    },
  },
});

2. Configurar GitHub backend

O mínimo é backend.name e backend.repo, mas em produção defina também branch, OAuth e mensagens de commit.

backend:
  name: github
  repo: owner/repository
  branch: main
  base_url: https://your-sveltia-cms-auth-worker.example.workers.dev
  api_root: /admin/api/github
  graphql_api_root: /admin/api/graphql
  auth_methods: [oauth]
  commit_messages:
    create: 'cms: create {{collection}} "{{slug}}"'
    update: 'cms: update {{collection}} "{{slug}}"'
    delete: 'cms: delete {{collection}} "{{slug}}"'
    uploadMedia: 'cms: upload "{{path}}"'
    deleteMedia: 'cms: delete media "{{path}}"'

Mantenha main como branch de publicação e encaminhe leituras e salvamentos por um proxy same-origin. Antes de cada save, o proxy revalida a permissão de escrita do usuário GitHub, usa uma GitHub App instalada apenas em acecore-net para acessar o repositório e valida caminhos, conteúdo e o HEAD mais recente de main antes de criar um único commit direto.

Em 20 de julho de 2026, o Editorial Workflow ainda não está implementado no Sveltia CMS. Adicionar a opção do Decap CMS publish_mode: editorial_workflow não faz o Sveltia CMS criar branches temporárias ou PRs automaticamente.

Uma branch permanente como cms-content exige sincronização contínua e aumenta o risco de conflitos ou de configurar a origem de deploy incorretamente. A Acecore mantém main como única fonte de verdade e rejeita atualizações concorrentes com expectedHeadOid.

3. Adicionar OAuth Worker

Personal Access Token é suficiente para teste, mas não é a melhor opção para vários editores. A Acecore usa Sveltia CMS Authenticator em Cloudflare Workers e aponta base_url para esse Worker.

O callback do GitHub OAuth App aponta para /callback no Worker. O Worker recebe GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET e, se necessário, ALLOWED_DOMAINS.

Isso é diferente de Turnstile. OAuth protege login do CMS; Turnstile protege formulários ou APIs contra bots.

4. Definir a pasta de mídia cedo

Sveltia CMS pode salvar mídia dentro do repositório. Em Astro, o caminho prático é:

media_folder: public/uploads
public_folder: /uploads

A Acecore corrigiu esse ponto depois no PR #116. A lição é decidir o caminho no repositório e a URL pública antes dos primeiros uploads.

5. Separar collections

collection	Alvo	Política
`blog`	`src/content/blog/*.md`	Editar só artigos fonte em japonês
`authors`	`src/content/authors/*.json`	Editar perfis e nomes localizados
`tags`	`src/content/tags/*.json`	Editar tags e nomes localizados
page text	`src/i18n/source/ja/*/.json`	Editar texto fonte japonês de páginas e UI

Não exponha todos os Markdown traduzidos sem necessidade. A Acecore mantém o japonês como fonte canônica e atualiza traduções por Como operar um blog multilíngue com Sveltia CMS.

6. Usar relation e select

Tags devem ser selecionadas por relation, não digitadas livremente.

- name: tags
  label: Tags
  widget: relation
  collection: tags
  value_field: name
  display_fields: ["{{name}} ({{id}})"]
  search_fields: [name, id]
  multiple: true
  required: false

Autores, ícones e tons de aviso seguem a mesma lógica. CMS bom não só permite editar; ele dificulta salvar valores quebrados.

7. Editar JSON fonte em japonês

Textos fixos também podem entrar no CMS. A Acecore centraliza a fonte japonesa em src/i18n/source/ja/**/*.json e expõe por página.

O cuidado é não adicionar todos os campos de uma vez. config.yml cresce rapidamente. Comece por blog, autores, tags, avisos e páginas que mudam com frequência.

8. Manter credenciais de escrita somente em produção

Configure o client ID, installation ID e private key da GitHub App somente no ambiente de produção do Cloudflare Pages. Previews não recebem credenciais de escrita e permanecem sem leitura ou escrita no repositório. O conteúdo é salvo e publicado apenas pelo /admin/ de produção; previews ficam para PRs normais de código ou configuração.

CMS.init({
  config: {
    backend: {
      branch: "main",
    },
  },
});

9. Validar e publicar diretamente com o proxy

Um proxy same-origin valida de forma síncrona o escopo e o conteúdo permitidos e cria exatamente um commit em main.

backend:
  name: github
  repo: owner/repository
  branch: main
  api_root: /admin/api/github
  graphql_api_root: /admin/api/graphql

GitHub OAuth verifica novamente o editor e sua permissão de escrita antes do save. Um token curto da GitHub App exclusiva de acecore-net faz as leituras e gravações. Só conteúdo e imagens permitidos são aceitos; SVG e PDF são rejeitados.

O save usa o HEAD inicial como expectedHeadOid; uma atualização concorrente retorna 409. Se a resposta do GitHub se perder, só há recuperação quando marker da request, SHA pai, todos os paths e SHAs dos blobs coincidem.

O commit direto mantém subjects como cms: create ... e cms: update .... O mesmo push da GitHub App inicia Pages e a tarefa de tradução. Código, schemas, workflows, configuração CMS e traduções continuam passando por PR e CI.

10. Tradução só para commits CMS

O PR #98 adicionou --cms-only, para que tarefas de tradução por push só sejam criadas com commits CMS.

function isCmsCommitSubject(subject) {
  return /^cms: (create|update|delete) /.test(subject || "");
}

cms: é um contrato de workflow, não decoração.

11. CSP próprio para `/admin`

O admin precisa conectar ao CDN, GitHub API, OAuth Worker e blob URLs. Por isso, a Acecore separa a CSP de /admin/* e marca a área como noindex.

Separar Turnstile

A versão antiga misturava seleção de CMS e Cloudflare Turnstile. Isso confundia o assunto.

Sveltia CMS trata de backend GitHub, OAuth, collections, mídia e PRs. Turnstile trata de reduzir bots em formulários ou APIs. São camadas diferentes.

Lições de PRs e commits

Ao mudar o CMS, atualize também artigos e links internos.
OAuth deve fazer parte do setup real.
Caminhos de mídia devem ser definidos antes de uploads.
config.yml deve crescer por etapas.
cms: é contrato de automação.
As credenciais de escrita ficam somente em produção; preview serve sem acesso ao repositório para PRs normais de código e configuração.

Ponto inicial mínimo

public/admin/index.html
public/admin/config.yml
public/admin/init.js
public/admin/runtime-config.js

Depois adicione relations de autores e tags, imagens, JSON fonte, validação síncrona de direct publish e tarefas de tradução.

Referências

Resumo

Sveltia CMS é simples de colocar em public/admin, mas a instalação de produção exige decidir branch, OAuth, pastas de mídia, política de idioma fonte, workflow de tradução e merge strategy. Com essas regras claras, um site Astro continua estático e leve, mas ganha uma operação de conteúdo muito mais utilizável.

Fluxo de instalação do Sveltia CMS

A área administrativa, autenticação, conteúdo editável, mídia e fluxo de PR devem ser pensados separadamente.

Adicionar o admin
Coloque index.html e config.yml em public/admin e carregue o Sveltia CMS.
Configurar GitHub
Defina repo, branch, OAuth Worker e mensagens de commit antes de começar a editar.
Limitar o escopo editável
Exponha apenas blog, autores, tags e JSON fonte em japonês que devem ser editados pelo CMS.
Automatizar a operação
Use main como branch de publicação e conecte commits diretos validados, deploys do Pages e tarefas de tradução.

Antes e depois do CMS

Markdown editado manualmente

Só quem usa GitHub ou editor atualiza com facilidade
Caminhos de imagem, IDs de autor e tags são digitados à mão
Fonte japonesa e traduções podem ser misturadas
O destino de salvamento e os caminhos graváveis podem ficar ambíguos

Edição com Sveltia CMS

Markdown e JSON são editados em formulários no navegador
relation, image e select reduzem valores inválidos
Apenas commits de CMS disparam tarefas de tradução
Um proxy same-origin valida o conteúdo permitido e grava um commit direto em main

Checklist de instalação

Carregar Sveltia CMS em public/admin/index.html
Definir GitHub backend e collections em public/admin/config.yml
Usar OAuth Worker para edição por várias pessoas
Alinhar media_folder e public_folder ao diretório public do Astro
Decidir como commits de CMS acionam tradução ou publicação

Perguntas frequentes

Para que tipo de site o Sveltia CMS serve?

Ele funciona bem para sites estáticos onde Markdown ou JSON ficam no repositório, como Astro, Hugo e VitePress. Assim é possível adicionar CMS sem banco de dados externo.

Posso usar só um Personal Access Token do GitHub?

Pode, mas para várias pessoas ou editores não técnicos, um OAuth Worker é mais seguro e fácil de explicar. A Acecore usa Cloudflare Worker como cliente OAuth.

Devo editar todos os idiomas no CMS?

Em uma equipe pequena, é mais seguro editar apenas a fonte japonesa e atualizar traduções por PR. Expor todos os idiomas dificulta revisão e detecção de traduções desatualizadas.

Quando usar Sveltia CMS

Arquitetura geral

1. Colocar o admin em public/admin

2. Configurar GitHub backend

3. Adicionar OAuth Worker

4. Definir a pasta de mídia cedo

5. Separar collections

6. Usar relation e select

7. Editar JSON fonte em japonês

8. Manter credenciais de escrita somente em produção

9. Validar e publicar diretamente com o proxy

10. Tradução só para commits CMS

11. CSP próprio para /admin

Separar Turnstile

Lições de PRs e commits

Ponto inicial mínimo

Referências

Resumo

Fluxo de instalação do Sveltia CMS

Adicionar o admin

Configurar GitHub

Limitar o escopo editável

Automatizar a operação

Antes e depois do CMS

Markdown editado manualmente

Edição com Sveltia CMS

Checklist de instalação

Perguntas frequentes

1. Colocar o admin em `public/admin`

11. CSP próprio para `/admin`