Gatsby et JavaScript pour le SEO : API Head, prérendu et choix de migrer

Gatsby se référence bien parce qu'il génère au build une page HTML complète pour chaque URLUniform Resource Locator. Adresse unique d'une page web. Une URL optimisée est courte, descriptive et contient le mot-clé. : texte, liens et balises sont là avant toute exécution de JavaScriptLangage de programmation web. Son mauvais usage peut bloquer l'indexation par les moteurs de recherche.. Le SEOSearch Engine Optimization. Ensemble des techniques visant à améliorer le positionnement d'un site web dans les résultats naturels des moteurs de recherche. d'un site Gatsby se joue donc ailleurs : des balises gérées par l'API Head, les pages qui échappent au prAlgorithme historique de Google évaluant l'importance d'une page selon ses backlinks. Toujours utilisé en interne.érendu, et un framework que Netlify, son propriétaire depuis 2023, maintient au minimum.

Ce guide s'adresse aux équipes qui ont un site Gatsby en production. Les exemples de code suivent la documentation officielle de Gatsby 5, vérifiée le 13 octobre 2026, et remplacent les recettes react-helmet de la première version de cet article.

Pourquoi un site Gatsby part-il avec un avantage SEO ?

Par défaut, Gatsby prérend chaque page en HTML, CSS et JavaScript au moment du build, puis sert ces fichiers statiques. C'est la génération statique (SSG), que sa documentation présente comme son mode de rendu par défaut. Le robot reçoit une page déjà écrite. Le JavaScript qui arrive ensuite l'hydrate, c'est-à-dire qu'il y attache l'interactivité.

Pour Google, le contenu ne dépend plus de la file de rendu. Google exécute bien le JavaScript, mais il recommande toujours le rendu côté serveur ou le prérendu, plus rapides, et rappelle que tous les robots n'utilisent pas forcément JavaScript.

Avec les assistants, l'écart se creuse. Dans l'étude publiée par Vercel et MERJ en décembre 2024, aucun des grands robots d'IA mesurés ne rendait le JavaScript, à part Gemini, qui s'appuie sur l'infrastructure de Googlebot, et AppleBot. Ce que le fonctionnement de Google face au JavaScript impose à une application React, Gatsby le règle au build.

L'avantage a trois limites, toutes visibles dans la documentation :

• Les routes client-only ne correspondent à aucun fichier indexProcessus par lequel Google ajoute une page à sa base de données pour qu'elle puisse apparaître dans les résultats..html dans le dossier public. Un espace client ou un tableau de bord s'y prête bien. Une page qui doit ranker, jamais.
• Le contenu chargé dans le navigateur après le build (avis, prix, stock appelés en fetch depuis un composant) n'est pas dans le HTML servi. Google le verra peut-être au rendu, les robots d'IA qui n'exécutent pas le JavaScript non.
• Les deux autres modes ajoutés par Gatsby 4 changent l'hébergement. La génération différée (DSG) construit une page à sa première demande, et le rendu serveur (SSRTechnique générant le HTML sur le serveur, facilitant l'indexation du contenu JavaScript.) l'appelle à chaque requêteTerme ou expression que les utilisateurs saisissent dans un moteur de recherche. Base de toute stratégie SEO. via getServerData. Les deux exigent un serveur qui tourne après le build.

Pour une page dont les données bougent tous les jours, le choix entre ces modes suit la même grille que sur n'importe quel framework : le rendu côté serveur et ses compromis (temps de réponse, cache) se comparent au prérendu page par page.

Où en est Gatsby en octobre 2026 ?

Gatsby reste maintenu, en version 5.16.1 du 10 février 2026, avec un développement volontairement limité, annoncé par ses mainteneurs chez Netlify. Le contexte compte pour décider de rester dessus.

