Gatsby の使い方 — React ベースの高速サイトジェネレーター

一言でいうと

Gatsby は React ベースのオープンソースフレームワークで、静的サイト生成（SSG）を軸に、サーバーサイドレンダリング（SSR）や Deferred Static Generation（DSG）も組み合わせて高速な Web サイト・アプリを構築できるツールです。GraphQL による統一的なデータレイヤーが最大の特徴で、あらゆるデータソースを一元的に扱えます。

どんな時に使う？

1. ブログやドキュメントサイトの構築 — Markdown や MDX ファイルからコンテンツを読み込み、高速な静的サイトとして配信したい場合
2. ヘッドレス CMS と連携したコーポレートサイト — Contentful、WordPress、Strapi などの CMS からデータを取得し、React で自由にフロントエンドを構築したい場合
3. パフォーマンス最適化が求められるマーケティングサイトや EC サイト — 画像最適化、コード分割、プリフェッチなどが自動で適用され、Lighthouse スコアを高く保ちたい場合

インストール

プロジェクトの新規作成（推奨）

# インタラクティブにプロジェクトを初期化
npm init gatsby

# または Gatsby CLI を使う場合
npm install -g gatsby-cli
gatsby new my-gatsby-site

既存プロジェクトへの追加

# npm
npm install gatsby react react-dom

# yarn
yarn add gatsby react react-dom

# pnpm
pnpm add gatsby react react-dom

注意: Gatsby v5 は Node.js 18 以上、React 18 以上が必要です。

基本的な使い方

最もシンプルなパターンとして、ページコンポーネントを作成してローカル開発サーバーを起動する流れを示します。

プロジェクト構成

my-gatsby-site/
├── gatsby-config.ts
├── src/
│   └── pages/
│       ├── index.tsx
│       └── about.tsx
├── package.json
└── tsconfig.json

gatsby-config.ts

import type { GatsbyConfig } from "gatsby"

const config: GatsbyConfig = {
  siteMetadata: {
    title: "My Gatsby Site",
    description: "A blazing fast site built with Gatsby",
    siteUrl: "https://example.com",
  },
  plugins: [
    "gatsby-plugin-image",
    "gatsby-plugin-sharp",
    "gatsby-transformer-sharp",
  ],
}

export default config

src/pages/index.tsx

import * as React from "react"
import { graphql, PageProps, HeadFC } from "gatsby"

type DataProps = {
  site: {
    siteMetadata: {
      title: string
      description: string
    }
  }
}

const IndexPage: React.FC<PageProps<DataProps>> = ({ data }) => {
  const { title, description } = data.site.siteMetadata

  return (
    <main>
      <h1>{title}</h1>
      <p>{description}</p>
    </main>
  )
}

export default IndexPage

// Gatsby Head API（v4.19+）
export const Head: HeadFC<DataProps> = ({ data }) => (
  <title>{data.site.siteMetadata.title}</title>
)

// ページクエリ
export const query = graphql`
  query IndexPage {
    site {
      siteMetadata {
        title
        description
      }
    }
  }
`

開発・ビルドコマンド

# 開発サーバー起動（http://localhost:8000）
npm run develop

# 本番ビルド
npm run build

# ビルド結果をローカルで確認
npm run serve

よく使う API — Gatsby の使い方ガイド

1. GraphQL ページクエリと StaticQuery

ページコンポーネントでは graphql タグでデータを取得します。非ページコンポーネントでは useStaticQuery を使います。

import * as React from "react"
import { useStaticQuery, graphql } from "gatsby"

const Header: React.FC = () => {
  const data = useStaticQuery(graphql`
    query HeaderQuery {
      site {
        siteMetadata {
          title
        }
      }
    }
  `)

  return <header><h1>{data.site.siteMetadata.title}</h1></header>
}

export default Header

2. gatsby-node.ts — プログラムによるページ生成

Markdown ファイルなどから動的にページを生成する最も一般的なパターンです。

import type { GatsbyNode } from "gatsby"
import path from "path"

export const createPages: GatsbyNode["createPages"] = async ({
  graphql,
  actions,
  reporter,
}) => {
  const { createPage } = actions

  const result = await graphql<{
    allMarkdownRemark: {
      nodes: Array<{ frontmatter: { slug: string } }>
    }
  }>(`
    query {
      allMarkdownRemark {
        nodes {
          frontmatter {
            slug
          }
        }
      }
    }
  `)

  if (result.errors) {
    reporter.panicOnBuild("Error loading markdown", result.errors)
    return
  }

  const blogPostTemplate = path.resolve("src/templates/blog-post.tsx")

  result.data?.allMarkdownRemark.nodes.forEach((node) => {
    createPage({
      path: `/blog/${node.frontmatter.slug}`,
      component: blogPostTemplate,
      context: {
        slug: node.frontmatter.slug,
      },
    })
  })
}

3. gatsby-plugin-image — 最適化された画像表示

Gatsby の画像最適化は強力な差別化ポイントです。StaticImage（静的パス用）と GatsbyImage（動的データ用）の 2 種類があります。

import * as React from "react"
import { StaticImage } from "gatsby-plugin-image"
import { GatsbyImage, getImage, IGatsbyImageData } from "gatsby-plugin-image"
import { graphql, PageProps } from "gatsby"

