Seu time autoriza a mudança para Sanity. Você exporta 80.000 posts do WordPress, ativa uma instância do Studio, e descobre que metade dos seus meta fields seguem três schemas diferentes — e ninguém documentou a lógica de taxonomias customizadas que alimentava toda a navegação do seu site. Executei mais de 40 migrações para Sanity em três anos. Algumas fecharam em duas semanas. Outras se estenderam por três meses e me fizeram reconsiderar cada decisão que me levou ao trabalho autônomo. A diferença nunca veio de você estar deixando WordPress, Contentful ou Drupal. Veio de três coisas: como você foi honesto ao definir seu modelo de conteúdo desde o início, se você tratou field-mapping como arquitetura ou trabalho ocupado, e se alguém no seu time admitiu que não entendia como seu CMS antigo realmente funcionava. Este playbook o guia por cada decisão que determina se sua migração é um sprint limpo ou um desravelling em câmera lenta — e mostra os checklists exatos, scripts e modelos mentais que separam os dois.

Este é o guia que gostaria de ter tido quando comecei a fazer migrações de CMS. Ele cobre a mudança do WordPress, Contentful e Drupal para o mundo alimentado por GROQ do Sanity. Vou ser direto sobre onde Sanity brilha, onde vai frustrar você, e como são os prazos reais.

Sumário

Sanity Migration Playbook: Moving from WordPress, Contentful, or Drupal

Por que times estão se movendo para Sanity em 2026

Vamos sair do óbvio. A edição colaborativa em tempo real do Sanity, Studio customizável e abordagem de conteúdo estruturado são genuinamente bons. Mas o motivo pelo qual a maioria dos times nos contatam sobre migração não é porque leram um post sobre recursos do Sanity. É porque algo quebrou.

Sites WordPress batem em limites de escalabilidade em torno de 50.000+ conteúdos com tipos de post customizados complexos. O modelo de preço do Contentful começa a apertar no tier enterprise — vimos times enfrentando contas de $3.500+/mês por o que é essencialmente uma API de conteúdo. Times Drupal não conseguem achar desenvolvedores mais, pelo menos não que queiram trabalhar com templating PHP em 2026.

O modelo de preço do Sanity é genuinamente mais previsível para a maioria dos times. O tier gratuito cobre até 100K requisições de API/mês e 500K assets. O plano Growth em $99/mês/projeto te dá 2,5M requisições de API e 1M assets. Para comparação, o plano Team do Contentful custa $300/mês e o tier Premium do Contentful facilmente pode 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 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 fazer uma auditoria de conteúdo. Não uma varredura rápida — uma auditoria de verdade. Aqui está como isso se parece:

Inventário de Conteúdo

Documente cada tipo de conteúdo, cada campo, cada relacionamento. Eu 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 customizada (shortcodes, widgets, embeds)
  • Data da última modificação
  • Ainda relevante? (Sim/Não/Talvez)

Você vai se chocar com quanto conteúdo é peso morto. Em uma migração 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ências Técnicas

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 customizada?
  4. Podemos descartar isso inteiramente?

Este mapeamento sozinho vai te poupar semanas de surpresas adiante.

Avaliação de Prontidão do Time

Sanity Studio é baseado em React. Seus editores de conteúdo vão precisar de treinamento. Seus desenvolvedores vão precisar 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 nice-to-have, mas como um item de linha.

Migração de WordPress para Sanity

WordPress é a fonte de CMS mais comum de que migramos. É também a mais complicada, porque WordPress não é apenas um CMS — é uma plataforma de aplicação inteira que as pessoas encaixotaram tudo.

O que se transfere limpo

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

O que fica bagunçado

  • Blocos Gutenberg: Cada tipo de bloco precisa de um bloco customizado correspondente de Portable Text do Sanity ou um tipo de objeto. Se você tem 15+ blocos Gutenberg customizados, orçamente tempo significativo aqui.
  • Shortcodes: Estes precisam ser parseados, interpretados e convertidos para anotações de Portable Text ou blocos customizados. Shortcodes do WPBakery e Elementor são particularmente dolorosos.
  • Conteúdo gerado por plugin: Produtos WooCommerce, dados Yoast SEO, campos repeater ACF — cada um requer lógica de migração customizada.
  • Media library: WordPress armazena múltiplos tamanhos de imagem. Sanity lida com transformações de imagem on-the-fly, então você só precisa dos originais. Mas encontrar os originais em uma pasta wp-uploads bagunçada? Diversão pura.

Abordagem de Script de Migração

Tipicamente uso um script Node.js que acessa a API REST do WordPress e escreve na API de mutation 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 requires HTML-to-Portable-Text conversion
      body: await convertToPortableText(post.content.rendered),
    })
  }

  await transaction.commit()
  console.log(`Migrated page ${page} of ${totalPages}`)

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

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

