gatsbyjs.com

Do que se trata o Gatsby?

Gatsby é um framework React para criar sites a partir de componentes e conteúdo estruturado. Ele pode coletar dados de arquivos, sistemas de gerenciamento de conteúdo, APIs e outros serviços; organizar esses dados por meio de uma camada GraphQL; e usá-los para criar páginas com renderização estática, adiada, no servidor ou no cliente.

Gatsby é o framework. gatsbyjs.com é seu site oficial e central de documentação. Essa distinção é importante porque a arquitetura, os pacotes e o repositório do framework são os temas deste guia, enquanto o domínio é onde o projeto publica sua documentação.

Um projeto Gatsby costuma reunir várias questões em um único fluxo de trabalho:

• Componentes React definem a interface e os elementos reutilizáveis das páginas.
• Plugins de origem importam conteúdo e dados de sistemas locais ou remotos.
• Gatsby normaliza os registros obtidos em nós na sua camada de dados.
• Consultas GraphQL selecionam os campos necessários para páginas e componentes.
• APIs de página e modelos transformam dados em rotas.
• Configurações de renderização determinam quando cada página é produzida.

Como Gatsby se relaciona com React

React fornece o modelo de componentes do Gatsby. Desenvolvedores compõem layouts, navegação, modelos e recursos interativos a partir de componentes React, enquanto Gatsby fornece o framework ao redor para roteamento, obtenção de dados, criação de páginas, processamento de recursos e saída de produção.

Portanto, Gatsby não é um substituto para React nem apenas uma biblioteca de componentes. É um framework opinativo para sites, desenvolvido em torno de React. As equipes podem aplicar JSX, composição de componentes, props, estado e interação no navegador já conhecidos, enquanto usam APIs específicas do Gatsby para dados e renderização.

O que Gatsby acrescenta ao React

Questão	O que React fornece	O que Gatsby acrescenta
Interface	Componentes e estado	Convenções de página, layouts e integração com o processo de build
Dados	Opções de busca de dados no nível da aplicação	Uma camada de dados normalizada e um fluxo de consultas GraphQL
Rotas	Blocos fundamentais para uma aplicação	Páginas baseadas em arquivos, criação programática de páginas e rotas somente no cliente
Saída	Interfaces renderizadas no navegador	Renderização de páginas estática, adiada e no momento da solicitação
Integrações	Um ecossistema JavaScript geral	Plugins, temas, starters e APIs do ciclo de vida do framework Gatsby

Essa estrutura pode ser adequada para uma equipe React que esteja criando um site público com muito conteúdo. Ela pode ser desnecessária quando um projeto pequeno tem pouca integração de conteúdo ou quando seus requisitos são principalmente os de uma aplicação renderizada no cliente.

A camada de dados e GraphQL

A camada de dados do Gatsby foi projetada para oferecer uma interface de consulta comum a diferentes fontes de conteúdo. Plugins de origem recuperam registros e criam nós Gatsby. Gatsby então disponibiliza esses nós por meio de um esquema GraphQL que páginas e componentes podem consultar.

Um site pode combinar arquivos Markdown, imagens, um sistema de conteúdo headless e dados selecionados de serviços. Em vez de fazer cada página compreender o formato de resposta original de cada fonte, Gatsby pode expor os registros relevantes por meio de um grafo compartilhado.

Um fluxo típico de conteúdo é assim:

1. Um arquivo, serviço ou plataforma de conteúdo armazena o material original.
2. Um plugin de origem importa esse material durante o processo de obtenção de dados do Gatsby.
3. Gatsby representa os registros importados como nós e cria um esquema.
4. Consultas GraphQL solicitam os campos exigidos por uma página ou componente.
5. Um modelo usa o resultado da consulta para produzir a página.
6. Gatsby renderiza a página de acordo com o modo de renderização selecionado.

GraphQL é central para o fluxo de dados obtidos do Gatsby, mas não substitui todos os valores comuns do React. Props de componentes, estado local, eventos do navegador e solicitações no lado do cliente ainda podem existir fora do grafo criado durante o build. A questão útil é saber se o esquema compartilhado do Gatsby simplifica o conteúdo que precisa ser reunido nas páginas.

