Ir para o conteúdo
Acecore

Guia de instalação do Sveltia CMS

by Gui
TecnologiaCMSAstroCloudflareSegurança
Índice
Guia de instalação do Sveltia CMS

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.

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
  • mudanças do CMS devem passar por Pull Request antes de produção

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 permitidos e cria uma branch temporária e um PR para cada alteração

.github/workflows/create-translation-prs.yml
  -> cria tarefas de tradução apenas para commits cms:

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 criar uma branch temporária e um PR, o proxy valida o repositório, a permissão de escrita do usuário GitHub, os caminhos alterados e o HEAD mais recente de main.

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. Branches temporárias mantêm main como única fonte de verdade.

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

collectionAlvoPolítica
blogsrc/content/blog/*.mdEditar só artigos fonte em japonês
authorssrc/content/authors/*.jsonEditar perfis e nomes localizados
tagssrc/content/tags/*.jsonEditar tags e nomes localizados
page textsrc/i18n/source/ja/**/*.jsonEditar 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 main como branch de publicação no preview

O proxy cria cada branch temporária a partir do main mais recente. Portanto, um preview do Cloudflare Pages não deve substituir a branch backend pela branch do PR. O resultado é revisado no Pages preview do PR de CMS gerado.

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

9. Criar branches temporárias com um proxy de salvamento

Um proxy de salvamento same-origin cria uma branch temporária e um PR para main a cada alteração.

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

O proxy não grava diretamente em main. Ele reúne conteúdo e mídia permitidos em um commit, cria cms/acecore/* a partir do main mais recente e abre um PR. Após revisão e merge, a branch temporária é removida automaticamente.

Com GitHub OAuth, o token do editor fornece identidade e atua como gravador. Com Cloudflare Access, uma GitHub App específica do site pode ser o ator. Restrições de caminho, branches temporárias, PRs e CI continuam comuns às duas variantes.

O modo de merge importa. As traduções dependem de subjects como cms: create ... e cms: update .... Se um squash merge apaga esses subjects, a automação pode não detectar a mudança. Para PRs de CMS, preserve os commits cms: com merge commit ou rebase merge.

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.
  • A branch de publicação não muda por ambiente; o preview verifica o resultado do PR de CMS.

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, PRs automáticos de CMS 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 branches temporárias do proxy de salvamento validado, PRs de CMS 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 grava apenas caminhos permitidos em uma branch temporária e um PR
Checklist de instalação
  • Concluído: Carregar Sveltia CMS em public/admin/index.html
  • Concluído: Definir GitHub backend e collections em public/admin/config.yml
  • Concluído: Usar OAuth Worker para edição por várias pessoas
  • Concluído: Alinhar media_folder e public_folder ao diretório public do Astro
  • Concluído: 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.
CompartilharX(abre em nova aba)B!Adicionar ao Hatena Bookmark(abre em nova aba)

Comentários

Carregando comentários...

Links, e-mails e textos promocionais não podem ser publicados.

G

Gui

CEO da Acecore. Lidera sistemas de negócio, web, bancos de dados e infraestrutura, qualidade e adoção de IA da definição de problemas de negócio ao design, implantação e melhoria após o lançamento. Parte de capacidade prática em C#/.NET e também cobre PHP/JavaScript, SQL Server/PostgreSQL/MySQL e Linux/Windows Server, desenhando requisitos, escolhas tecnológicas, padrões de qualidade e operações de desenvolvimento baseadas em GitHub como um fluxo único. Incorpora IA generativa a processos de desenvolvimento, verificação e organização de informações, como uma base prática para que equipes pequenas entreguem mais rápido e com maior confiabilidade.

Definição de problemas de negócioSeleção tecnológicaDesign de sistemasC#/.NETDesign de bancos de dados/infraestruturaOperações de desenvolvimento no GitHubIA generativaDesign de fluxos de IADesign de qualidadeIntegração em campo

Quer saber mais sobre nossos serviços?

Oferecemos suporte abrangente em desenvolvimento de sistemas, design web, operações de servidores e design gráfico.

Ver serviçosConsulta gratuita

Artigos relacionados

Como projetar um site Astro + Cloudflare que cresce por funcionalidadeComo projetar um site Astro + Cloudflare que cresce por funcionalidade7 de junho de 2026 às 19:00
TecnologiaAstroCloudflare
Como adicionar comentários a um blog Astro usando apenas CloudflareComo adicionar comentários a um blog Astro usando apenas Cloudflare7 de junho de 2026 às 18:00
TecnologiaCloudflareAstro
Renderizar links Markdown com segurança em respostas de chat com IARenderizar links Markdown com segurança em respostas de chat com IA7 de junho de 2026 às 14:30
TecnologiaSiteIA
O que era a antiga opção SSL paga da Cloudflare — de Dedicated SSL para Advanced Certificate ManagerO que era a antiga opção SSL paga da Cloudflare — de Dedicated SSL para Advanced Certificate Manager31 de março de 2026
TecnologiaCloudflareSegurança
Pesquisar no site

Após você inserir pelo menos dois caracteres, Conteúdo relacionado envia automaticamente seus termos de pesquisa ao Cloudflare Workers AI. Não insira informações pessoais ou confidenciais.Como os dados de pesquisa são tratados