Netlify a annoncé le rachat de Gatsby Inc. le 1er février 2023, en promettant que le framework resterait open source. Le 24 août 2023, il a notifié aux clients de Gatsby Cloud une date de fin de service, en précisant que la décision n'affectait pas le framework, utilisé alors par plus de 20 % de ses clients Enterprise.

En novembre 2023, Matt Biilmann, le directeur général de Netlify, écrivait sur le dépôt que Gatsby restait et serait maintenu, tout en prévenant que Gatsby ne serait pas le premier à adopter les nouveaux paradigmes de rendu.

Un an plus tard, en novembre 2024, un mainteneur décrivait le rythme réel : correctifs de sécurité, mises à jour de dépendances limitées, corrections de bugs simples, et adaptation aux API tierces qui disparaissent. C'est ce qui s'observe dans les versions publiées :

Le framework n'est donc pas abandonné, et il ne bouge plus beaucoup. Pour un nouveau projet React, l'équipe React recommande aujourd'hui Next.js (App Router), React Router ou Expo ; Gatsby n'apparaît pas sur sa page de démarrage. La dernière section revient sur la décision de rester ou de partir.

Title, meta et canonical : l'API Head à la place de react-helmet

Sur Gatsby 4.19 et plus, chaque page ou template exporte une fonction Head qui renvoie ses balises ; Gatsby les écrit dans le HTML statique au build. React Helmet, que la première version de cet article enseignait, n'a plus publié de version depuis la 6.1.0 du 8 juin 2020, et le plugin gatsby-plugin-react-helmet annonce lui-même sa dépréciation au profit de Head.

Raison de plus pour migrer : depuis Gatsby 5.16, React 19 est pris en charge, mais la remontée native des balises <title> et <meta> de React 19 y est désactivée, parce qu'elle entre en conflit avec l'API Head. Le conseil du guide React SEO, qui écrit ces balises directement dans les composants, vaut pour React seul. Sur Gatsby, tout passe par Head.

La documentation recommande un composant SEO commun, alimenté par siteMetadata dans gatsby-config.js. La version ci-dessous reprend celui de la doc, allégé des balises Twitter, de la meta image et de l'icône, avec l'attribut lang et une canonical en plus. Pour l'aperçu des partages, le même composant peut porter les balises Open Graph à poser dans le head, avec og:url calculé comme la canonical. Le hook useSiteMetadata reprend celui de la doc, réduit aux trois champs utilisés, qui doivent tous figurer dans le siteMetadata de gatsby-config.js :

// src/hooks/use-site-metadata.jsx
import { graphql, useStaticQuery } from "gatsby"

