Gatsby SEO Guide

Complete guide to building SEO-friendly applications with Gatsby. Learn best practices, common pitfalls, and actionable recommendations.

Published: Last updated:
Back to Framework Guides

Gatsby

React-based SSG

Easy SEO SetupOfficial Site

SEO Friendliness

Technical SEO capability

5/5
Strong

Performance

Runtime and delivery efficiency

5/5
Strong

Ecosystem

Community, plugins, tooling

4/5
Strong

Primary Rendering

SSG, DSG

Key SEO Considerations

1

A powerful Static Site Generator (SSG) built on React, producing incredibly fast websites.

2

Its core strength is a GraphQL data layer that can pull content from any source (CMSs, APIs, Markdown).

3

Its rich plugin ecosystem simplifies many SEO tasks like creating sitemaps and managing metadata.

4

Best suited for content-heavy websites; less ideal for highly dynamic, real-time applications.

Content Mesh Architecture

The GraphQL-Powered Framework

Gatsby is a React-based framework whose architectural heart is Static Site Generation (SSG). Its unique feature is a powerful data layer that uses GraphQL to create a unified "content mesh," pulling data from any source (headless CMSs, Markdown, APIs) during the build process.

Static Site Advantages

Blazing-Fast Static Sites

Gatsby's default output is a fully static website, which is its primary SEO advantage.

  • Instant Crawlability: Every page is a pre-rendered HTML file, so crawlers can index content instantly and completely.
  • Peak Performance: Static sites are inherently fast. Gatsby adds further optimizations like code-splitting, lazy-loading, and image optimization, leading to excellent Core Web Vitals.

Plugin Ecosystem

The Power of Plugins

Gatsby's extensive plugin library is key to its SEO capabilities.

  • gatsby-plugin-sitemap: Automatically generates a sitemap.xml during the build.
  • gatsby-plugin-image: A standout feature that provides a component for automatic image optimization, including resizing, modern formats, and lazy loading.
  • Metadata: Typically managed by creating a reusable SEO component that uses react-helmet-async to populate head tags.

Actionable Recommendations

  • Choose Gatsby for content-heavy sites: blogs, documentation, and marketing websites.
  • Leverage the plugin ecosystem for SEO tasks; this is the idiomatic "Gatsby way."
  • Master the GraphQL data layer to unlock Gatsby's full potential.
  • The gatsby-plugin-image is non-negotiable for any Gatsby site with images.

International SEO

International SEO Fundamentals

When targeting multiple countries or languages, proper international SEO ensures search engines serve the right content to the right audience. This involves URL structure, hreflang tags, and language detection.

  • URL Structure Options: Choose between subdirectories (/en/, /fr/), subdomains (en.site.com), or parameters (?lang=en). Subdirectories are typically recommended for most sites.
  • Hreflang Tags: HTML attributes that tell search engines about language and regional variations of your pages. Format: <link rel="alternate" hreflang="en-US" href="..." />
  • Language vs Locale: Use language codes (en) for language targeting, or locale codes (en-US, en-GB) for region-specific content.

Implementing International SEO in Gatsby

Gatsby's plugin ecosystem and static generation make it excellent for building multilingual sites with optimal SEO.

  • Routing Strategy: Use page creation in gatsby-node.js to programmatically create pages with language prefixes. Plugins like gatsby-plugin-intl automate this process.
  • Adding Hreflang: Add hreflang tags in your SEO component using react-helmet-async, or use gatsby-plugin-intl which handles hreflang automatically.
  • Recommended Tools: gatsby-plugin-intl (automates i18n routing), react-intl (for translations), react-helmet-async (for metadata), gatsby-plugin-sitemap (with locale-specific sitemaps).
  • Code Example:
    // gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-intl',
      options: {
        path: `${__dirname}/src/intl`,
        languages: ['en', 'fr'],
        defaultLanguage: 'en',
        redirect: true
      }
    }
  ]
};

// src/components/SEO.js
import React from 'react';
import { Helmet } from 'react-helmet-async';
import { useIntl } from 'gatsby-plugin-intl';

export const SEO = ({ title, description }) => {
  const intl = useIntl();
  const lang = intl.locale;
  
  return (
    <Helmet>
      <html lang={lang} />
      <title>{title}</title>
      <meta name="description" content={description} />
      
      <link rel="alternate" hreflang="en" href="https://site.com/en/about" />
      <link rel="alternate" hreflang="fr" href="https://site.com/fr/about" />
      <link rel="alternate" hreflang="x-default" href="https://site.com/en/about" />
    </Helmet>
  );
};

// In a page component
import { FormattedMessage } from 'react-intl';

const AboutPage = () => (
  <>
    <SEO title="About Us" description="Learn about our company" />
    <h1><FormattedMessage id="about.title" /></h1>
  </>
);

Ready to build with Gatsby?

Explore more framework guides and SEO resources to make the right choice for your project.

View All Framework GuidesBrowse SEO Resources