Migrei mais de uma dúzia de lojas Shopify para arquiteturas headless nos últimos três anos. Algumas correram bem. Algumas foram pesadelos. A diferença quase sempre veio do planejamento — especificamente, se o time entendia realmente no que estava se metendo antes de escrever a primeira linha de código.

Este guia cobre tudo o que gostaria que alguém tivesse me dito antes da minha primeira migração headless de Shopify: qual framework frontend escolher, como preservar seus rankings de SEO, como alcançar zero downtime durante o cutover, quanto custa realmente, e prazos realistas baseados na complexidade da loja. Sem enrolação. Sem "depende" sem explicar do que depende.

Índice

Migração Shopify para Headless: Guia Next.js, Hydrogen & Remix

Por que Migrar do Shopify para Headless?

Vamos deixar uma coisa clara: Shopify padrão é ótimo para a maioria das lojas. Se você está fazendo menos de $2M/ano e seu tema faz o que você precisa, você provavelmente não precisa de headless. Sério mesmo. Dissuadi mais pessoas dessa migração do que converti.

Mas há razões legítimas para ir headless:

  • Limite de performance: Temas Liquid têm um gargalo de rendering. Mesmo com Online Store 2.0 e Dawn, você está limitado pelo pipeline de server-side rendering do Shopify. Lojas headless consistentemente atingem scores de sub-1-segundo de LCP.
  • Experiências customizadas: Configuradores de produtos, try-on com AR, filtragem complexa, mecanismos de personalização — estes são dolorosos de construir em Liquid.
  • Multi-storefront: Um backend alimentando seu site DTC, portal wholesale, app mobile e lojas internacionais.
  • Marcas content-rich: Se sua marca depende fortemente de conteúdo editorial, lookbooks e storytelling, acoplar um CMS headless ao motor de comércio do Shopify te dá o melhor dos dois mundos.
  • Experiência do desenvolvedor: Seu time quer trabalhar em React/TypeScript, não Liquid. Isso importa mais do que as pessoas admitem.

Os ganhos de performance são reais e mensuráveis. Em 2025, Core Web Vitals do Google impactam diretamente seus rankings de busca. Lojas que migrei para headless tipicamente veem uma melhoria de 30-50% em LCP e 40-60% em Total Blocking Time. Isso se traduz em melhorias mensuráveis de taxa de conversão — dados próprios do Shopify sugerem que uma melhoria de 1% na velocidade da página pode aumentar conversão em até 0,7%.

Arquitetura Shopify Headless Explicada

Quando as pessoas dizem "Shopify headless", querem dizer desacoplando o frontend (o que clientes veem) do backend (motor de comércio do Shopify). Você mantém Shopify para produtos, inventário, pedidos, checkout e pagamentos. Você constrói um frontend customizado que fala com Shopify via Storefront API.

Aqui está a arquitetura típica:

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│ Frontend        │────▶│ Storefront API    │────▶│ Shopify Backend │
│ Customizado     │     │ (GraphQL)         │     │ (Produtos,      │
│ (Next.js/H2/    │     │                   │     │ Carrinho, Peds) │
│ Remix)          │     │                   │     │                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │
        ▼
┌─────────────────┐
│ CMS Headless    │
│ (Sanity,        │
│ Contentful,     │
│ Storyblok)      │
└─────────────────┘

Merchants Shopify Plus ganham acesso à Checkout Extensibility API, que permite customizar checkout sem redirecionar para o checkout hospedado do Shopify. Para lojas não-Plus, clientes ainda são redirecionados para checkout.shopify.com para a compra real — o que honestamente não é uma experiência terrível, mas é uma interrupção de UX.

A Storefront API

Tudo passa pela Storefront API do Shopify, um endpoint GraphQL que cuida de:

  • Queries de produtos e coleções
  • Gerenciamento de carrinho (criar, atualizar, remover itens)
  • Autenticação de clientes
  • Conteúdo (metafields, metaobjects)
  • Localização e moeda da loja