Timeline Realista

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

Sanity Migration Playbook: Moving from WordPress, Contentful, or Drupal - architecture

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 similares. 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
Rich text Rich Text (baseado em JSON) Portable Text (baseado em JSON)
Modelagem de conteúdo Web UI Schemas definidos em código
Linguagem de query GraphQL / REST GROQ (+ GraphQL)
Localização Nível de campo integrado Plugin ou customizado
Referências Links (Entry/Asset) Referências com tipos
Webhooks Sim Sim
Manipulação de assets CDN integrado Sanity CDN + hotspot/crop
Preço (mid-tier) ~$300/mês (Team) $99/mês (Growth)

Conversão de Rich Text

Rich Text do Contentful e Portable Text do Sanity são ambos baseados em JSON, o que é ótimo. Mas têm estruturas diferentes. Você vai 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':
        // Map to your custom Portable Text type
        return mapEmbeddedEntry(node)
      // ... handle all node types
    }
  }).filter(Boolean)
}

Mapeamento de Tipo de Conteúdo para Schema

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

Use a API de Management do Contentful para exportar seu modelo de conteúdo, depois escreva um script que gera arquivos de schema Sanity:

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

Timeline 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 servir um segundo café. Não porque Drupal é ruim — é um sistema poderoso. Mas sites Drupal tendem a ser antigos, customizados ao extremo e rodando em infraestrutura que ninguém entende completamente.

Os Desafios Específicos do Drupal

  • Tipos de conteúdo com 50+ campos: Drupal faz fácil adicionar campos. Muito fácil. Vi tipos de conteúdo com 80 campos, metade dos quais não usados.
  • Referências de termos de taxonomy: O sistema de taxonomy 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 fazem), cada tipo de parágrafo se torna um tipo de bloco Portable Text ou objeto Sanity. Esta é a maior tarefa única.
  • Media entities: O sistema de media do Drupal 9/10 é mais complexo que o do WordPress. Múltiplos tipos de mídia, media entities reutilizáveis e configurações de file field tudo precisa de mapeamento.
  • Conteúdo multilingue: O sistema de tradução do Drupal é sofisticado. Sanity não tem localização integrada no mesmo nível — você vai precisar do plugin @sanity/document-internationalization ou uma abordagem de nível de campo.

Abordagem de Migração

