Migrar Gatsby para Next.js

Por Que Sites Gatsby Estão Migrando para Next.js

Gatsby foi uma escolha sólida quando a geração estática de sites era a única opção real. Mas a web evoluiu, e Gatsby não acompanhou. Seu site está preso à renderização somente em tempo de build, emaranhado em uma camada de dados GraphQL que você provavelmente não precisava, e sofrendo com tempos de build que pioram conforme seu conteúdo cresce.

Next.js oferece tudo que Gatsby faz — geração estática, componentes React, roteamento baseado em arquivos — mais renderização no servidor, regeneração estática incremental, rotas de API e middleware. Mesmo ecossistema React, sem as limitações.

Como ambos os frameworks são baseados em React, seus componentes reais mal mudam. A migração é principalmente sobre padrões de busca de dados e roteamento. Você não está reescrevendo sua UI.

Os Verdadeiros Problemas com Gatsby

GraphQL para Tudo É Overkill

Gatsby roteia todas as interações de dados através de GraphQL. Quer puxar uma lista de posts de blog do seu CMS? Query GraphQL. Precisa de metadados do site? Query GraphQL. Quer ler um arquivo JSON? Query GraphQL. Isso era inteligente em 2018. Agora é apenas fricção.

Você está mantendo arquivos gatsby-node.js com lógica createPages, escrevendo page queries, static queries e definições de fragment para o que deveria ser uma simples chamada fetch(). Todo novo desenvolvedor no seu time tem que aprender as convenções GraphQL do Gatsby antes de contribuir com algo significativo.

Tempos de Build que Escalam Mal

Gatsby reconstrói tudo em tempo de build. Um site com 500 páginas pode levar 5-10 minutos. Um site com 5.000 páginas? Você está olhando para 20-45 minutos. Cada atualização de conteúdo dispara um rebuild completo. Seu time de marketing espera meia hora para ver um post de blog ao vivo.

Next.js com Regeneração Estática Incremental (ISR) resolve isso completamente. Páginas se regeneram em background em um cronograma que você define. Novo conteúdo aparece em segundos, não minutos.

Inferno de Dependências de Plugins

O ecossistema de plugins do Gatsby foi uma vez seu maior trunfo. Agora é uma responsabilidade. Plugins quebram em atualizações de versão major. Alguns são abandonados. Você está três camadas de profundidade em dependências gatsby-plugin-* para alcançar o que Next.js entrega nativamente — otimização de imagens, manipulação CSS, carregamento de fontes, gerenciamento de metadados.

Quando gatsby-plugin-image quebra após uma atualização e você está debugando source maps às 23h, esse é geralmente o momento em que times decidem que é hora de migrar.

Sem Renderização no Servidor

Gatsby é apenas estático. Precisa de páginas autenticadas? Renderização no cliente com spinners de carregamento. Precisa de dados em tempo real? Busca no cliente após hidratação. Precisa de personalização? Workarounds pesados em JavaScript que destruem suas Core Web Vitals.

Next.js permite que você escolha por página: geração estática, renderização no servidor, ou um híbrido com ISR. Você escolhe a ferramenta certa para cada rota.

O Que Você Ganha com Next.js

Estratégias Flexíveis de Renderização

Cada página em Next.js pode usar uma estratégia de renderização diferente. Páginas de marketing usam getStaticProps para geração estática. Seu dashboard usa renderização no servidor. Seu blog usa ISR para se manter fresco sem rebuilds. Um framework, todos os padrões.

Busca de Dados Sem GraphQL

Substituir cada query GraphQL por fetch() padrão, SWR ou qualquer biblioteca de dados que você preferir. getStaticProps substitui page queries. getStaticPaths substitui createPages em gatsby-node.js. O modelo mental é mais simples e o código é mais portável.

// Antes: gatsby-node.js
exports.createPages = async ({ graphql, actions }) => {
  const result = await graphql(`
    query { allMarkdownRemark { edges { node { frontmatter { slug } } } } }
  `);
  result.data.allMarkdownRemark.edges.forEach(({ node }) => {
    actions.createPage({
      path: node.frontmatter.slug,
      component: path.resolve('./src/templates/post.js'),
    });
  });
};

// Depois: pages/posts/[slug].tsx
export const getStaticPaths: GetStaticPaths = async () => {
  const posts = await getAllPosts();
  return {
    paths: posts.map((post) => ({ params: { slug: post.slug } })),
    fallback: 'blocking',
  };
};

export const getStaticProps: GetStaticProps = async ({ params }) => {
  const post = await getPostBySlug(params.slug);
  return { props: { post }, revalidate: 60 };
};

A versão Next.js é mais explícita, mais fácil de debugar e adiciona ISR com uma única propriedade revalidate.

Otimização de Imagens Integrada

