Guia de Migração para Sanity: Movendo do WordPress, Contentful ou Drupal

Migrei cerca de 40 projetos para Sanity nos últimos três anos. Alguns foram sprints limpos de duas semanas. Outros se transformaram em maratonas de três meses que me fizeram questionar minhas escolhas de carreira. A diferença quase nunca depende do CMS de origem — tudo se resume a preparação, decisões de modelagem de conteúdo e ser honesto sobre o que você realmente está assumindo.

Este é o guia que gostaria de ter tido quando comecei a fazer migrações de CMS. Ele aborda a mudança do WordPress, Contentful e Drupal para o mundo alimentado por GROQ do Sanity. Vou ser franco sobre onde Sanity se destaca, onde ela vai frustrar você e qual é o cronograma real.

Índice

• Por que os times estão se mudando para Sanity em 2025
• Auditoria Pré-Migração: O Passo que Todos Pulam
• Migração de WordPress para Sanity
• Migração de Contentful para Sanity
• Migração de Drupal para Sanity
• Modelagem de Conteúdo: Acertando seus Esquemas
• Estratégias e Ferramentas de Migração de Dados
• Os Custos Ocultos que Ninguém Fala
• Lista de Verificação Pós-Migração
• Comparação de Cronograma e Orçamento
• FAQ

Por que os times estão se mudando para Sanity em 2025

Vamos deixar as coisas óbvias de lado. A edição colaborativa em tempo real do Sanity, o Studio personalizável e a abordagem de conteúdo estruturado são genuinamente bons. Mas a razão pela qual a maioria dos times nos procura sobre migração não é porque leram um post de blog sobre os recursos do Sanity. É porque algo quebrou.

Sites WordPress atingem limites de escalabilidade em torno de 50.000+ pedaços de conteúdo com tipos de post personalizados complexos. O modelo de preços do Contentful começa a apertar no nível empresarial — temos visto times enfrentando contas de $3.500+/mês pelo que é essencialmente uma API de conteúdo. Times de Drupal não conseguem encontrar desenvolvedores, ou pelo menos não aqueles que querem trabalhar com templates PHP em 2025.

O modelo de preços do Sanity é genuinamente mais previsível para a maioria dos times. O nível gratuito cobre até 100K requisições de API/mês e 500K assets. O plano Growth a $99/mês/projeto oferece 2,5M requisições de API e 1M assets. Para comparação, o plano Team do Contentful custa $300/mês e o nível Premium do Contentful pode facilmente exceder $2.000/mês.

Mas aqui está minha opinião honesta: se seu CMS atual está funcionando bem e seu time é produtivo, não migre apenas porque Sanity é mais novo ou mais legal. Migrações sempre custam mais do que você pensa.

Auditoria Pré-Migração: O Passo que Todos Pulam

Antes de escrever uma única linha de código de migração, você precisa de uma auditoria de conteúdo. Não uma varredura rápida — uma auditoria real. Aqui está como fica:

Inventário de Conteúdo

Documente todo tipo de conteúdo, todo campo, toda relação. Uso uma planilha com essas colunas:

• Nome do tipo de conteúdo
• Total de itens
• Campos (com tipos)
• Relacionamentos com outros tipos de conteúdo
• Anexos de mídia (contagem e tamanho total)
• Funcionalidade personalizada (shortcodes, widgets, embeds)
• Data da última modificação
• Ainda relevante? (Sim/Não/Talvez)

Você ficará chocado com quanto conteúdo é peso morto. Em uma migração de WordPress, um cliente tinha 12.000 posts. Após a auditoria, apenas 4.200 ainda eram relevantes. Isso é 65% menos conteúdo para migrar, testar e validar.

Mapeamento de Dependência Técnica

Liste todo plugin, módulo ou integração que seu CMS atual usa. Para cada um, determine:

1. Sanity pode lidar com isso nativamente?
2. Existe um plugin Sanity para isso?
3. Precisamos construir uma solução personalizada?
4. Podemos descartar isso completamente?

Este mapeamento sozinho economizará semanas de surpresas no futuro.