export const useSiteMetadata = () => {
  const data = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          title
          description
          siteUrl
        }
      }
    }
  `)

  return data.site.siteMetadata
}

Le composant lui-même :

// src/components/seo.jsx
import React from "react"
import { useSiteMetadata } from "../hooks/use-site-metadata"

export const SEO = ({ title, description, pathname, children }) => {
  const { title: defaultTitle, description: defaultDescription, siteUrl } = useSiteMetadata()

  const seo = {
    title: title || defaultTitle,
    description: description || defaultDescription,
    url: `${siteUrl}${pathname || ``}`,
  }

  return (
    <>
      <html lang="fr" />
      <title>{seo.title}</title>
      <meta name="description" content={seo.description} />
      <link rel="canonical" href={seo.url} />
      {children}
    </>
  )
}

Chaque page ou template l'appelle dans son export Head, qui reçoit location, params, data (la requête GraphQL de la page) et pageContext :

// src/templates/article.jsx
export const Head = ({ location, data }) => (
  <SEO
    title={data.page.title}
    description={data.page.description}
    pathname={location.pathname}
  />
)

Quatre règles de la documentation évitent les mauvaises surprises :

1. Head ne s'exporte que depuis une page ou un template passé à createPage, jamais depuis un composant. Le composant SEO est appelé par Head, il ne l'exporte pas.
2. Les balises acceptées sont link, meta, style, title, base, script et noscript. L'attribut lang de <html> se règle dans Head depuis Gatsby 5.5.
3. Pour éviter un doublon, par exemple une icône globale et une icône propre à la page, donnez le même id aux deux balises : seule la dernière part dans le HTML.
4. Le contenu de Head est vidé quand la page se démonte : chaque page déclare tout ce dont elle a besoin.

La migration depuis react-helmet tient en trois gestes : remplacer chaque <Helmet> par un export Head dans la page concernée, retirer gatsby-plugin-react-helmet de gatsby-config.js puis désinstaller gatsby-plugin-react-helmet et react-helmet, et contrôler le HTML de trois gabarits avec les commandes de la section audit. Un site multilingue déclare au même endroit ses balises <link rel="alternate" hreflangAttribut HTML indiquant la langue et la région ciblée d'une page pour le SEO international.>, une par version ; les règles de réciprocité sont dans notre guide du hreflang.

Données structurées en JSON-LD

Le JSON-LDFormat recommandé par Google pour implémenter les données structurées dans le code source. se place dans Head, comme les autres balises : la documentation de Gatsby l'autorise pour les scripts de données, et conseille le composant Script pour les scripts qui s'exécutent. Le plus simple est de le passer en enfant du composant SEO, rempli avec les données de la page :

export const Head = ({ location, data }) => (
  <SEO
    title={data.page.title}
    description={data.page.description}
    pathname={location.pathname}
  >
    <script type="application/ld+json">
      {JSON.stringify({
        "@context": "httpsProtocole sécurisé de transfert de données. Facteur de ranking depuis 2014.://schema.orgVocabulaire standardisé de balisage structuré reconnu par Google, Bing et Yahoo.",
        "@type": "Article",
        headline: data.page.title,
        datePublished: data.page.date,
      }).replace(/</g, "\\u003c")}
    </script>
  </SEO>
)

Le replace protège la page : JSON.stringify ne filtre pas les chaînes malveillantes, et un titre qui contiendrait </script> fermerait le bloc et ouvrirait une faille XSS. Remplacer < par son équivalent unicode règle le problème, comme dans notre guide Next.js. Comme le reste de Head, ce bloc part dans le HTML statique : Google le lit dès l'explorationProcessus par lequel les robots des moteurs de recherche parcourent et analysent les pages web., sans dépendre de la file de rendu. Testez chaque gabarit avec le test des résultats enrichis de Google, que la documentation de Gatsby recommande en développement, puis suivez les rapports d'état des résultats enrichis de la Search ConsoleOutil gratuit Google pour surveiller et optimiser la présence d'un site dans les résultats de recherche. après la mise en ligne.

Sitemap, robots.txt, canonical et barre oblique finale

Ces quatre réglages se font ensemble, sur une seule forme d'URL : celle de siteUrl, avec ou sans barre oblique finale selon l'option trailingSlash.

Le sitemapFichier XML listant toutes les URLs d'un site pour faciliter leur découverte par les moteurs de recherche.. gatsby-plugin-sitemap lit siteMetadata.siteUrl et génère sitemap-index.xml à la racine, plus un fichier sitemap-0.xml par tranche de 45 000 URL. Il ne produit rien en mode développement : testez avec gatsby build &ampAccelerated Mobile Pages. Framework Google pour créer des pages mobiles ultra-rapides (moins utilisé aujourd'hui).;& gatsby serve.

Sa sortie par défaut donne la même priority et la même changefreq à toutes les pages ; Google ignore ces deux valeurs. Il utilise en revanche lastmod si elle est cohérente et vérifiable : elle doit refléter la dernière mise à jour importante de la page. L'option excludes retire les pages sans intérêt. Le lastmod demande trois réglages, comme dans l'exemple du README : une query personnalisée qui récupère la date de chaque page, resolvePages qui la joint aux pages, puis serialize qui l'écrit dans l'entrée du sitemap. Le reste des règles d'un bon fichier est dans notre guide du sitemap XML.

// gatsby-config.js
module.exports = {
  siteMetadata: {
    title: `Ma Boutique`,
    description: `Chaises et tables en chêne massif`,
    siteUrl: `https://www.example.com`,
  },
  plugins: [`gatsby-plugin-sitemap`],
}