A API tem limites de taxa — 50 pontos de custo por segundo para um único app. Na prática, isso raramente é um problema se você cachear apropriadamente, mas pode te morder durante vendas relâmpago se você não tiver planejado.

# Exemplo: Buscando um produto com variantes
query ProductQuery($handle: String!) {
  product(handle: $handle) {
    id
    title
    descriptionHtml
    priceRange {
      minVariantPrice {
        amount
        currencyCode
      }
    }
    variants(first: 100) {
      edges {
        node {
          id
          title
          availableForSale
          price {
            amount
          }
          selectedOptions {
            name
            value
          }
        }
      }
    }
    images(first: 10) {
      edges {
        node {
          url
          altText
          width
          height
        }
      }
    }
  }
}

Escolhendo seu Frontend: Next.js vs Hydrogen vs Remix

Este é o lugar onde a maioria dos times fica presa. Aqui está minha opinião honesta depois de construir lojas em produção com os três.

Funcionalidade Next.js 15 Hydrogen 2024.10+ Remix (Shopify)
Maturidade do framework Muito maduro, ecossistema massivo Madurando, específico do Shopify Maduro (merged no React Router 7)
Integração Shopify Manual via Storefront API First-party, hooks built-in Boa via Hydrogen UI
Hosting Vercel, Netlify, self-hosted Oxygen (Shopify) ou self-hosted Qualquer lugar, mas otimizado para Oxygen
Curva de aprendizado Moderada Moderada-Alta Moderada
Comunidade/contratação Massiva Pequena mas crescendo Média
Flexibilidade SSR/SSG Excelente (App Router) SSR-focado (streaming) SSR-focado (loaders)
Controle de cache ISR, revalidação on-demand Caching de sub-requisição Oxygen Caching HTTP padrão
Melhor para Times com experiência React, necessidades complexas de conteúdo Times nativos Shopify, lojas simples-médias Times querendo o caminho recomendado do Shopify

Next.js: A Aposta Segura

Next.js é o que recomendo para a maioria dos times, especialmente se você está emparelhando Shopify com um CMS headless como Sanity ou Contentful. O ecossistema é imenso, contratação é mais fácil, e você tem flexibilidade incrível com os server components do App Router.

A desvantagem? Você tem que conectar a integração do Shopify você mesmo. Não há um SDK oficial do Shopify para Next.js (apesar de pacotes da comunidade como @shopify/hydrogen-react te darem hooks de carrinho e utilitários). Você vai gastar mais tempo em boilerplate.

Construímos muitas lojas Shopify headless com Next.js na Social Animal — é nossa stack mais requisitada para projetos de ecommerce.

Hydrogen: Framework Próprio do Shopify

Hydrogen é o framework headless oficial do Shopify, construído em cima de Remix (agora React Router 7). Ele vem com componentes pré-construídos para produtos, carrinhos e SEO — mais integração apertada com Oxygen, plataforma de hosting edge do Shopify.

O apelo é claro: menos boilerplate, caching otimizado para Shopify, e uma história de deploy que simplesmente funciona no Oxygen. A release 2024.10 trouxe melhorias significativas incluindo melhor suporte TypeScript e atualizações de UI otimistas para operações de carrinho.

As desvantagens? Comunidade menor, menos recursos quando você fica preso, e você está um tanto acoplado ao ecossistema do Shopify. Se você alguma vez quiser trocar backends de comércio, você está reescrevendo muito mais código do que faria com Next.js.

Remix / React Router 7

Aqui está a parte confusa: Remix foi merged no React Router 7. Hydrogen é construído em Remix. Então "Remix para Shopify" efetivamente significa Hydrogen na maioria dos contextos.

Se você quer usar React Router 7 sem as abstrações específicas do Shopify do Hydrogen, você pode. Você vai ter os mesmos padrões de loader/action, o mesmo streaming SSR, e controle total sobre sua integração Shopify. Isso faz sentido se você já é um time Remix e quer flexibilidade máxima.