Avaliação de Prontidão do Time

Sanity Studio é baseado em React. Seus editores de conteúdo precisarão de treinamento. Seus desenvolvedores precisarão aprender GROQ (ou usar GraphQL, embora GROQ seja onde Sanity realmente brilha). Orçamente 1-2 semanas para onboarding do time — não como um "gostaria de ter", mas como um item de linha.

Migração de WordPress para Sanity

WordPress é o CMS de origem mais comum do qual migramos. É também o mais complicado, porque WordPress não é apenas um CMS — é uma plataforma de aplicação inteira que as pessoas parafusaram tudo nela.

O que é transferido facilmente

• Posts e páginas (conteúdo básico)
• Categorias e tags
• Imagens em destaque
• Dados do autor
• Campos personalizados básicos (ACF, Meta Box)

O que fica confuso

• Blocos Gutenberg: Cada tipo de bloco precisa de um bloco personalizado correspondente em Portable Text ou tipo de objeto Sanity. Se você tem 15+ blocos Gutenberg personalizados, orçamente tempo significativo aqui.
• Shortcodes: Estes precisam ser analisados, interpretados e convertidos para anotações Portable Text ou blocos personalizados. Shortcodes WPBakery e Elementor são particularmente dolorosos.
• Conteúdo gerado por plugins: Produtos WooCommerce, dados Yoast SEO, campos de repetidor ACF — cada um requer lógica de migração personalizada.
• Biblioteca de mídia: WordPress armazena múltiplos tamanhos de imagem. Sanity gerencia transformações de imagem on-the-fly, então você só precisa dos originais. Mas encontrar os originais em uma pasta wp-uploads confusa? Que diversão.

Abordagem de Script de Migração

Normalmente uso um script Node.js que atinge a API REST do WordPress e escreve na API de mutação do Sanity:

import { createClient } from '@sanity/client'
import fetch from 'node-fetch'

const sanity = createClient({
  projectId: 'your-project-id',
  dataset: 'production',
  token: process.env.SANITY_WRITE_TOKEN,
  apiVersion: '2025-01-01',
  useCdn: false,
})

const WP_API = 'https://yoursite.com/wp-json/wp/v2'

async function migratePosts(page = 1) {
  const res = await fetch(`${WP_API}/posts?per_page=100&page=${page}`)
  const posts = await res.json()
  const totalPages = res.headers.get('x-wp-totalpages')

  const transaction = sanity.transaction()

  for (const post of posts) {
    transaction.createOrReplace({
      _id: `wp-post-${post.id}`,
      _type: 'post',
      title: post.title.rendered,
      slug: { current: post.slug },
      publishedAt: post.date,
      // Body requer conversão de HTML-para-Portable-Text
      body: await convertToPortableText(post.content.rendered),
    })
  }

  await transaction.commit()
  console.log(`Migrados ${page} de ${totalPages}`)

  if (page < totalPages) {
    await migratePosts(page + 1)
  }
}

A função convertToPortableText é onde 80% da complexidade reside. Uso o pacote @sanity/block-tools combinado com jsdom para análise de HTML. Lida bem com HTML básico, mas elementos personalizados e shortcodes precisam de manipuladores individuais.

Cronograma Realista

Para um site WordPress típico com 500-2.000 posts, campos personalizados padrão e alguns tipos de post personalizados: 4-8 semanas incluindo modelagem de conteúdo, scripting de migração, validação de dados e treinamento de editores.

Migração de Contentful para Sanity

Contentful-para-Sanity é na verdade o caminho de migração mais suave dos três. Por quê? Porque ambos são plataformas de conteúdo estruturado com modelos mentais semelhantes. Seu conteúdo já está em um CMS headless com tipos de conteúdo e campos definidos.

Diferenças-chave a considerar

Recurso	Contentful	Sanity
Texto rico	Rich Text (baseado em JSON)	Portable Text (baseado em JSON)
Modelagem de conteúdo	UI da web	Esquemas definidos em código
Linguagem de consulta	GraphQL / REST	GROQ (+ GraphQL)
Localização	Integrada em nível de campo	Plugin ou personalizado
Referências	Links (Entry/Asset)	Referências com tipos
Webhooks	Sim	Sim
Tratamento de assets	CDN integrado	CDN Sanity + hotspot/crop
Preço (nível médio)	~$300/mês (Team)	$99/mês (Growth)