A camada de dados também introduz trabalho. As equipes precisam compreender o comportamento das fontes, as relações entre nós, as alterações no esquema e as dependências das consultas. Um grafo que unifica vários sistemas pode ser valioso, mas seu custo de build e sua carga de manutenção devem ser testados com conteúdo representativo, e não inferidos a partir de um site starter.

Plugins de origem e o modelo mais amplo de extensões

Plugins de origem conectam Gatsby a dados. Eles podem ler arquivos locais ou integrar sistemas e serviços de conteúdo e, em seguida, criar nós que participam da camada GraphQL. Isso os diferencia de plugins que acrescentam processamento, análises, estilos, suporte a imagens ou outros comportamentos do ciclo de vida.

Gatsby organiza trabalho reutilizável em três formas relacionadas:

• Plugins adicionam uma fonte, transformação, integração ou capacidade do framework.
• Temas agrupam configurações e funcionalidades reutilizáveis do Gatsby que os sites podem estender.
• Starters fornecem um projeto inicial que os desenvolvedores copiam e adaptam.

Um starter pode reduzir o tempo de configuração, mas suas dependências e convenções passam a ser responsabilidade da equipe que o adota. Um tema pode manter a funcionalidade consistente entre sites, mas as equipes devem compreender o que ele controla. Um plugin pode evitar código de integração personalizado, embora sua compatibilidade e manutenção precisem ser avaliadas individualmente.

A existência de uma grande categoria de plugins não prova que um pacote específico seja compatível com a versão do Gatsby, a fonte de dados ou o modelo de implantação de uma equipe. Uma avaliação prática deve identificar os pacotes exatos necessários, examinar sua documentação e a atividade dos repositórios e testá-los dentro da arquitetura proposta.

Opções de renderização no Gatsby

Gatsby começou fortemente associado à geração de sites estáticos, mas sua documentação agora define várias opções de renderização. Elas podem ser selecionadas por página, permitindo que um artigo público, um arquivo extenso, uma rota dependente da solicitação e uma área da aplicação usem modelos de produção diferentes.

Opção de renderização	Quando a página é produzida	Pergunta adequada a fazer
Geração de Site Estático (SSG)	Durante o build	O conteúdo exigido pela página está disponível antes da implantação?
Geração Estática Adiada (DSG)	Quando uma página adiada é solicitada pela primeira vez	Esta página pode ser excluída do build inicial, e o provedor de hospedagem oferece suporte a Gatsby DSG?
Renderização no Lado do Servidor (SSR)	No momento da solicitação, usando getServerData	A resposta exige dados ou contexto disponíveis no momento da solicitação?
Rota no lado do cliente	No navegador, para um caminho da aplicação	Esta seção foi criada intencionalmente como aplicação, e o que está disponível antes de o JavaScript terminar?

Páginas estáticas e adiadas

SSG produz HTML e recursos relacionados durante o build. É uma opção natural para conteúdo cujas entradas são conhecidas antecipadamente. Arquivos gerados podem ser simples de distribuir, mas um grande número de páginas, consultas custosas, numerosas fontes de conteúdo ou processamento intenso de imagens podem aumentar as exigências do build.

DSG adia páginas selecionadas até a primeira solicitação. Isso pode reduzir o número de páginas criadas durante o build inicial, especialmente quando um site tem uma longa cauda de conteúdo solicitado com pouca frequência. Também exige um ambiente de implantação que implemente o comportamento de geração adiada do Gatsby; não equivale a enviar somente arquivos estáticos para qualquer provedor de hospedagem.

Renderização no momento da solicitação e no navegador

SSR gera uma resposta no momento da solicitação por meio da API getServerData do Gatsby. Ela pode fornecer páginas cuja saída depende de informações atuais da solicitação, mas introduz execução no servidor, decisões de cache, tratamento de falhas e requisitos de infraestrutura que uma página puramente estática evita.