Minha Recomendação

Para marcas content-heavy com layouts de página complexos: Next.js + CMS headless. Para lojas DTC simples que querem o caminho mais rápido para produção: Hydrogen no Oxygen. Para times já investidos no ecossistema Remix: React Router 7 com componentes Hydrogen UI.

Migração Shopify para Headless: Guia Next.js, Hydrogen & Remix - arquitetura

O Processo de Migração Passo a Passo

Aqui está o processo que sigo para cada migração. É chato. Funciona.

Fase 1: Auditoria e Planejamento (2-3 semanas)

  1. Rastreie o site existente — Use Screaming Frog ou Sitebulb para catalogar cada URL, redirect, tag canônica e bloco de dados estruturados. Exporte isso. Você vai precisar mais tarde.
  2. Documente todas as integrações — Klaviyo, Yotpo reviews, programas de fidelidade, apps de subscription (Recharge, Loop), gateways de pagamento. Cada um.
  3. Mapeie estruturas de URL — Suas novas URLs vão combinar com as antigas? Shopify usa /products/product-handle e /collections/collection-handle. Se você mudar estas, você precisa de redirects.
  4. Identifique funcionalidade customizada — Qualquer coisa além de padrão browse-and-buy. Gift cards, bundles, preços wholesale, multi-moeda, B2B.
  5. Escolha sua stack — Framework frontend, CMS, hosting, CDN.

Fase 2: Construir o Frontend (6-12 semanas)

Aqui é onde o desenvolvimento real acontece. Áreas-chave:

  • Páginas de produtos com seleção de variante, galerias de imagens, integração de reviews
  • Páginas de coleção com filtragem, ordenação, paginação
  • Carrinho com verificações de inventário em tempo real e upsells
  • Busca — Predictive Search API do Shopify ou terceiros como Algolia
  • Contas de clientes — login, histórico de pedidos, gerenciamento de endereços
  • Páginas com CMS — homepage, sobre, landing pages
  • Redirect de checkout — tratando a entrega ao checkout Shopify
// Exemplo: Página de produto Next.js com ISR
import { getProduct } from '@/lib/shopify'
import { ProductDetails } from '@/components/product-details'

export async function generateStaticParams() {
  const products = await getAllProductHandles()
  return products.map((handle) => ({ handle }))
}

export default async function ProductPage({ 
  params 
}: { 
  params: { handle: string } 
}) {
  const product = await getProduct(params.handle)
  
  if (!product) notFound()

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify(generateProductJsonLd(product)),
        }}
      />
      <ProductDetails product={product} />
    </>
  )
}

export const revalidate = 60 // ISR: revalidar a cada 60 segundos

Fase 3: Integração e QA (2-4 semanas)

Conecte todos os serviços de terceiros. Teste tudo. E quero dizer tudo:

  • Faça pedidos de teste em todos os métodos de pagamento
  • Teste códigos de desconto, gift cards, descontos automáticos
  • Verifique rastreamento de analytics (GA4, Meta Pixel, TikTok Pixel)
  • Teste de carga nas chamadas da Storefront API sob tráfego esperado
  • Teste em dispositivos reais, não apenas Chrome DevTools

Fase 4: Cutover (1-2 dias)

A troca real. Mais sobre isso na seção zero-downtime abaixo.

Preservação de SEO Durante Migração

Aqui é onde migrações dão errado. Vi lojas perderem 40% de tráfego orgânico porque alguém esqueceu de redirects de URL. Não seja esse time.

Mapeamento de URL

Crie um documento completo de mapeamento de URL antes de escrever uma única regra de redirect. Cada URL no site antigo precisa de um destino no novo site.

ANTIGA: /collections/summer-2024
NOVA: /collections/summer-2024  ← Mesma? Ótimo, nenhum redirect necessário.