// 静的画像（パスがビルド時に確定している場合）
const StaticExample: React.FC = () => (
  <StaticImage
    src="../images/hero.jpg"
    alt="Hero image"
    placeholder="blurred"
    layout="fullWidth"
  />
)

// 動的画像（GraphQL から取得する場合）
type ImagePageData = {
  file: {
    childImageSharp: {
      gatsbyImageData: IGatsbyImageData
    }
  }
}

const DynamicExample: React.FC<PageProps<ImagePageData>> = ({ data }) => {
  const image = getImage(data.file.childImageSharp)

  return image ? (
    <GatsbyImage image={image} alt="Dynamic image" />
  ) : null
}

export const query = graphql`
  query {
    file(relativePath: { eq: "hero.jpg" }) {
      childImageSharp {
        gatsbyImageData(width: 800, placeholder: BLURRED)
      }
    }
  }
`

4. Head API — SEO メタタグの管理

Gatsby v4.19 以降で導入された Head API により、react-helmet なしで <head> 要素を宣言的に管理できます。

import * as React from "react"
import { HeadFC, HeadProps } from "gatsby"

type SEOData = {
  site: {
    siteMetadata: {
      title: string
      description: string
      siteUrl: string
    }
  }
}

export const Head: HeadFC<SEOData> = ({ data, location }) => {
  const { title, description, siteUrl } = data.site.siteMetadata

  return (
    <>
      <title>{title}</title>
      <meta name="description" content={description} />
      <meta property="og:title" content={title} />
      <meta property="og:url" content={`${siteUrl}${location.pathname}`} />
      <link rel="canonical" href={`${siteUrl}${location.pathname}`} />
    </>
  )
}

5. レンダリングオプション — SSG / DSG / SSR の切り替え

Gatsby v5 ではページ単位でレンダリング戦略を選択できます。

// gatsby-node.ts
import type { GatsbyNode } from "gatsby"

export const createPages: GatsbyNode["createPages"] = async ({
  actions,
}) => {
  const { createPage } = actions

  // 通常の SSG（デフォルト）
  createPage({
    path: "/about",
    component: require.resolve("./src/templates/about.tsx"),
    context: {},
  })

  // Deferred Static Generation — ビルド時には生成せず、初回アクセス時に生成
  createPage({
    path: "/archive/old-post",
    component: require.resolve("./src/templates/blog-post.tsx"),
    context: { slug: "old-post" },
    defer: true, // DSG を有効化
  })
}

SSR を使う場合は、ページコンポーネントから getServerData をエクスポートします。

import * as React from "react"
import type { GetServerDataProps, GetServerDataReturn } from "gatsby"

type ServerDataProps = {
  message: string
}

const SSRPage: React.FC<{ serverData: ServerDataProps }> = ({
  serverData,
}) => {
  return <p>{serverData.message}</p>
}

export default SSRPage

// この関数をエクスポートすると、そのページは SSR になる
export async function getServerData(
  props: GetServerDataProps
): GetServerDataReturn<ServerDataProps> {
  return {
    status: 200,
    headers: {},
    props: {
      message: `Server rendered at ${new Date().toISOString()}`,
    },
  }
}

類似パッケージとの比較

選定の目安:

• GraphQL でデータを統一管理したい、プラグインで拡張したい → Gatsby
• フルスタックアプリ、API Routes、RSC を活用したい → Next.js
• JS を極力減らして軽量なサイトを作りたい → Astro
• React 不要で超高速ビルドが欲しい → Hugo

注意点・Tips

1. GraphQL の学習コストを見積もる

Gatsby を使う以上、GraphQL は避けて通れません。GraphiQL（http://localhost:8000/___graphql）を活用してクエリを対話的に構築するのが効率的です。

2. ビルド時間の肥大化に注意

ページ数が数千〜数万規模になると、ビルド時間が大幅に増加します。以下の対策を検討してください。

• DSG（Deferred Static Generation） を活用し、アクセス頻度の低いページはビルドを遅延させる
• Gatsby Cloud（現在は Netlify に統合）のインクリメンタルビルドを利用する
• gatsby-plugin-sharp の画像処理がボトルネックになりやすいため、不要な画像変換を減らす

3. Gatsby Cloud の終了について

重要: 2023 年に Gatsby は Netlify に買収され、Gatsby Cloud は 2023 年 9 月にサービスを終了しました。ホスティングは Netlify、Vercel、Cloudflare Pages などを利用してください。

4. TypeScript は最初から有効にする

Gatsby v5 は TypeScript をファーストクラスでサポートしています。gatsby-config.ts、gatsby-node.ts など設定ファイルも TypeScript で記述可能です。型定義は gatsby パッケージに同梱されています。

// 型安全な gatsby-config.ts
import type { GatsbyConfig } from "gatsby"

const config: GatsbyConfig = {
  // 型補完が効く
}

export default config

5. プラグイン選定のコツ

• 公式プラグイン（gatsby-plugin-*、gatsby-source-*、gatsby-transformer-*）を優先する
• 最終更新日が古いコミュニティプラグインは Gatsby v5 との互換性を確認する
• gatsby-plugin-image + gatsby-plugin-sharp + gatsby-transformer-sharp は画像を扱うならほぼ必須のセット

6. v4 から v5