PagefindでAstroブログに全文検索を導入した

PagefindでAstroブログに全文検索を導入しました。

この記事を読むと、以下のことがわかります。

• astro-pagefindを使用してAstroアプリケーションにPagefindを導入する方法
• Pagefind UIを使わずにAPIで検索UIをカスタム構築する方法
• ⌘Kコマンドパレット型の検索UIの実装

動作環境

背景

ブログに検索ページはあったのですが、雑に作ったまま放置していました。ポートフォリオも兼ねたブログなので、検索機能もちゃんとしたいと思い、機能とデザインを見直しました。

その過程を記事にまとめます。

Pagefindとは

公式サイトはこちらです。

Pagefind | Pagefind — Static low-bandwidth search at scale

Pagefind is a fully static search library that aims to perform well on large sites, while using as little of your users’ bandwidth as possible, and without hosting any infrastructure.

pagefind.app

Pagefindは、Rust製の静的サイト向け全文検索ライブラリです。 特徴はビルド時にHTMLをクロールしてインデックスを生成する点にあります。

開発元はCloudCannonで、静的サイト向けCMSを提供している企業です。GitHubリポジトリも継続的に更新されています。

公式サイトでは次のように説明されています。

Pagefind is a fully static search library that aims to perform well on large sites, while using as little of your users’ bandwidth as possible, and without hosting any infrastructure.

公式によると、10,000ページのサイトでもPagefindライブラリ自体を含めてネットワークペイロードが300KB未満に収まるとのことです¹。

なぜPagefindを選んだか

静的サイトに全文検索を導入する方法はいくつかあります。

下記の理由から、Pagefindを採用しました。

• 外部サービスへの依存がない（Algoliaと違い、セルフホスト不要）
• クライアント側で全記事データを読み込む必要がない（Fuse.js/Lunr.jsと違い、軽量）
• ビルド時にインデックスを生成するため、記事数が増えてもクライアントの初期ロードが重くならない

余談: Pagefindの人気度

Pagefindは2022年に公開され、上記の比較対象ライブラリと比べると新しいライブラリです。 npm trendsで他のライブラリと比較すると、ダウンロード数ではFuse.jsやLunr.jsにはまだまだ及んでいませんが、GitHub Starsは5,000を超えており、伸びている印象です。

algoliasearch vs fuse.js vs lunr vs pagefind | npm trends

Comparing trends for algoliasearch 5.49.2 which has 2,512,846 weekly downloads and 1,386 GitHub stars vs. fuse.js 7.1.0 which has 7,001,058 weekly downloads and 20,040 GitHub stars vs. lunr 2.3.9 which has 4,690,999 weekly downloads and 9,215 GitHub stars vs. pagefind 1.4.0 which has 361,353 weekly downloads and 5,073 GitHub stars.

npmtrends.com

astro-pagefindの導入

Astroへの導入はastro-pagefindというインテグレーションを使います。やることはほぼ2つだけです。GitHubリポジトリは以下です。

GitHub - shishkin/astro-pagefind: Astro integration for Pagefind static site search.

Astro integration for Pagefind static site search. - shishkin/astro-pagefind

github.com

1. インストール

お使いのパッケージマネージャでインストールします。私の環境ではpnpmを使いました。

# npm
npm install astro-pagefind

# pnpm
pnpm add astro-pagefind

2. astro.config.mjsにインテグレーションを追加

import pagefind from "astro-pagefind";

export default defineConfig({
  integrations: [react(), sitemap(), pagefind()],
});

これだけでビルド時にPagefindのインデックスが自動生成されます。pagefind()にオプションを渡す必要もありません。ビルドを実行すると、dist/pagefind/配下にpagefind.jsなどのファイルが出力されます。

3. 検索UIの表示

astro-pagefindにはデフォルトのUIコンポーネントも用意されています。

---
import Search from "astro-pagefind/components/Search";
---

<Search id="search" className="pagefind-ui" uiOptions={{ showImages: false }} />

このコンポーネントを配置するだけで、Pagefind UIベースの検索フォームが表示されます。私のブログでも最初はこの方式を使っていました。

Pagefind UIからカスタムUIへ

なぜ切り替えたか