Conversão de Texto Rico

Rich Text do Contentful e Portable Text do Sanity são ambos baseados em JSON, o que é ótimo. Mas têm estruturas diferentes. Você precisará escrever um transformador:

function contentfulRichTextToPortableText(richTextField) {
  return richTextField.content.map(node => {
    switch (node.nodeType) {
      case 'paragraph':
        return {
          _type: 'block',
          style: 'normal',
          children: node.content.map(mapInlineContent),
        }
      case 'heading-2':
        return {
          _type: 'block',
          style: 'h2',
          children: node.content.map(mapInlineContent),
        }
      case 'embedded-entry-block':
        // Mapear para seu tipo Portable Text personalizado
        return mapEmbeddedEntry(node)
      // ... tratar todos os tipos de nó
    }
  }).filter(Boolean)
}

Mapeamento de Tipo de Conteúdo para Schema

Tipos de conteúdo Contentful mapeiam de forma bastante direta para tipos de documento e objeto Sanity. A mudança maior é que esquemas Sanity são definidos em código (JavaScript/TypeScript), não em uma UI da web. Na verdade, isso é uma enorme vantagem — seu modelo de conteúdo vive no controle de versão.

Use a API de Gerenciamento do Contentful para exportar seu modelo de conteúdo, então escreva um script que gera arquivos de schema Sanity:

contentful space export --space-id YOUR_SPACE_ID --export-dir ./export

Cronograma Realista

Para um espaço Contentful com 10-20 tipos de conteúdo e 5.000-10.000 entradas: 3-5 semanas. É mais rápido porque você já está pensando em conteúdo estruturado.

Migração de Drupal para Sanity

Migrações Drupal são aquelas que me fazem despejar um segundo café. Não porque Drupal seja ruim — é um sistema poderoso. Mas sites Drupal tendem a ser antigos, personalizados até a exaustão, e executados em infraestrutura que ninguém entende completamente mais.

Os Desafios Específicos do Drupal

• Tipos de conteúdo com 50+ campos: Drupal torna fácil adicionar campos. Fácil demais. Vi tipos de conteúdo com 80 campos, metade dos quais não utilizados.
• Referências de termos de taxonomia: O sistema de taxonomia do Drupal é flexível mas pode criar hierarquias profundamente aninhadas que precisam ser achatadas para Sanity.
• Módulo Paragraphs: Se o site usa Drupal Paragraphs (e a maioria dos sites Drupal modernos usa), cada tipo de parágrafo se torna um tipo de bloco Portable Text ou objeto Sanity. Esta é a maior tarefa única.
• Entidades de mídia: O sistema de mídia do Drupal 9/10 é mais complexo que o do WordPress. Múltiplos tipos de mídia, entidades de mídia reutilizáveis e configurações de campo de arquivo tudo precisa de mapeamento.
• Conteúdo multilíngue: O sistema de tradução do Drupal é sofisticado. Sanity não tem localização integrada no mesmo nível — você precisará do plugin @sanity/document-internationalization ou de uma abordagem em nível de campo.

Abordagem de Migração

Prefiro usar o módulo JSON:API do Drupal (incluído no núcleo Drupal desde 9.x) como camada de extração:

async function fetchDrupalContent(type, page = 0) {
  const limit = 50
  const offset = page * limit
  const url = `${DRUPAL_URL}/jsonapi/node/${type}?page[limit]=${limit}&page[offset]=${offset}&include=field_image,field_paragraphs`

  const res = await fetch(url, {
    headers: { Authorization: `Basic ${DRUPAL_AUTH}` },
  })
  return res.json()
}

Para sites Drupal 7 mais antigos sem JSON:API, você pode precisar consultar o banco de dados diretamente. O schema de banco de dados do Drupal 7 é... uma experiência. As tabelas field_data_* vão assombrar seus sonhos.