Le robots.txtFichier texte à la racine d'un site indiquant aux robots quelles pages explorer ou ignorer.. Le plus simple est un fichier robots.txt dans le dossier static/, que Gatsby copie tel quel dans public/. Le plugin gatsby-plugin-robots-txt qu'on trouve dans les tutoriels est communautaire, et sa dernière version date du 13 novembre 2022. Les directives à y mettre ne changent pas avec Gatsby : elles sont détaillées dans notre guide du robots.txt en SEO.

User-agent: *
Disallow:

Sitemap: https://www.example.com/sitemap-index.xml

La canonical. Deux voies, jamais les deux à la fois. La balise du composant SEO, montrée plus haut, se règle page par page. Le plugin gatsby-plugin-canonical-urls ajoute à chaque page une canonical construite avec sa propre option siteUrl et le chemin de la page. Il sert surtout à fixer le protocole et le www, et son option stripQueryString retire les paramètres d'URL.

Cumuler les deux produit deux canonicals dans le même head, qui se contredisent dès que leurs URL divergent (paramètres, barre oblique, www). Le choix de l'URL canoniqueBalise indiquant la version principale d'une page en cas de contenu dupliqué ou similaire. elle-même suit les règles de notre guide de la balise canonical.

La barre oblique finale. L'option trailingSlash de gatsby-config.js existe depuis Gatsby 4.7. Depuis Gatsby 5, elle vaut always par défaut : /contact devient /contact/. En Gatsby 4, le défaut legacy laisse les URL telles qu'elles ont été créées. Le guide de migration vers la version 5 conseille de fixer l'option explicitement. L'hébergeur doit rediriger l'autre forme, la documentation renvoie pour cela à la RFC de l'option. Liens internesEnsemble des liens entre les pages d'un même site. Distribue le jus SEO et guide les utilisateurs., canonical et sitemap doivent tous écrire la forme retenue, sinon chaque lien coûte une redirection. Sur gatsbyjs.com, testé le 13 octobre 2026, la canonical de la page des plugins pointe vers /plugins, qui répond par une 301Redirection permanente transférant le jus SEO de l'ancienne URL vers la nouvelle. vers /plugins/ : le décalage exact à éviter.

Liens, images et vitesse

Le composant Link de Gatsby produit de vrais liens <a href>, que Google suit. Il précharge en plus les ressources de la page liée dès que le lien entre dans l'écran, puis en priorité haute au survol. Sur gatsbyjs.com, testé le 13 octobre 2026, la page des plugins sert 84 liens internes relatifs en <a href> dans son HTML brut. Réservez Link aux pages du site et gardez <a> pour les liens externes, comme le demande la documentation.