Pagefind UIは内部的にSvelteで構築されており⁶、独自のスコープ付きCSSを持っています。私のブログではTailwind CSS + CSS変数でデザインシステムを構築しているため、Pagefind UIが既存のデザインシステムにそのまま適合しないという問題がありました。

具体的には:

• フォントサイズやパディングがサイト全体のデザイントークンと合わない
• CSSの上書きで対応しようとすると、Pagefind UIの内部構造に依存するセレクタが必要になる

以下は、Pagefind UIを使っていた頃と、カスタムUIに切り替えた後の検索ページの比較です。

Before: Pagefind UIのデフォルトコンポーネント

After: Pagefind APIで構築したカスタムUI

CSSの上書きでカスタマイズするよりも、自前でUIを作った方がデザインの自由度が高く、結果的にシンプルだと判断しました。

そこで、Pagefind APIを直接使ってUIを自前で構築することにしました。

Pagefind UIとPagefind APIの違い

Pagefindには2つの利用方法が用意されています。

Pagefind APIでSearchBoxを作る

Pagefind APIのインターフェースはシンプルで、importしてsearch()を呼ぶだけです。

Pagefindの.jsファイルはビルド後に生成されるため、通常のimport文ではなく動的import()で読み込みます。

// Pagefindをロード（ビルド後に生成されるファイルなので動的importを使う）
const pagefindPath = "/pagefind/pagefind.js";
const pf = await import(/* @vite-ignore */ pagefindPath);
await pf.init();

// 検索を実行
const response = await pf.search("astro");

// 各結果のデータを取得（遅延ロード）
const data = await response.results[0].data();
console.log(data.url);        // "/posts/astro/..."
console.log(data.meta.title); // "記事タイトル"
console.log(data.excerpt);    // "...検索キーワードの<mark>ハイライト</mark>..."

search()の結果にはdata()という関数が入っています。これを呼ぶまで詳細データは取得されません。大量の検索結果がある場合でも、表示する分だけdata()を呼べばよい設計になっています。

search()とdata()だけで検索機能が実装できるので、APIとしてはかなりシンプルだと感じました。

SearchBoxコンポーネントの実装

この仕組みを使って、/searchページ用のReactコンポーネントを作りました。Pagefindの公式ドキュメントでも動的importによる読み込みが推奨されています⁷。

export function SearchBox() {
  const [query, setQuery] = useState("");
  const [results, setResults] = useState<SearchResult[]>([]);
  const pagefindRef = useRef<Pagefind | null>(null);
  const allResultsRef = useRef<PagefindResult[]>([]);

  // 初期化: Pagefindをロード + URLパラメータから検索クエリを復元
  useEffect(() => {
    async function loadPagefind() {
      try {
        const pagefindPath = "/pagefind/pagefind.js";
        const pf = await import(/* @vite-ignore */ pagefindPath);
        await pf.init();
        pagefindRef.current = pf;

        // ?q=keyword で直接検索できるようにする
        const params = new URLSearchParams(window.location.search);
        const q = params.get("q");
        if (q) {
          setQuery(q);
          performSearch(pf, q);
        }
      } catch {
        // pagefind not available (dev mode)
      }
    }
    loadPagefind();
  }, [performSearch]);

  // 検索実行: 最初の5件だけdata()を呼ぶ
  const performSearch = useCallback(async (pf: Pagefind, searchQuery: string) => {
    const response = await pf.search(searchQuery);
    allResultsRef.current = response.results;

    const loaded = await Promise.all(
      response.results.slice(0, 5).map((r) => r.data()),
    );
    setResults(loaded.map((d) => ({
      url: d.url,
      title: d.meta.title,
      excerpt: d.excerpt,
    })));
  }, []);

  // ...（入力ハンドラ、もっと見る、UI部分）
}

ポイントは以下の2つです。

1. 遅延ロード: allResultsRefに全結果を保持し、「もっと見る」で追加分のdata()を呼びます
2. URLパラメータ対応: ?q=keywordで直接検索結果ページにアクセスできます

ビルド後にプレビューサーバーで実際に検索してみると、結果がほぼ一瞬で返ってきます。個人ブログの記事数であればレスポンスの遅さを感じることはまずないと思います。

