Gatsby SEO Best Practices

Gatsby SEO best practices

Gatsby is a React based static site generator, so its SEO strengths and its pitfalls both come from how it turns your components into HTML at build time. Done well, a Gatsby site ships lean, pre-rendered pages that crawlers index effortlessly. Done carelessly, key pages hide behind client only rendering and never surface in search. This guide walks through the practical moving parts: the Head API, a reusable SEO component, sitemap and robots.txt plugins, image performance, rendering modes, and the URL settings that quietly break canonicals. If you are coming from another stack, our Drupal SEO module guide covers the same fundamentals in a CMS context.

The Gatsby Head API versus react-helmet

Older Gatsby tutorials tell you to install gatsby-plugin-react-helmet and render a Helmet component inside your page body. That still works, but it adds a dependency and can behave inconsistently during hydration. Modern Gatsby ships the Head API: you export a named function called Head from any page or template, and Gatsby injects whatever it returns into the document head during server rendering. Because the tags are emitted into the static HTML, search engines see the correct title, meta description, and canonical without executing JavaScript. Prefer the Head API for new work and migrate Helmet usage when you touch a template.

Build one reusable SEO component

Centralize head logic in a single component so every page sets a consistent set of tags: a unique title, a meta description, a self referencing canonical link, Open Graph and Twitter Card tags for social previews, and a JSON-LD block for structured data. The example below reads values from pageContext, which you populate in gatsby-node.js when you create pages. Note the JSON-LD is emitted through a script tag with type application/ld+json, exactly the shape Google expects.

import * as React from "react"

export const Head = ({ pageContext }) => {
  const siteUrl = "https://example.com"
  const { title, description, path } = pageContext
  const canonical = siteUrl + path
  return (
    <>
      <title>{title}</title>
      <meta name="description" content={description} />
      <link rel="canonical" href={canonical} />
      <meta property="og:title" content={title} />
      <meta property="og:description" content={description} />
      <meta property="og:type" content="website" />
      <meta property="og:url" content={canonical} />
      <meta name="twitter:card" content="summary_large_image" />
      <script type="application/ld+json">
        {JSON.stringify({
          "@context": "https://schema.org",
          "@type": "Article",
          headline: title,
          description: description,
          url: canonical,
        })}
      </script>
    </>
  )
}

Reusing this component keeps the head consistent and prevents the classic errors flagged by automated audits, such as a missing meta description on templated pages. Pass a distinct title and description for every route so no two pages compete with identical metadata.

Sitemap, robots.txt, and gatsby-config.js

Two plugins handle crawl discovery. gatsby-plugin-sitemap generates an XML sitemap at build time; you can override the output path, supply a custom GraphQL query, reshape entries with serialize, and drop utility routes with excludes. gatsby-plugin-robots-txt writes a robots.txt file where you declare the host, point at the sitemap, and set allow or disallow policy per user agent. Wiring both in gatsby-config.js looks like this:

module.exports = {
  siteMetadata: {
    siteUrl: "https://example.com",
    title: "Example",
  },
  trailingSlash: "always",
  plugins: [
    "gatsby-plugin-image",
    "gatsby-plugin-sharp",
    "gatsby-transformer-sharp",
    {
      resolve: "gatsby-plugin-sitemap",
      options: {
        output: "/sitemap",
        excludes: ["/preview/**", "/404"],
        query: `{ allSitePage { nodes { path } } }`,
      },
    },
    {
      resolve: "gatsby-plugin-robots-txt",
      options: {
        host: "https://example.com",
        sitemap: "https://example.com/sitemap-index.xml",
        policy: [{ userAgent: "*", allow: "/" }],
      },
    },
  ],
}

Set the sitemap option on the robots plugin to your sitemap index URL so crawlers can find the full URL inventory from a single robots.txt request. Use excludes to keep preview, staging, and thank you pages out of the index.

Which plugin does what

Images and Core Web Vitals

Image weight is the most common Gatsby performance drag. Pair gatsby-plugin-image with gatsby-plugin-sharp to generate responsive sources in modern formats, set explicit width and height so the browser reserves space, and lazy load anything below the fold. For your Largest Contentful Paint element, usually a hero image, use eager loading and a high fetch priority so it paints fast. Reserving dimensions is also what keeps Cumulative Layout Shift near zero. And every image needs descriptive alt text; audits routinely flag images with a missing alt attribute, which hurts both accessibility and image search.

SSG, DSG, and SSR crawlability

Gatsby offers three rendering modes. Static Site Generation builds every page to HTML at build time and is the default and safest choice for SEO. Deferred Static Generation builds a page the first time it is requested, then caches it, which suits large archives where most pages get little traffic. Server Side Rendering builds the page fresh on each request for highly dynamic content. All three return real, pre-rendered HTML to the crawler, so your titles, meta tags, and body copy are present in the initial response. The danger zone is client only routes created with the reach router splat pattern, where content renders only after JavaScript runs. Keep anything that must rank on a statically rendered path.

Path prefix, asset prefix, trailing slash, and hreflang

A few configuration options quietly govern URL hygiene. Set pathPrefix when the site is served from a subdirectory and assetPrefix when static assets live on a separate CDN host, then build with the prefix paths flag so links resolve correctly. Choose a single trailingSlash policy, commonly always, and stick with it; mixing slashed and unslashed URLs spawns duplicate paths and conflicting canonicals. For multilingual sites, emit alternate link tags with hreflang values from your Head component so Google maps language and region variants to one another. Consistent canonicals and clean prefixes prevent the self referencing canonical mismatches that plague migrated Gatsby builds. For a broader checklist, start from the SEO ProCheck homepage.

Frequently asked questions