O componente <Image> do Next.js cuida de lazy loading, dimensionamento responsivo e conversão de formato (WebP/AVIF) sem plugins. Não mais lutar com configurações de gatsby-plugin-image e gatsby-transformer-sharp.

Rotas de API e Middleware

Precisa de um endpoint de formulário de contato? Um manipulador de webhook? Lógica de autenticação? As rotas de API do Next.js vivem no mesmo codebase. Middleware cuida de redirects, testes A/B e geolocalização na edge. Gatsby não tem equivalente.

Nosso Processo de Migração

Fase 1: Auditoria e Arquitetura (Semana 1)

Inventariamos cada página Gatsby, plugin, query GraphQL e rota dinâmica. Cada uma é mapeada para seu equivalente Next.js. Identificamos plugins que precisam de substituição customizada e documentamos sua estrutura de URL atual para preservação de SEO.

Fase 2: Scaffolding do Projeto (Semana 1-2)

Inicializamos o projeto Next.js com TypeScript, configuramos sua conexão com headless CMS e montamos sua solução de styling — migrando seu CSS existente seja styled-components, Tailwind ou CSS Modules. Depois estabelecemos a arquitetura de componentes.

Ambos os frameworks usam React, então seus componentes existentes transferem com mudanças mínimas. Atualizamos imports, substituímos gatsby-link por next/link, trocamos gatsby-image por next/image e movemos CSS global de gatsby-browser.js para _app.tsx.

Fase 3: Migração de Busca de Dados (Semana 2-3)

Este é o trabalho central. Cada query GraphQL se torna uma chamada de API direta ou método de SDK do CMS dentro de getStaticProps ou getServerSideProps. Cada chamada createPages em gatsby-node.js se torna uma função getStaticPaths. Substituímos gatsby-plugin-react-helmet pela componente <Head> nativa do Next.js ou pela API de metadados do App Router.

Fase 4: Recursos Dinâmicos (Semana 3-4)

Aqui é onde Next.js se destaca. Adicionamos ISR a páginas de conteúdo para que atualizações do CMS apareçam em segundos. Implementamos rotas de API para formulários e integrações. Adicionamos middleware para redirects, auth ou personalização — recursos que eram impossíveis ou dolorosamente hacky em Gatsby.

Fase 5: Testes e Launch (Semana 4-5)

Teste de regressão completo em dispositivos. Auditorias Lighthouse em cada template. Testes de diff visual contra seu site atual. Verificamos que cada URL se resolve corretamente, cada redirect funciona e cada meta tag é preservada.

Estratégia de Preservação de SEO

Migrar frameworks é um risco de SEO se você não for cuidadoso. Eliminamos esse risco.

• Paridade de URL: Cada URL existente mapeia 1:1 para o novo site. Sem mudanças de estrutura a menos que você solicite.
• Redirects 301: Configuramos redirects do Next.js em next.config.js para qualquer mudança de URL, com um mapa completo de redirects.
• Auditoria de meta tags: Verificamos que title tags, meta descriptions, tags Open Graph e URLs canônicas transferem corretamente usando a componente <Head> do Next.js.
• Dados estruturados: Qualquer markup JSON-LD do seu site Gatsby é portado para os novos templates.
• Sitemap e robots.txt: Gerados automaticamente via next-sitemap ou rotas de API customizadas.
• Ganhos de performance: Pontuações TTFB mais rápidas e melhores Core Web Vitals geralmente melhoram rankings pós-migração, não prejudicam.

Deploy e Hosting

Fazemos deploy em Vercel para a melhor experiência Next.js — deployments de preview automáticos, edge functions, analytics integrado e ISR zero-config. Alternativamente, podemos fazer deploy em Cloudflare Pages, AWS Amplify ou qualquer ambiente de hosting Node.js que se ajuste à sua infraestrutura.

Timeline e Preços

Uma migração típica de Gatsby para Next.js leva 3-5 semanas dependendo da complexidade do site:

• Sites pequenos (menos de 50 páginas, blog ou site de marketing): 2-3 semanas, começando em $6.000
• Sites médios (50-500 páginas, CMS-driven, múltiplos templates): 3-5 semanas, começando em $12.000
• Sites grandes (500+ páginas, fontes de dados complexas, e-commerce): 5-8 semanas, começando em $20.000

Cada migração inclui um período de suporte pós-launch gratuito para capturar edge cases e ajustar performance.

A Vantagem React

Isso não é uma reescrita — é uma atualização. Seu time já conhece React. Seus componentes já funcionam. Estamos trocando a camada de framework por baixo enquanto mantemos tudo que importa: seu design, seu conteúdo, suas URLs e seus rankings de busca.

O resultado é um site que é mais rápido, mais flexível e capaz de coisas que Gatsby simplesmente não consegue entregar.