Rotas no lado do cliente oferecem suporte a seções da aplicação tratadas no navegador. Elas podem coexistir com páginas públicas geradas, mas as equipes devem examinar estados de carregamento, navegação, acessibilidade e o conteúdo disponível antes da execução do código no lado do cliente. A descoberta pública não deve ser presumida apenas porque uma rota do navegador acaba exibindo as informações corretas.

Nenhum rótulo de renderização garante velocidade ou visibilidade nas buscas. Os resultados dependem do design da página, JavaScript, recursos, fontes de dados, cache, hospedagem e qualidade da implementação. Gatsby oferece às equipes várias opções de arquitetura; ele não elimina a necessidade de medi-las.

Imagens e produção de conteúdo

Imagens frequentemente fazem parte do mesmo pipeline de conteúdo que textos e registros estruturados. Plugins Gatsby podem obter arquivos de imagem, transformá-los e conectar os recursos processados às consultas das páginas. Os componentes podem então renderizar os dados de imagem selecionados como parte de um modelo de página.

Um fluxo editorial útil separa responsabilidades:

• Editores gerenciam títulos, corpo do conteúdo, metadados e referências de imagens na fonte escolhida.
• Plugins de origem importam esses registros e os recursos referenciados.
• A camada de dados do Gatsby conecta nós de conteúdo aos dados de imagem necessários.
• Consultas solicitam apenas os campos e as variantes de imagem necessários para um modelo.
• Componentes fornecem legendas, textos alternativos, dimensões e comportamento de layout.
• O build de produção verifica se registros, recursos e rotas são resolvidos em conjunto.

O processamento de imagens pode melhorar a consistência, mas ainda representa trabalho de build. As equipes devem testar a quantidade e o tamanho reais dos recursos, confirmar como as alterações afetam novos builds e preservar textos alternativos significativos vindos da fonte editorial. Um plugin não pode decidir se uma imagem é informativa, decorativa ou descrita adequadamente.

Onde Gatsby pode se encaixar bem

Gatsby é particularmente relevante quando um projeto já usa React e precisa reunir conteúdo de vários sistemas. Seu grafo de dados pode fornecer uma camada consistente entre essas fontes e os modelos de página que as consomem.

Situações comuns que vale a pena avaliar incluem:

• Sites de documentação ou editoriais que combinam arquivos, imagens e uma plataforma de conteúdo.
• Sites de marketing com componentes React reutilizáveis e registros de página estruturados.
• Projetos de publicação com múltiplas fontes que se beneficiam de uma única interface de consulta.
• Sites Gatsby existentes criados em torno de APIs de página, GraphQL e plugins consolidados.
• Grandes coleções de conteúdo nas quais páginas selecionadas podem ser candidatas a DSG.
• Sites que combinam páginas públicas geradas com seções no momento da solicitação ou no lado do cliente.

Gatsby pode ser uma opção menos direta quando um projeto tem uma única fonte de conteúdo simples, não se beneficia de um grafo normalizado ou precisa de uma arquitetura de aplicação centrada principalmente em operações no momento da solicitação e no lado do cliente. Esse é um julgamento de arquitetura, não um veredito sobre a qualidade do framework.

Compensações de build e implantação

A geração estática transfere trabalho para antes da implantação. Gatsby pode precisar recuperar dados das fontes, construir seu esquema, executar consultas, criar páginas, processar imagens, empacotar código e gravar a saída. A duração e os requisitos de recursos dependem do projeto real.

Uma avaliação representativa deve registrar:

Área de teste	O que verificar
Escala do conteúdo	Número de páginas, número de nós, relações e tamanhos realistas dos registros
Confiabilidade das fontes	Autenticação, limites de requisições, falhas e recuperação repetível
Consultas	Estabilidade do esquema, custo das consultas e erros após alterações no conteúdo
Imagens	Volume de processamento, uso de memória, tamanho da saída e metadados editoriais
Renderização	Saída SSG, primeiras solicitações DSG, respostas SSR e carregamento de rotas no cliente
Implantação	Suporte a todos os modos escolhidos, comportamento do cache e recuperação de falhas

