【Astro】クライアントディレクティブとは？client:loadの使い分け

Astroを触りはじめて最初につまずくのが、この 「置いただけでは動かない」 という挙動だと思います。

理由はシンプルで、Astroは デフォルトでJavaScriptを1行も出力しない からです。
そのうえで「ここだけは動かしたい」と指定するための仕組みが、クライアントディレクティブです。

この記事では、5種類あるディレクティブの違いと、どれを選べばいいのかの判断軸を、私なりに整理していきます。

Astroでの記事データの扱い方については、別記事で整理しています。

【Astro】コンテンツコレクションとは？記事を型安全に管理する書き方Astroのコンテンツコレクションの使い方を解説。src/content.config.tsの書き方、globローダーとZodスキーマでの型定義、getCollectionやrenderでの取り出し方、下書きの除外や旧APIからの変更点まで整理しました。rarzyu.com

Astroのコンポーネントが動かないのは仕様｜アイランドとハイドレーション

Astroは アイランドアーキテクチャという考え方でできています。

ページ全体は静的なHTMLとして書き出しておいて、動きが必要な部品だけを「島（アイランド）」として切り出し、そこにだけJavaScriptを届ける、という作りです。

つまりAstroにとっては、JavaScriptを配らないのが標準の状態です。
ReactやSvelteのコンポーネントを置いても、指示がなければサーバー側でHTMLに変換されて終わり。だからクリックしても反応しません。

---
import Counter from "../components/Counter.jsx";
---

<!-- 見た目は出るが、クリックしても動かない -->
<Counter />

<!-- JSが届いて、動くようになる -->
<Counter client:load />

この client:load の部分がクライアントディレクティブです。
「この部品にはJavaScriptを届けてください。届けるタイミングはこれです」 という指定だと考えるとわかりやすいと思います。

クライアントディレクティブ5種の書き方

Astroが標準で用意しているのは次の5つです。公式ドキュメントが示す優先度（高→中→低）の順に並べています。
ただし client:only は優先度の枠外で、client:load と同じくページ読み込み直後に動きます。

1. client:load｜ページ表示と同時に動かす

<BuyButton client:load />

ページが読み込まれた時点ですぐにハイドレーションします。優先度が一番高い指定です。

最初の画面に見えていて、すぐ押される可能性がある部品に向いています。購入ボタン、ヘッダーの検索フォーム、開閉するグローバルメニューあたりですね。

2. client:idle｜ブラウザの手が空いてから動かす

<ShowHideButton client:idle />

ページの初期読み込みが終わり、ブラウザが暇になったタイミング（requestIdleCallback）でハイドレーションします。

すぐ触られるわけではないけれど、画面には最初から見えている部品向けです。
待ち時間の上限を決めたいときは、ミリ秒でタイムアウトを渡せます。

<ShowHideButton client:idle={{timeout: 500}} />

こう書くと、ブラウザが暇にならなくても 500ミリ秒経てばハイドレーションを始めます。

3. client:visible｜画面に入ってから動かす

<HeavyImageCarousel client:visible />

その部品がビューポート（表示領域）に入ったときに初めてハイドレーションします。内部では IntersectionObserver が使われています。

ページ下部のカルーセルやコメント欄など、スクロールしないと出てこない重い部品に向いています。読者がそこまで来なければ、そのJavaScriptは一生読み込まれません。

少し手前で準備を始めたいときは、rootMargin を渡します。

<HeavyImageCarousel client:visible={{rootMargin: "200px"}} />

画面に入る200px手前から読み込みが始まるので、表示された瞬間にはもう触れる状態になりやすくなります。回線が遅い環境やレイアウトのガタつきが気になるときに有効です。

4. client:media｜画面幅の条件つきで動かす

<SidebarToggle client:media="(max-width: 50em)" />

指定したCSSメディアクエリに一致したときだけハイドレーションします。

スマホのときだけ必要な部品が典型です。モバイル用のハンバーガーメニューやドロワーは、PCでは使われないのにJavaScriptだけ届いている、ということが起こりがちなので、ここで絞れます。

5. client:only｜サーバーでは描画しない

<SomeReactComponent client:only="react" />

サーバー側のHTML生成をスキップして、ブラウザだけで描画・実行する指定です。

ポイントは、フレームワーク名を文字列で必ず渡すこと。Astroはこの部品をビルド時にもサーバー側でも動かさないため、何で書かれたコンポーネントなのかを推測できないからです。react / preact / svelte / vue / solid-js のように指定します。

window や localStorage にアクセスするなど、ブラウザにしか存在しないものへ依存している部品の逃げ道として使います。

どれを選ぶ？部品の「位置」と「重さ」で決める

迷ったときは、その部品が最初の画面に見えているかと、どのくらい重いかの2軸で考えると決まりやすいです。

とはいえ、とりあえず全部 client:load にするのは避けたいところです。
アイランドを増やすほど初期表示で読み込むJavaScriptが増えて、Astroを選んだ理由そのものが薄れてしまいます。

私は基本的に、まず「ワンランク遅い方」から試すようにしています。
体感で困らなければそのまま、待たされる感じがしたら1段上げる。それくらいの温度感でいいと思います。

指定するときに引っかかりやすい4つのこと

1. .astro コンポーネントには付けられない

client:load などを指定できるのは、React・Preact・Svelte・Vue・Solidといった UIフレームワークのコンポーネントです。

.astro ファイルはサーバー側でHTMLになるための仕組みなので、そもそもクライアントで動く状態を持っていません。
.astro の中に動きが欲しい場合は、素の <script> を書くか、その部分だけをフレームワークのコンポーネントに切り出すことになります。

2. インテグレーションを入れていないと使えない

ReactやSvelteのコンポーネントをAstroで扱うには、対応するインテグレーションの追加が必要です。

npx astro add react

コンポーネントを置いただけでビルドが通らないときは、まずここを疑ってみてください。

3. 付け忘れてもエラーにならない

冒頭の話に戻りますが、ディレクティブを書き忘れても ビルドは成功します。
静的なHTMLとして正しく出力されるので、Astroからすると何も問題がないんですよね。

「動かない」と感じたときの確認順は、ディレクティブの有無 → インテグレーション → コンポーネント本体がおすすめです。

4. サーバー側の遅い処理は server:defer という選択肢もある

.astro コンポーネントのうち、データ取得に時間がかかる部分だけ後から差し込みたいというケースもあります。この場合は server:defer を使います。

---
import Avatar from "../components/Avatar.astro";
---

<Avatar server:defer />

こう書くと、その部分がサーバーアイランドになり、ページ本体とは別に読み込まれます。読み込み中に出しておく内容は、子要素の slot="fallback" で指定できます。

ただし server:defer を使うには、@astrojs/node などのアダプターの導入が必要です。全ページ静的なサイトでもアダプター自体は追加できますが、入れていないとビルドエラーになります。詳しくは公式の Server islands を参照してください。

client:* がブラウザ側の話なのに対して、server:defer はサーバー側の話。名前は似ていますが役割はまったく別物なので、混同しないよう気をつけたいところです。

まとめ｜ディレクティブは「JavaScriptを届ける約束」

クライアントディレクティブは、単なるおまじないではなく、この部品にいつJavaScriptを届けるかの約束です。

Astroはデフォルトで何も配らないからこそ、どこに配るかを自分で決められます。
その判断がそのままページの表示速度になる、と考えると選び方も見えてくるはずです。