Cronograma Realista

Migrações Drupal variam bastante. Um site Drupal 10 direto com 5-10 tipos de conteúdo: 5-8 semanas. Um site legado Drupal 7 com 30+ tipos de conteúdo, Paragraphs e conteúdo multilíngue: 8-16 semanas. Não estou exagerando.

Modelagem de Conteúdo: Acertando seus Esquemas

Aqui está a coisa que a maioria dos guias de migração não dirá: não replique seu modelo de conteúdo antigo em Sanity. Esta é sua chance de corrigir anos de débito técnico de conteúdo acumulado.

Erros Comuns de Modelagem

1. Criar um mapeamento de campo 1:1: Apenas porque WordPress tinha um campo personalizado "subtitle" não significa que Sanity precise de um. Talvez deva fazer parte de um objeto estruturado "hero".
2. Sobre-aninhar objetos: Sanity permite você aninhar objetos profundamente. Resista ao impulso. Esquemas mais planos são mais fáceis de consultar com GROQ e mais fáceis para editores trabalharem.
3. Ignorar o poder do Portable Text: Não apenas despeje HTML em um único campo de texto. Projete tipos de bloco personalizados que correspondam aos seus padrões de conteúdo. Um bloco "callout", um bloco "code snippet", um bloco "image with caption" — estes melhoram a vida dos editores.

Processo de Design de Schema

Sigo esta ordem:

1. Auditoria de conteúdo existente (feito na pré-migração)
2. Identificar os padrões de conteúdo reais (não o que o CMS impôs)
3. Projetar esquemas em papel/whiteboard primeiro
4. Construir esquemas em código
5. Importar um pequeno lote de teste (50-100 itens)
6. Fazer editores testarem a experiência do Studio
7. Iterar em esquemas antes da migração completa

Os passos 5-7 são críticos e frequentemente pulados. Escrevemos mais sobre abordagens de modelagem de conteúdo em nosso trabalho de desenvolvimento de CMS headless.

Estratégias e Ferramentas de Migração de Dados

Ferramentas Essenciais

• @sanity/client: O cliente JavaScript oficial para ler/escrever dados Sanity
• @sanity/block-tools: Converte HTML para Portable Text
• sanity dataset import/export: Ferramentas CLI para operações de dataset completo
• ndjson: Sanity usa newline-delimited JSON para importações — fique confortável com isso
• jsdom ou htmlparser2: Para análise de HTML durante conversão de texto rico

Arquitetura de Migração

Estruturo cada migração como um pipeline com quatro estágios:

Extrair → Transformar → Carregar → Validar

Cada estágio é um script separado. Isso importa porque você rodará a migração múltiplas vezes — tipicamente 5-10 vezes antes da execução final de produção. Ter estágios separados significa que você pode re-rodar apenas as partes que precisam correção.

# Extrair
node scripts/extract-wordpress.js > data/raw-posts.ndjson

# Transformar
node scripts/transform-posts.js < data/raw-posts.ndjson > data/sanity-posts.ndjson

# Carregar
sanity dataset import data/sanity-posts.ndjson production --replace

# Validar
node scripts/validate-migration.js

Tratamento de Assets

Imagens e arquivos são sempre a parte mais lenta. O pipeline de assets do Sanity é bom, mas fazer upload de 10.000 imagens leva tempo. Dicas:

• Faça upload de assets primeiro, mantenha um mapeamento de URLs antigas para IDs de assets Sanity novos
• Use uploads simultâneos (mas respeite limites de taxa — 25 req/seg para o plano Growth)
• Verifique dimensões e formatos de imagem antes do upload
• Não migre tamanhos de miniaturas — Sanity gera estes on-the-fly via seu CDN de imagem

Os Custos Ocultos que Ninguém Fala

Deixe-me ser direto com você sobre custos que não aparecem na estimativa típica de migração.

Redirecionamentos de URL