以下はカスタムUIで構築した検索ページです。

⌘Kコマンドパレットの実装

SearchBoxとは別に、どのページからでも呼び出せるコマンドパレット型の検索UIも作りました。GitHubやVercelのダッシュボードなど、最近のWebアプリでは⌘Kで検索を呼び出すパターンをよく見かけます。自分のブログにも取り入れてみました。

SearchBoxと同じPagefind APIを使っていますが、コマンドパレットでは以下の点が異なります。

• HTML <dialog>要素をベースに実装し、Escキーはブラウザネイティブの挙動に任せ、バックドロップクリックはonClickで実装している
• 200msのデバウンスをかけて、入力中の不要なAPI呼び出しを抑制
• 結果は最大8件に絞り、素早く目的の記事にたどり着けるようにしている

⌘Kショートカットの登録

グローバルなキーボードショートカットで<dialog>の開閉を制御します。<dialog>要素のshowModal()を使うことで、Escキーでの閉じる動作はブラウザが処理してくれます。バックドロップクリックでの閉じる動作は自動では提供されないため、<dialog>要素へのonClickで実装しています。

export function CommandPalette() {
  const dialogRef = useRef<HTMLDialogElement>(null);
  const inputRef = useRef<HTMLInputElement>(null);

  const openDialog = useCallback(() => {
    dialogRef.current?.showModal();
    setTimeout(() => inputRef.current?.focus(), 0);
    loadPagefind(); // ダイアログを開いたタイミングでPagefindをプリロード
  }, [loadPagefind]);

  // ⌘K / Ctrl+K でトグル
  useEffect(() => {
    const handler = (e: KeyboardEvent) => {
      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
        e.preventDefault();
        if (dialogRef.current?.open) {
          dialogRef.current.close();
        } else {
          openDialog();
        }
      }
    };
    document.addEventListener("keydown", handler);
    return () => document.removeEventListener("keydown", handler);
  }, [openDialog]);

  return (
    <dialog ref={dialogRef} className="...">
      <input ref={inputRef} type="text" placeholder="記事を検索..." />
      {/* 検索結果の表示 */}
    </dialog>
  );
}

デバウンス付き検索

入力のたびにAPI呼び出しが走らないよう、200msのデバウンスをかけています。結果は最大8件に絞り、コマンドパレットとしての素早い操作感を優先しました。

// queryが変わるたびにデバウンス付きで検索を実行
useEffect(() => {
  if (!query.trim()) {
    setResults([]);
    return;
  }

  clearTimeout(debounceRef.current);
  debounceRef.current = setTimeout(async () => {
    setIsLoading(true);
    const pf = await loadPagefind();
    if (!pf) return;

    const response = await pf.search(query);
    const data = await Promise.all(
      response.results.slice(0, 8).map((r) => r.data()),
    );
    setResults(
      data.map((d) => ({
        url: d.url,
        title: d.meta.title,
        excerpt: d.excerpt,
      })),
    );
    setIsLoading(false);
  }, 200);

  return () => clearTimeout(debounceRef.current);
}, [query, loadPagefind]);

BaseLayout.astroで<CommandPalette client:load />として全ページに配置しています。

以下はコマンドパレットの表示例です。

⌘Kで呼び出したコマンドパレット。検索結果から直接記事に遷移できる

まとめ

astro-pagefindの導入自体は、パッケージのインストールとastro.config.mjsへの1行追加だけで完了します。それだけで静的サイトに全文検索が入る手軽さが最大の魅力だと感じました。

デザインを自前で作り込みたい場合は、Pagefind APIを直接使ったカスタムUI構築という選択肢があります。APIのインターフェースがシンプルなので、Reactコンポーネントとして自然に実装できました。

参考

Pagefind | Pagefind — Static low-bandwidth search at scale

Pagefind is a fully static search library that aims to perform well on large sites, while using as little of your users’ bandwidth as possible, and without hosting any infrastructure.

pagefind.app

GitHub - shishkin/astro-pagefind: Astro integration for Pagefind static site search.

Astro integration for Pagefind static site search. - shishkin/astro-pagefind

github.com