ANTIGA: /blogs/news/our-story
NOVA: /journal/our-story  ← Diferente? Redirect 301 necessário.

ANTIGA: /pages/about-us
NOVA: /about  ← Diferente? Redirect 301 necessário.

Dados Estruturados

Temas Shopify incluem dados estruturados básicos. Quando você vai headless, você é responsável por implementar você mesmo. No mínimo:

  • Schema Product com offers, aggregateRating
  • BreadcrumbList para navegação
  • Organization para sua marca
  • WebSite com SearchAction para busca sitelinks
  • FAQPage onde aplicável

Meta Tags e Canônicas

Cada página precisa de <title> apropriado, <meta description>, URL canônica e tags Open Graph. Em Next.js, use a Metadata API:

export async function generateMetadata({ params }): Promise<Metadata> {
  const product = await getProduct(params.handle)
  
  return {
    title: product.seo.title || product.title,
    description: product.seo.description || product.description,
    openGraph: {
      images: [product.featuredImage?.url],
    },
    alternates: {
      canonical: `https://yourstore.com/products/${params.handle}`,
    },
  }
}

XML Sitemap

Gere seu sitemap dinamicamente a partir dos dados do Shopify. Inclua produtos, coleções e páginas CMS. Envie para Google Search Console imediatamente após migração.

Checklist de SEO Pré-Migração

  • Documento completo de mapeamento de URL
  • Redirects 301 configurados e testados
  • Dados estruturados implementados e validados
  • Meta tags puxando de campos SEO do Shopify
  • XML sitemap gerado dinamicamente
  • robots.txt configurado corretamente
  • Google Search Console notificado de mudança de domínio (se aplicável)
  • Links internos atualizados para nova estrutura de URL
  • Textos alt de imagem preservados do Shopify

Estratégia de Migração com Zero Downtime

Zero downtime não é mágica. É gerenciamento de DNS e preparação.

A Abordagem Blue-Green Deployment

  1. Construa e deploy o novo site em um domínio staging (ex: new.yourstore.com)
  2. Execute ambos os sites simultaneamente por pelo menos uma semana, testando o novo site completamente
  3. Configure seu CDN/DNS para suportar switching instantâneo (Cloudflare, Vercel ou Netlify todos suportam isso)
  4. Troque DNS para apontar para o novo frontend — TTL deve estar setado para 60 segundos bem antecipadamente
  5. Monitore tudo: taxas de erro, 404s, taxas de conversão, Core Web Vitals

A Abordagem Proxy (Ainda Mais Segura)

Para lojas fazendo mais de $1M/mês, prefiro uma migração baseada em proxy:

  1. Coloque um reverse proxy (Cloudflare Workers, Vercel Edge Middleware) na frente de ambos os sites antigos e novos
  2. Roteie tráfego página por página — comece com uma página de baixo risco como /about
  3. Gradualmente mova páginas para o novo frontend em 2-4 semanas
  4. Monitore a performance de cada página antes de mover o próximo lote
  5. Páginas de produto e coleção vêm por último (risco de receita mais alto)

Esta abordagem adiciona complexidade mas permite você pegar problemas antes deles afetarem sua loja inteira.

// Exemplo de Vercel Edge Middleware para migração gradual
import { NextResponse } from 'next/server'

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl
  
  // Páginas já migradas para novo frontend
  const migratedPaths = ['/about', '/contact', '/journal']
  
  if (migratedPaths.some(path => pathname.startsWith(path))) {
    return NextResponse.next() // Serve do novo frontend
  }
  
  // Tudo mais faz proxy para loja Shopify antiga
  return NextResponse.rewrite(
    new URL(pathname, 'https://old-store.myshopify.com')
  )
}

Breakdown de Preços e Prazos

Vamos falar números reais. Estes são baseados em projetos que vi em 2025, variando de lojas DTC simples a operações complexas multi-mercado.