Pour les images, gatsby-image, cité par les vieux tutoriels, est déprécié depuis août 2021 : il est remplacé par gatsby-plugin-image et ses deux composants, StaticImage pour une image fixe (logo, visuel d'accueil) et GatsbyImage pour une image qui vient des données (CMS, Markdown).

import { StaticImage } from "gatsby-plugin-image"

export function Hero() {
  return (
    <StaticImage
      src="../images/hero.jpg"
      alt="Atelier de fabrication des chaises en chêne"
      loading="eager"
    />
  )
}

Trois réglages comptent pour le SEO. L'attribut alt est obligatoire dans les deux composants. Les images sont chargées en différé par défaut, et la documentation conseille loading="eager" pour celles du premier écran, afin qu'elles commencent à charger avant l'hydratation. Si cette image est le plus grand élément visible au chargement, c'est elle qui fixe le LCPLargest Contentful Paint. Mesure le temps de chargement du plus grand élément visible. Idéalement < 2,5 secondes.. Le plugin génère enfin le format d'origine et une version WebP sans réglage ; l'AVIF s'ajoute par l'option formats. Le plugin WebP séparé des tutoriels de 2023 n'a plus lieu d'être.

Dernier ménage : gatsby-plugin-google-analytics affiche un avis de dépréciation et renvoie vers gatsby-plugin-google-gtag.

Auditer un site Gatsby en quelques commandes

Trois lectures du HTML brut suffisent pour savoir comment un site Gatsby gère ses balises et ce que voient les robots. Les commandes ci-dessous ont été lancées le 13 octobre 2026 sur deux vrais sites Gatsby : gatsbyjs.com et typescriptlang.org.

curl -sL https://www.example.com/page/ -o page.html -w "%{http_code}\n"
grep -o '<meta name="generator"[^>]*>' page.html
echo "Head : $(grep -o 'data-gatsby-head' page.html | wc -l) / Helmet : $(grep -o 'data-react-helmet' page.html | wc -l)"
grep -o '<title[^>]*>[^<]*</title>' page.html | head -1
grep -o '<link[^>]*rel="canonical"[^>]*>' page.html
grep -o '<meta[^>]*name="description"[^>]*>' page.html

La première ligne enregistre la page et affiche le code HTTP. La deuxième lit la balise generator, que Gatsby ajoute par défaut avec son numéro de version ; si elle manque, le site a pu la retirer. La troisième compte les balises posées par l'API Head, que Gatsby marque data-gatsby-head, et celles posées par React Helmet, marquées data-react-helmet. Les trois dernières affichent title, canonical et meta descriptionBalise HTML décrivant le contenu d'une page. Affichée sous le titre dans les SERP, elle influence le CTR. telles que le robot les reçoit.

Ce que donnent les deux sites :

• La page gatsbyjs.com/plugins/ répond 200, annonce Gatsby 4.24.6 et porte 18 balises data-gatsby-head contre 0 data-react-helmet : le site est passé à l'API Head. Sa canonical ne porte pas le marqueur : ses attributs data-baseprotocol et data-basehost signent le plugin gatsby-plugin-canonical-urls. Elle pointe vers /plugins, qui redirige en 301 vers /plugins/.
• Le site typescriptlang.org, sur une page du manuel, répond 200 et annonce Gatsby 5.16.1, la dernière version, avec 8 balises data-react-helmet et aucune data-gatsby-head : la mise à jour du framework n'a pas emporté la migration des balises. Title et description sont bien dans le HTML servi, mais la commande ne trouve aucune canonical.

Deux cas faussent la lecture.

Un code 403 avec un title « Just a moment... » et une meta robots noindexDirective indiquant aux moteurs de ne pas indexer une page.,nofollowAttribut indiquant aux moteurs de ne pas suivre un lien ou de ne pas transmettre de jus SEO. signale une page de défi du pare-feu : c'est elle que la commande a lue, à la place de la page. Passez alors par l'inspection d'URL de la Search Console, qui montre le HTML que GooglebotRobot d'exploration de Google qui parcourt le web pour découvrir et indexer les pages. a reçu.

La page peut aussi contenir d'autres balises <title>, celles des icônes SVG (gatsbyjs.com en a deux, « Gatsby Github » et « Gatsby Youtube ») : la commande garde la première, en principe celle du head. Si le head n'a pas de title, c'est celui d'une icône qui s'affiche.

Lancez ces commandes sur trois gabarits au moins (accueil, liste, détail), puis sur une URL de route client-only si le site en a : elle ne doit pas être une page qui doit ranker.

Rester sur Gatsby ou migrer

Un site Gatsby en ligne, à jour en 5.16 et passé à l'API Head, n'a pas de raison SEO de migrer : son HTML prérendu reste ce que Google et les robots d'IA lisent le mieux. La question devient technique et budgétaire.

Restez si le site est surtout éditorial et prérendu, si l'équipe le maîtrise, et si ses plugins viennent du dépôt officiel, que l'équipe Gatsby a tous mis à jour pour React 19.

Préparez une migration si le site dépend de plugins communautaires qui ne suivent plus, s'il a besoin des Server Components ou des nouveautés de rendu que Gatsby n'adoptera pas en premier, ou si un nouveau chantier de fond se profile. Pour un projet neuf, partez sur un framework que l'équipe React recommande ; notre guide Next.js SEO détaille l'équivalent de chaque réglage de cet article (API Metadata, sitemap.ts, robots.ts).

Une migration de framework change le HTML de toutes les pages en même temps : c'est une refonteModification majeure du design ou de la structure d'un site. Risque SEO si mal gérée. au sens SEO. Elle se prépare avec un inventaire des URL, le HTML brut de chaque gabarit enregistré avant la bascule, et une recette en préproduction, comme le décrit notre méthode pour conserver son trafic pendant une refonte.

Slashr intervient aux côtés de l'équipe de développement dans le cadre d'un accompagnement SEO de refonte et de migration, et l'audit du HTML servi d'un site JavaScript fait partie de notre accompagnement SEO technique.

Questions fréquentes

Sources

• Rendering Options : gatsbyjs.com/docs/conceptual/rendering-options/
• Client-only Routes & User Authentication : gatsbyjs.com/docs/how-to/routing/client-only-routes-and-user-authentication/
• Comprendre les bases du SEO JavaScript, Google Search Central
• The rise of the AI crawler, Vercel et MERJ, vercel.com
• gatsby, registre npm : registry.npmjs.org/gatsby
• Release gatsby@5.16.1, GitHub
• Netlify Acquires Gatsby Inc. : netlify.com/press/netlify-acquires-gatsby-inc-to-accelerate-adoption-of-composable-web-architectures/
• Netlify Announces the Evolution of Cloud Platform : netlify.com/blog/gatsby-cloud-evolution/
• Commentaire de Matt Biilmann, issue #38696, GitHub
• Is GatsbyJS Officially Dead? discussion #39062, GitHub
• Release gatsby@5.15.0, GitHub
• Release gatsby@5.16.0, GitHub
• Commits gatsbyjs/gatsby, GitHub
• Creating a React App, react.dev
• Gatsby Head API : gatsbyjs.com/docs/reference/built-in-components/gatsby-head/
• Adding an SEO Component : gatsbyjs.com/docs/how-to/adding-common-features/adding-seo-component/
• React Helmet, version 6.1.0, GitHub
• gatsby-plugin-react-helmet, README, GitHub
• gatsby-plugin-sitemap, README, GitHub
• Créer et envoyer un sitemap, Google Search Central
• Using the Static Folder : gatsbyjs.com/docs/how-to/images-and-media/static-folder/
• gatsby-plugin-robots-txt, registre npm : registry.npmjs.org/gatsby-plugin-robots-txt
• gatsby-plugin-canonical-urls, README, GitHub
• Gatsby Config API : gatsbyjs.com/docs/reference/config-files/gatsby-config/#trailingslash
• Migrating from v4 to v5 : gatsbyjs.com/docs/reference/release-notes/migrating-from-v4-to-v5/
• Gatsby Link API : gatsbyjs.com/docs/reference/built-in-components/gatsby-link/
• gatsby-image, registre npm : registry.npmjs.org/gatsby-image
• gatsby-plugin-image, README, GitHub
• Gatsby Image plugin : gatsbyjs.com/docs/reference/built-in-components/gatsby-plugin-image/
• gatsby-plugin-google-analytics, README, GitHub
• packages/gatsby/cache-dir/static-entry.js, GitHub
• head-export-handler-for-ssr.js, GitHub
• gatsby-plugin-canonical-urls/src/gatsby-ssr.js, GitHub
• Guides: JSON-LD, Next.js