Uma pequena demonstração não pode determinar como um catálogo completo se comportará. As equipes devem testar builds limpos, alterações incrementais quando houver suporte, indisponibilidade das fontes de conteúdo e páginas tanto nas partes comuns quanto nas extremas do conjunto de dados.

DSG pode transferir trabalho para depois do build inicial, enquanto SSR transfere trabalho para as solicitações. Essas são mudanças no momento de execução e na responsabilidade operacional, não melhorias gratuitas de desempenho. O provedor escolhido deve oferecer suporte ao comportamento exigido pelo Gatsby, e a equipe deve compreender o que acontece durante uma solicitação a frio ou uma falha em um serviço upstream.

Gatsby, Astro e outras alternativas

Gatsby e Astro podem aparecer em avaliações de sites orientados a conteúdo, mas organizam os projetos de maneiras diferentes. Gatsby coloca React, sua camada de dados GraphQL, plugins de origem e APIs de geração de páginas no centro. Astro deve ser avaliado segundo sua própria arquitetura documentada, em vez de ser tratado automaticamente como uma resposta mais rápida ou mais recente.

Gatsby merece consideração mais atenta quando uma equipe quer React em toda a interface, precisa consultar várias fontes de conteúdo normalizadas, depende de integrações Gatsby ou mantém uma base de código Gatsby consolidada. Outro framework pode ser mais simples quando esse grafo e o ciclo de vida de plugins acrescentariam estrutura sem resolver um problema real de conteúdo.

Uma comparação útil cria o mesmo recorte representativo em cada candidato: uma fonte de conteúdo, uma página complexa, uma listagem, tratamento de imagens, navegação e o modo de implantação pretendido. Compare a compreensão dos desenvolvedores, o comportamento do build, a saída no navegador, a acessibilidade, os requisitos de hospedagem e a responsabilidade pela manutenção. Evite declarar um vencedor universal com base em modelos padrão.

Fundador e recursos oficiais da comunidade

Em uma sessão oficial de perguntas e respostas da comunidade Gatsby publicada em 2 de abril de 2020, Kyle Mathews foi identificado como “Fundador @ GatsbyJS”. Essa atribuição datada descreve seu papel histórico naquela fonte; ela não deve ser interpretada como uma afirmação sobre a liderança atual do Gatsby.

A documentação do Gatsby direciona desenvolvedores a canais oficiais da comunidade para diferentes necessidades:

• Discord é indicado como um lugar para pedir ajuda de desenvolvimento à comunidade.
• GitHub Discussions oferece suporte a discussões sobre o projeto e seus recursos.
• A documentação de contribuição explica maneiras de participar do projeto.
• O repositório gatsbyjs/gatsby, que continua sendo mantido, contém o código-fonte do framework, pacotes, issues e histórico de contribuições.

Esses recursos ajudam os leitores a verificar a documentação, fazer perguntas de implementação e examinar o trabalho público do projeto. Sua existência não deve ser convertida em afirmações sem respaldo sobre tempos de resposta, longevidade dos pacotes ou planos futuros.

O que as equipes devem decidir antes de adotar Gatsby

1. Mapeie o conteúdo. Identifique cada fonte, as relações entre registros, a frequência de atualização e quais páginas consomem cada campo. Isso revela se a camada GraphQL normalizada do Gatsby resolve um problema significativo de coordenação.

2. Atribua um modo de renderização às páginas representativas. Confirme quais páginas podem ser estáticas, quais podem ser adiadas, quais exigem getServerData e quais são deliberadamente executadas no lado do cliente. Verifique se o destino de implantação oferece suporte à combinação resultante.

3. Audite o conjunto concreto de dependências. Verifique os plugins de origem, plugins de transformação, temas, starters e ferramentas de imagem necessários em relação à versão do Gatsby usada pelo projeto. Crie protótipos de integrações incertas antes de transformá-las em dependências da arquitetura.

4. Teste uma carga de trabalho semelhante à de produção. Gatsby oferece um framework coerente para React e conteúdo, mas sua adequação vem do alinhamento com os dados, páginas, integrações e modelo de hospedagem da equipe, não de promessas amplas sobre velocidade, posicionamento nas buscas ou escalabilidade sem esforço.