Complexidade da Loja Prazo Custo Agência Custo Freelancer
Simples (< 50 produtos, páginas básicas, checkout padrão) 8-12 semanas $40.000 - $75.000 $20.000 - $40.000
Médio (50-500 produtos, CMS, subscriptions, multi-moeda) 12-20 semanas $75.000 - $150.000 $40.000 - $80.000
Complexo (500+ produtos, B2B+DTC, checkout customizado, múltiplas integrações) 20-32 semanas $150.000 - $300.000+ $80.000 - $150.000

Custos Recorrentes

Não esqueça as despesas recorrentes:

  • Shopify Plus: $2.300/mês (necessário para extensibilidade de checkout, recomendado para headless)
  • Hosting: $20-500/mês (Vercel Pro é $20/usuário, Oxygen é incluído com Shopify)
  • CMS Headless: $0-500/mês (Sanity, Contentful, Storyblok todos têm tiers gratuitos)
  • Busca: $0-500/mês se usando Algolia ou similar
  • Manutenção: Orçamento 10-15% do custo inicial anualmente

Para times explorando qual seria o custo de uma migração Shopify headless para sua situação específica, detalhamos nossa abordagem de preços aqui. Também estamos felizes em fazer scope de coisas em uma chamada rápida.

Armadilhas Comuns em Migrações

1. Subestimando o Carrinho

O carrinho parece simples até você considerar: códigos de desconto, descontos automáticos, gift cards, propriedades de item de linha, notas de carrinho, frete estimado, cálculos de taxa e metafields de nível de carrinho. Orçamente o dobro do tempo que você acha que precisa para funcionalidade de carrinho.

2. Esquecendo de Apps

Aquele ecossistema de app Shopify em que você confia? A maioria dos apps injeta JavaScript no seu tema Liquid. Ir headless significa você precisa de alternativas baseadas em API ou implementações customizadas para reviews, wishlists, programas de fidelidade e mais.

3. Customização de Checkout

Sem Shopify Plus ($2.300/mês), você não pode customizar a experiência de checkout. Clientes serão redirecionados para o checkout hospedado do Shopify, o que cria uma desconexão visual. Merchants Plus podem usar Checkout Extensibility, mas ainda está mais limitado que um checkout completamente customizado.

4. Não Fazer Teste de Performance Cedo

A Storefront API adiciona latência. Se você está fazendo 8 chamadas de API para renderizar uma página de produto, você vai sentir. Cachear agressivamente, usar fragmentos GraphQL para minimizar over-fetching, e implementar streaming SSR onde possível.

5. Ignorar o Time de Conteúdo

Seu time de marketing gerenciava conteúdo no admin do Shopify. Agora ele precisa de um CMS headless. Orçamente tempo para treinamento e construir uma experiência de edição de conteúdo que seja realmente agradável de usar. É aqui onde expertise em desenvolvimento de CMS headless realmente importa.

Quando Headless Não é a Escolha Certa

Vou ser direto com você: Shopify headless não é para todos. Não migre se:

  • Sua loja faz menos de $1M/ano e você não tem necessidades de customização complexas
  • Você não tem orçamento para desenvolvimento e manutenção contínuos
  • Seu time não tem desenvolvedores React (ou orçamento para contratar/fazer contrato com eles)
  • Você está feliz com a performance e funcionalidades do seu tema atual
  • Você está principalmente procurando por uma história "tech legal" em vez de resolver problemas de negócio reais

Online Store 2.0 do Shopify com um tema bem otimizado pode marcar 90+ no Lighthouse. Às vezes a resposta certa é otimizar o que você tem em vez de reconstruir do zero.

Se você está em dúvida, considere começar com uma abordagem híbrida: mantenha seu tema Shopify mas construa páginas específicas de alto impacto (como sua homepage ou landing pages) como headless. Você pode usar a Storefront API do Shopify ao lado do seu tema existente. Isso deixa você provar valor antes de se comprometer com uma migração completa.