Se você está mudando seu frontend (o que você provavelmente está se estiver movendo para um CMS headless), você precisa de mapeamento de redireção. Cada. URL. Único. Para SEO, isso é inegociável. Um site com 5.000 páginas precisa de 5.000 regras de redireção. Ferramentas como redirecionamentos next.config.js ou arquivo _redirects do Vercel podem lidar com isso, mas alguém precisa construir o mapeamento.

Migração de Metadados SEO

Dados Yoast SEO do WordPress. Dados do módulo Metatag do Drupal. Campos SEO do Contentful. Tudo isso precisa vir. Títulos de meta personalizados, descrições, imagens Open Graph, URLs canônicas, dados estruturados — é um projeto dentro do projeto.

Treinamento de editores e documentação

Orçamente 2-4 dias no mínimo. Sanity Studio é intuitivo, mas é diferente do que seus editores conhecem. Normalmente criamos documentação personalizada do Studio com screenshots e gravamos 3-5 vídeos de walkthrough.

Desenvolvimento Frontend

Este é o elefante na sala. Migrar conteúdo para Sanity é apenas metade do projeto. Você também precisa de um frontend que consome o conteúdo. Se você está usando Next.js, Astro ou outro framework, a construção do frontend é muitas vezes 50-70% do custo total do projeto. Confira nosso trabalho com Next.js e Astro se está avaliando opções de frontend.

Comparação de Cronograma e Orçamento

Com base em projetos que completamos em 2024-2025:

Caminho de Migração	Volume de Conteúdo	Complexidade	Cronograma	Intervalo de Orçamento
WordPress → Sanity	< 1.000 páginas	Baixa	3-5 semanas	$8K-$15K
WordPress → Sanity	1.000-10.000 páginas	Média	6-10 semanas	$15K-$35K
WordPress → Sanity	10.000+ páginas	Alta	10-16 semanas	$35K-$75K
Contentful → Sanity	< 5.000 entradas	Baixa-Média	3-5 semanas	$7K-$18K
Contentful → Sanity	5.000-20.000 entradas	Média	5-8 semanas	$18K-$40K
Drupal → Sanity	< 2.000 nós	Média	5-8 semanas	$12K-$25K
Drupal → Sanity	2.000-15.000 nós	Alta	8-14 semanas	$25K-$60K
Drupal 7 → Sanity	Qualquer	Muito Alta	10-20 semanas	$35K-$90K

Nota: Estes intervalos incluem apenas migração de conteúdo. Desenvolvimento frontend é adicional. Entre em contato conosco em /pricing para estimativas específicas do projeto.

Esses números incluem modelagem de conteúdo, scripting de migração, validação de dados e treinamento básico de editores. Eles não incluem desenvolvimento frontend, design ou manutenção contínua.

Lista de Verificação Pós-Migração

Aqui está a lista de verificação que uso em cada migração:

• Todos os tipos de conteúdo migrados e verificados
• Todas as referências/relacionamentos intactos
• Todas as imagens e arquivos carregados e vinculados corretamente
• Conteúdo de texto rico renderizado corretamente (verificar formatação quebrada)
• Redirecionamentos de URL em lugar e testados
• Metadados SEO migrados (títulos, descrições, dados OG)
• Mapa de site XML regenerado
• Search Console atualizado com novo mapa de site
• Rastreamento de análise preservado
• Contas de editor criadas e permissões definidas
• Treinamento de editor concluído
• Visualização de conteúdo (modo rascunho) funcionando
• Webhooks configurados para gatilhos de build
• Backup de dados do CMS de origem arquivado
• Mudanças de DNS planejadas (se aplicável)
• Baseline de desempenho medida
• Monitoramento de 404 configurado para os primeiros 30 dias

Este último ponto é importante. Não importa o quão minucioso seu mapeamento de redireção seja, algumas URLs vazarão. Monitore seus 404s agressivamente no primeiro mês.

FAQ

Quanto tempo uma migração típica de WordPress para Sanity leva? Para um site WordPress padrão com menos de 2.000 posts e campos personalizados simples, espere 4-8 semanas. Isso inclui modelagem de conteúdo, scripting de migração, validação de dados e treinamento de editores. Sites com blocos Gutenberg complexos, WooCommerce ou conteúdo multilíngue podem levar 10-16 semanas. O volume de conteúdo importa menos que a complexidade de seus tipos de conteúdo.