Prefiro usar o módulo JSON:API do Drupal (incluído no Drupal core 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.

Timeline Realista

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

Modelagem de Conteúdo: Acertando seus Schemas

Aqui está a coisa que a maioria dos guias de migração não vai te dizer: não replique seu modelo de conteúdo antigo em Sanity. Esta é sua chance de consertar anos de dívida técnica de conteúdo acumulada.

Erros Comuns de Modelagem

  1. Criar um mapeamento de campo 1:1: Só porque WordPress tinha um campo customizado "subtitle" não significa que Sanity precisa de um. Talvez deveria ser parte de um objeto "hero" estruturado.
  2. Over-nesting objetos: Sanity te deixa aninhar objetos profundamente. Resista ao impulso. Schemas achatados-ish são mais fáceis de consultar com GROQ e mais fáceis para editores trabalharem.
  3. Ignorar o poder de Portable Text: Não apenas despeje HTML em um campo de texto único. Projete tipos de blocos customizados que correspondam a seus padrões de conteúdo. Um bloco "callout", um bloco "code snippet", um bloco "image com caption" — estes tornam a vida dos editores melhor.

Processo de Design de Schema

Sigo esta ordem:

  1. Auditar 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. Desenhar schemas em papel/whiteboard primeiro
  4. Construir schemas em código
  5. Importar um pequeno lote de teste (50-100 itens)
  6. Ter editores testarem a experiência do Studio
  7. Iterar nos schemas 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 parsing de HTML durante conversão de rich text

Arquitetura de Migração

Eu estruturo cada migração como um pipeline com quatro etapas:

Extract → Transform → Load → Validate

Cada etapa é um script separado. Isso importa porque você vai rodar a migração múltiplas vezes — tipicamente 5-10 vezes antes da rodada de produção final. Ter etapas separadas significa que você pode re-rodar apenas as partes que precisam ser corrigidas.

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

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

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

# Validate
node scripts/validate-migration.js

Manipulando 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 antigos para IDs de assets Sanity novos
  • Use uploads concorrentes (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 thumbnail — Sanity gera estes on-the-fly via seu CDN de imagem

Os Custos Ocultos que Ninguém Fala

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

Redirects de URL

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

Migração de Metadata SEO

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

Treinamento de Editor e Documentação

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

Desenvolvimento de 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 está usando Next.js, Astro ou outro framework, a construção do frontend é frequentemente 50-70% do custo total do projeto. Confira nosso trabalho com Next.js e Astro se estiver avaliando opções de frontend.

Comparação de Timeline e Orçamento

Baseado em projetos que completamos em anos recentes:

Caminho de Migração Volume de Conteúdo Complexidade Timeline Faixa 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 nodes Média 5-8 semanas $12K-$25K
Drupal → Sanity 2.000-15.000 nodes 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 de frontend é adicional. Entre em contato em /pricing para estimativas específicas do projeto.

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

Checklist Pós-Migração

Aqui está o checklist 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 ativados e ligados corretamente
  • Conteúdo de rich text renderizado corretamente (verificar formatação quebrada)
  • Redirects de URL em lugar e testados
  • Metadata SEO migrado (títulos, descrições, dados OG)
  • XML sitemap regenerado
  • Search console atualizado com novo sitemap
  • Rastreamento de analytics preservado
  • Contas de editor criadas e permissões definidas
  • Treinamento de editor concluído
  • Preview de conteúdo (modo draft) funcionando
  • Webhooks configurados para gatilhos de build
  • Backup de dados do CMS fonte arquivado
  • Mudanças de DNS planejadas (se aplicável)
  • Baseline de desempenho medido
  • Monitoramento 404 configurado para primeiros 30 dias

Esse último ponto é importante. Não importa o quão completo seja seu mapeamento de redirect, algumas URLs vão escapar. Monitore seus 404s agressivamente para o primeiro mês.

FAQ

Quanto tempo leva uma migração típica de WordPress para Sanity?

Para um site WordPress padrão com menos de 2.000 posts e campos customizados diretos, espere 4-8 semanas. Isso inclui modelagem de conteúdo, script de migração, validação de dados e treinamento de editor. Sites com blocos Gutenberg complexos, WooCommerce ou conteúdo multilingue 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 cubro aqui. Ambas as plataformas usam conteúdo estruturado baseado em JSON então o mapeamento é relativamente direto. Rich text precisa de conversão do formato Contentful para Portable Text e referências precisam ser remapeadas, mas você não deveria perder nenhum dado. Recomendo rodar a migração contra um dataset de staging primeiro e fazer uma comparação completa de conteúdo antes de cortar.

O que acontece com meus rankings de SEO durante uma migração de CMS?

Esta é a questão que mantém diretores de marketing acordados à noite. Se você manusear redirects propriamente, manter sua estrutura de URL onde possível e migrar todo metadata de SEO, você deveria ver impacto mínimo. A documentação do Google diz que migrações propriamente redirecionadas podem ver um dip temporário de 2-4 semanas antes de recuperar. A palavra-chave é "propriamente". Pule o mapeamento de redirect e você vai derrubar seus rankings. Vimos acontecer.

Sanity é mais barato que Contentful para uso enterprise?

Na maioria dos casos, sim — às vezes significativamente. O plano Growth do Sanity em $99/mês cobre o que você precisaria do plano Team do Contentful em $300/mês. Em escala enterprise, a diferença fica maior. O preço Premium do Contentful não é listado publicamente mas tipicamente custa $2.000-$4.000+/mês. O preço Enterprise do Sanity também é customizado mas geralmente vem mais baixo para uso equivalente. A diferença real de custo está em 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 drasticamente entre versões. Se você já está investindo em uma migração principal, você poderia também se mover para a plataforma que você realmente quer estar em longo prazo. A uma 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 vem de um CMS monolítico como WordPress ou Drupal, sim — você vai precisar de um novo frontend já que Sanity é headless. Isso geralmente é a parte maior do projeto. Se vem de Contentful, você frequentemente pode reusar seu frontend existente com chamadas de API modificadas, especialmente se já está usando Next.js ou framework similar. Lidamos tanto com migração de CMS quanto com builds de frontend como projetos integrados.

Posso rodar meu CMS antigo e Sanity em paralelo durante a migração?

Absolutamente, e 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 rodada de migração final — você não quer perseguir um alvo em movimento. Alguns times definem uma data de "content freeze" 48 horas antes da cutover final.

Qual é o maior erro que times fazem durante uma migração Sanity?

Tentar replicar a estrutura exata de seu CMS antigo em Sanity. Vejo isso constantemente. Times vêm de WordPress e tentam construir schemas em forma de WordPress em Sanity — tipos de "page" genéricos com layouts flexíveis ao invés de tipos de conteúdo propositados. A força do Sanity é conteúdo estruturado. Use a migração como uma oportunidade para modelar seu conteúdo propriamente. Gaste uma semana extra em modelagem de conteúdo. Vai te poupar meses de dor depois. Se quer orientação sobre isso, entre em contato conosco — modelagem de conteúdo é uma das coisas que gastamos mais tempo em projetos de migração.