FAQ

Quanto tempo leva para migrar do Shopify para headless?

Para uma loja de complexidade típica média, espere 12-20 semanas do kickoff ao launch. Lojas simples com menos produtos e funcionalidade básica podem enviar em 8-12 semanas. Lojas complexas multi-mercado com checkout customizado e integração extensa frequentemente levam 20-32 semanas. A fase de auditoria e planejamento sozinha deve ser 2-3 semanas — não pule isso.

Vou perder meus rankings de SEO quando migrar para Shopify headless?

Não, se você fazer corretamente. As chaves são: manter a mesma estrutura de URL (ou configurar redirects 301 apropriados), implementar dados estruturados em cada tipo de página, preservar meta tags e URLs canônicas, e enviar um sitemap atualizado para Google Search Console imediatamente após launch. Típicamente vejo uma flutuação de 1-2 semanas em rankings pós-migração, seguido por melhoria uma vez que Google reconheça os melhores scores de Core Web Vitals.

Preciso de Shopify Plus para headless?

Tecnicamente, não. A Storefront API está disponível em todos os planos Shopify. Porém, Shopify Plus te dá Checkout Extensibility (customizar a experiência de checkout), limites de API rate mais altos e acesso a hosting Oxygen. Para projetos headless sérios, Plus em $2.300/mês quase sempre vale a pena.

Qual é a diferença entre Hydrogen e usar Next.js com Shopify?

Hydrogen é o framework headless oficial do Shopify construído em Remix/React Router 7. Ele inclui componentes, hooks e utilitários específicos do Shopify fora da caixa, mais deployment otimizado em Oxygen. Next.js requer você construir a integração Shopify você mesmo mas te dá um ecossistema maior, mais opções de hosting e melhor suporte para arquiteturas de conteúdo complexas. A maioria de agências, incluindo a nossa, têm opiniões fortes aqui baseadas em requisitos específicos do projeto.

Posso migrar para Shopify headless com zero downtime?

Sim, usando uma blue-green deployment (switch DNS) ou uma migração gradual baseada em proxy. A abordagem blue-green troca todo o tráfego de uma vez via DNS, enquanto a abordagem proxy migra páginas incrementalmente em semanas. Ambas funcionam. A abordagem proxy é mais segura para lojas de alta receita mas adiciona complexidade.

Quanto custa uma migração Shopify headless?

Custos de agência típicamente variam de $40.000 para uma loja simples a $300.000+ para operações complexas multi-mercado. Taxas de freelancer são aproximadamente 50-60% dos custos de agência mas podem vir com menos estrutura de gerenciamento de projeto e menos especialistas. Custos contínuos incluem Shopify Plus ($2.300/mês), hosting ($20-500/mês), CMS ($0-500/mês) e manutenção (10-15% do custo inicial anualmente).

Devo usar Astro em vez de Next.js ou Hydrogen para Shopify headless?

Astro é uma ótima escolha para sites content-heavy com ilhas de interatividade, e construímos várias storefronts alimentados por Astro. Funciona bem para lojas estilo catálogo onde a maioria das páginas é estática e você só precisa React (ou Svelte, Vue) para componentes interativos como o carrinho. Porém, para lojas com interatividade heavy no lado do cliente — inventário em tempo real, filtragem complexa, busca instantânea — o runtime React completo de Next.js ou Hydrogen geralmente é melhor.

O que acontece com meus apps Shopify após migrar para headless?

A maioria dos apps Shopify que injetam código frontend (popups, widgets, exibições de review) não vão funcionar fora da caixa. Você vai precisar usar a API do app diretamente, encontrar uma alternativa compatível com headless, ou construir implementações customizadas. Apps que operam apenas no backend (gerenciamento de inventário, shipping, integrações ERP) típicamente continuam funcionando sem mudanças. Sempre audite sua stack de app durante a fase de planejamento.