ブログ基盤を Gatsby から Astro 6 へ全面刷新

公開: 2026年5月3日 更新: 2026年5月3日

• #astro
• #gatsby
• #migration
• #pnpm
• #mise
• #github-actions
• #oxlint

このブログは長らく Gatsby v3 で運用してきたが、2026 年現在では古さが目立ち、Node 14 (EOL)・依存の脆弱性・ビルド失敗など実用上の問題が出てきた。今回、SSG 本体だけでなくランタイム・パッケージマネージャ・Linter・CI/CD まで含めて全面的に刷新したのでまとめておく。

旧スタック

ビルドはそもそも失敗していた([email protected] が Node 18 以降で動かない)。

新スタック

段階的に進めた

1. Linter/Formatter を oxlint/oxfmt へ

最初に手を付けたのはここ。Prettier は Rust 系の oxlint/oxfmt に置き換えた。oxfmt はまだ pre-1.0 (0.47.0) だが、個人ブログ用途では問題なし。

1
{
2
  "scripts": {
3
    "lint": "oxlint",
4
    "format": "oxfmt .",
5
    "format:check": "oxfmt --check ."
6
  }
7
}

oxlint は ESLint 互換ルールを 100 倍以上の速度で実行する。実際に走らせるとプロジェクト全体で 20ms 程度。

2. パッケージマネージャを pnpm へ

yarn.lock を捨てて pnpm-lock.yaml を生成。packageManager フィールドで pnpm 10.33.2 を固定。Astro 6 のクリーンな install で約 6 秒。

3. Node を mise で 24 LTS に固定

Volta から mise へ移行。.tool-versions 一本で OS / CI 両方が同じバージョンを使う。GitHub Actions の setup-node も node-version-file: .tool-versions で読めて二重管理を避けられる。

1
node 24.15.0

4. CircleCI から GitHub Actions へ

GitHub Pages のデプロイは actions/deploy-pages@v5 に統一。リポジトリ設定で Source: GitHub Actions に切り替えれば、master ブランチへの commit 配信は不要になる。

5. Gatsby 3 から Astro 6 へ

ここが本丸。Astro は Markdown ファイルをそのまま Content Collections として扱える上、JS バンドルを デフォルトで 0 にできるので個人技術ブログに最適。

src/content/articles/<YYYY>/<MM>/<slug>/index.md というディレクトリ構造で、gatsby-source-filesystem 相当の自動ルーティングが手に入る。スキーマは zod で型付け:

1
import { glob } from "astro/loaders";
2
import { defineCollection, z } from "astro:content";
3

4
const articles = defineCollection({
5
  loader: glob({ pattern: "**/index.md", base: "./src/content/articles" }),
6
  schema: z.object({
7
    title: z.string(),
8
    date: z.coerce.date(),
9
    tags: z.array(z.string()).default([]),
10
  }),
11
});
12

13
export const collections = { articles };

URL 構造は /articles/YYYY/MM/<slug>/ で旧サイトと互換。記事 10 本 + index + タグページで全 42 ページが 1.3 秒 でビルドできる。

ブログ機能の改善

ついでに気になっていた機能を整備した。

コードブロック: astro-expressive-code

行番号・コピーボタン・ライト/ダーク両テーマ・ファイル名タブ・行ハイライト等が一通り揃う:

1
import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
2
import { defineEcConfig } from "astro-expressive-code";
3

4
export default defineEcConfig({
5
  plugins: [pluginLineNumbers()],
6
  defaultProps: {
7
    wrap: true,
8
  },
9
});

画像 zoom:

+ rehype プラグイン

小さい架構図やスクリーンショットを拡大表示できるようにした。Markdown の <img> を rehype プラグインで <button data-zoom-target> + <dialog> 構造に変換し、レイアウト側で dialog.showModal() をフックする。

1
.zoom-dialog {
2
  width: 95vw;
3
  height: 95vh;
4
  background: transparent;
5
  border: none;
6
}
7
.zoom-dialog > img {
8
  width: 100%;
9
  height: 100%;
10
  object-fit: contain;
11
}
12
.zoom-dialog::backdrop {
13
  background: color-mix(in srgb, black 90%, transparent);
14
}

<form method="dialog"> を使えば閉じる × ボタンの JavaScript すら不要。Esc / 領域外クリックで閉じる挙動も <dialog> 標準。

タグ別ページ・目次・抜粋

• /tags/ でタグ一覧、/tags/<slug>/ で絞り込み
• 記事ページの aside.toc で目次サイドバー(render(post) の headings から自動生成)
• トップ一覧では entry.body を Markdown 記法を除去したうえで 140 字にトリムして冒頭表示

アクセシビリティ

WCAG を意識した一通りのパスを実施: 本文 17px、color-mix() で AA 達成、タップ領域 44px、:focus-visible のアウトライン、prefers-reduced-motion 尊重、Skip-to-main-content リンクなど。

デプロイ運用: タグ駆動

main への push は CI のみで本番反映しない。タグ push 時にだけデプロイされる構成。

1
# 通常のコード変更
2
pnpm release         # patch (vX.Y.Z+1)
3
pnpm release:minor   # minor (vX.Y+1.0)
4
pnpm release:major   # major (vX+1.0.0)
5

6
# 記事公開
7
pnpm release:post    # post-YYYYMMDD-HHmm タグ

記事公開とコードリリースをタグの prefix で分けたので、git log で「いつ何を出したか」が追える。

残課題

• 関連記事リンク・全文検索は未実装
• アナリティクスは要検討(Cloudflare Web Analytics または Plausible 候補)
• 記事のテストや prose lint(textlint 等)の導入は今後