Posso migrar de Contentful para Sanity sem perder dados? Sim, e é na verdade o caminho de migração mais limpo entre os três que cobro aqui. Ambas as plataformas usam conteúdo estruturado baseado em JSON, portanto o mapeamento é relativamente direto. Texto rico precisa de conversão do formato Contentful para Portable Text e referências precisam ser remapeadas, mas você não deveria perder dados. Recomendo rodar a migração contra um dataset de preparação primeiro e fazer uma comparação de conteúdo minuciosa antes do cutover.

O que acontece com meus rankings SEO durante uma migração de CMS? Esta é a pergunta que mantém diretores de marketing acordados à noite. Se você lidar com redirecionamentos adequadamente, mantiver sua estrutura de URL onde possível e migrar todos os metadados SEO, você deveria ver impacto mínimo. A documentação do próprio Google diz que migrações adequadamente redirecionadas podem ver um dip temporário de 2-4 semanas antes de se recuperarem. A palavra-chave é "adequadamente". Pule o mapeamento de redireção e você vai afundar seus rankings. Vimos acontecer.

Sanity é mais barata que Contentful para uso empresarial? Na maioria dos casos, sim — às vezes significativamente. O plano Growth do Sanity a $99/mês cobre o que você precisaria do plano Team do Contentful de $300/mês. Em escala empresarial, a diferença fica maior. O preço do Contentful Premium não é listado publicamente, mas tipicamente corre $2.000-$4.000+/mês. O preço Sanity Enterprise também é personalizado, mas geralmente fica menor para uso equivalente. A verdadeira diferença de custo está nas chamadas de API — os limites inclusos do Sanity são mais generosos.

Devo migrar meu site Drupal 7 para Sanity ou atualizar para Drupal 10 primeiro? Vá direto para Sanity. Migrar de Drupal 7 para Drupal 10 é quase tanto trabalho quanto migrar para um CMS diferente — a arquitetura mudou tão drasticamente entre versões. Se você já está investindo em uma grande migração, você também pode se mover para a plataforma que você realmente quer estar no longo prazo. A única exceção: se seu time está profundamente investido no ecossistema Drupal e apenas quer modernizar, Drupal 10 com um frontend headless é um caminho válido.

Preciso reconstruir meu frontend ao migrar para Sanity? Se você está vindo de um CMS monolítico como WordPress ou Drupal, sim — você precisará de um novo frontend, já que Sanity é headless. Isso é geralmente a parte maior do projeto. Se você está vindo de Contentful, você pode frequentemente reutilizar seu frontend existente com chamadas de API modificadas, especialmente se você já está usando Next.js ou framework similar. Nós tratamos tanto a migração CMS quanto as construções de frontend como projetos integrados.

Posso rodar meu CMS antigo e Sanity em paralelo durante a migração? Absolutamente, e eu recomendo. Rode ambos os sistemas por 2-4 semanas após sua migração inicial. Editores podem continuar trabalhando no CMS antigo enquanto você valida dados em Sanity. Apenas congele conteúdo no sistema antigo antes de sua execução de migração final — você não quer perseguir um alvo em movimento. Alguns times definem uma data de "content freeze" 48 horas antes do cutover final.

Qual é o maior erro que times cometem durante uma migração Sanity? Tentar replicar sua estrutura de CMS antiga exatamente em Sanity. Vejo isso constantemente. Times vêm do WordPress e tentam construir esquemas em forma de WordPress em Sanity — tipos de "page" genéricos com layouts flexíveis em vez de tipos de conteúdo construídos com propósito. A força do Sanity é conteúdo estruturado. Use a migração como uma oportunidade para modelar seu conteúdo apropriadamente. Gaste uma semana extra em modelagem de conteúdo. Vai economizar você meses de dor depois. Se você quer orientação sobre isso, entre em contato conosco — modelagem de conteúdo é uma das coisas nas quais gastamos o máximo de tempo em projetos de migração.