Shimanami RouteLab｜しまなみ海道のスポット紹介サイトを個人開発

`useEffect` の第2引数（依存配列）を空にしていい場面・してはいけない場面——しまなみガイドの実装から整理した

2026-05-02T13:52:46+09:00

はじめに

しまなみ海道の観光ガイドサイトを個人で開発しています。カスタムフックを書くたびに useEffect の第2引数（依存配列）をどう書くか迷いました。

useEffect(() => {
  // 何か処理
}, [])          // ← これは正しいのか？

「とりあえず [] にしとけばいい」と思っていた時期があります。実際には [] が正しい場面と、[] にしてはいけない場面があります。

このサイトで書いたカスタムフックを素材に、4パターンに整理しました。

まず：依存配列とは何か

useEffect の第2引数は「この値が変わったときに再実行する」というリストです。

useEffect(() => {
  // 処理
}, [a, b])  // a または b が変わったときに再実行

[]（空） → マウント時に1回だけ実行。以降は再実行しない
[a, b] → a か b が変わるたびに再実行
省略（第2引数なし） → 毎レンダリングのたびに実行

パターン1：`[]` でいい場面——「初回だけ取得すればいい」静的データ

// src/hooks/map/useHotelsData.ts
useEffect(() => {
  let cancelled = false

  ;(async () => {
    const res = await fetch('/data/hotels.json', { cache: 'no-store' })
    if (!cancelled) setHotels(await res.json())
  })().catch(() => {})

  return () => { cancelled = true }
}, [])  // ← [] で正しい

useHotelsData はホテルの GeoJSON ファイルをフェッチするフックです。フェッチ対象の URL は固定で、props や state に依存しません。「マウント時に1回取得すれば十分」なケースは [] が正解です。

同じパターンは useBusTimetable（バス時刻表）でも使っています。どちらも「URL が変わることはない・ページを開いたときに1回取得すれば十分」というデータです。

[] を使っていい条件： - effect 内で参照している値がコンポーネントの外（定数・モジュールスコープ）にある - effect 内で参照している値が props や state ではない - 「何かが変わったら再実行したい」という要件がない

パターン2：`[依存値]` が必要な場面——「URLが変わったら取り直す」

// src/hooks/map/useMapStyle.ts
export function useMapStyle(styleUrl: string) {
  const [styleSpec, setStyleSpec] = useState<MapboxStyle | null>(null)

  useEffect(() => {
    const ac = new AbortController()
    setStyleSpec(null)
    ;(async () => {
      try {
        const spec = await fetchAndLocalizeStyle(styleUrl, ac.signal)
        if (!ac.signal.aborted) setStyleSpec(spec)
      } catch { /* noop */ }
    })()
    return () => ac.abort()
  }, [styleUrl])  // ← styleUrl が変わるたびに再実行

  return { styleSpec }
}

useMapStyle は地図のスタイルURL（衛星モード・通常モードなど）を受け取ってスタイル定義を取得するフックです。ユーザーがレイヤーを切り替えると styleUrl が変わるため、[styleUrl] にしています。

[] にしていたら、スタイルを切り替えても最初のURLのスタイルを使い続けます。

また return () => ac.abort() でクリーンアップしています。styleUrl が変わって effect が再実行されるとき、前回の fetch を中断するためです。依存配列に値を入れたら、クリーンアップも一緒に書くのがセットです。

パターン3：`[query]` が必要な場面——「設定が変わったらリスナーを張り直す」

// src/hooks/useIsMobile.ts
export function useMediaQuery(query: string) {
  const [matches, setMatches] = useState(false)

  useEffect(() => {
    if (typeof window === 'undefined') return
    const mql = window.matchMedia(query)
    const onChange = () => setMatches(mql.matches)
    onChange()
    mql.addEventListener('change', onChange)
    return () => mql.removeEventListener('change', onChange)
  }, [query])  // ← query が変わるたびにリスナーを張り直す

  return matches
}

useMediaQuery はメディアクエリ文字列（"(max-width: 768px)" など）を受け取ってマッチ状態を返すフックです。

query が変わったとき、[] にしていると前の query に対するリスナーが残り続けます。[query] にすることで、query が変わると前のリスナーを外して（removeEventListener）新しい query のリスナーを張り直します。

パターン4：複数の依存値——「渡された値が変わるたびに再セットアップ」

// src/hooks/map/useHotelMarkers.ts（抜粋）
useEffect(() => {
  if (!map) return

  // syncOnce・各ハンドラはすべて effect 内部で定義（依存配列への追加不要）
  const syncOnce = (): void => { /* マーカーの差分更新処理 */ }
  const onMoveEnd = (): void => { syncOnce() }
  const onIdle = (): void => { syncOnce() }

  map.on('moveend', onMoveEnd)
  map.on('idle', onIdle)

  return () => {
    map.off('moveend', onMoveEnd)
    map.off('idle', onIdle)
    // マーカーを全削除
  }
}, [map, sourceId, idProp, thumbProp, nameProp, onPinClick])

useHotelMarkers はホテルのマーカーを地図に表示するフックです。map（Mapboxのインスタンス）・sourceId（データソースID）・各種設定を受け取ります。これらのどれかが変わったら、リスナーを外してマーカーを削除し、新しい設定で再セットアップが必要です。

onMoveEnd / onIdle は effect の内部で定義しているため依存配列には含めません。依存配列に書くのは「effect の外から来た値」だけです。effect 内部で作った変数・関数は毎回新しく作られるので、依存配列に入れる意味がありません。

なぜ `[]` にしてはいけない場面があるのか：stale closure 問題

[] を誤って使うと「stale closure（古い値を参照し続ける）」というバグが起きます。

// ❌ よくある間違い
function SearchBox({ query }: { query: string }) {
  const [result, setResult] = useState(null)

  useEffect(() => {
    fetch(`/api/search?q=${query}`)  // query を参照しているのに
      .then(r => r.json())
      .then(setResult)
  }, [])  // ← [] にしている → 最初の query 値を永遠に使い続ける
}

この例では query が変わっても effect が再実行されないため、初回マウント時の query 値でフェッチし続けます。

正しくは：

// ✅ 依存配列に query を入れる
useEffect(() => {
  fetch(`/api/search?q=${query}`)
    .then(r => r.json())
    .then(setResult)
}, [query])  // query が変わるたびにフェッチする

ESLint の `react-hooks/exhaustive-deps` を使う

どの値を依存配列に入れるべきか、人間が毎回判断するのは難しいです。ESLint の react-hooks/exhaustive-deps ルールを有効にすると、「依存配列に入れるべき値が漏れている」ときに警告してくれます。

Next.js 15 はデフォルトで flat config（eslint.config.mjs）を採用しており、next/core-web-vitals を継承するだけで react-hooks/exhaustive-deps がすでに有効になっています。

// eslint.config.mjs（Next.js 15 のデフォルト）
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({ baseDirectory: __dirname })

export default [
  ...compat.extends('next/core-web-vitals', 'next/typescript'),
]
// ↑ next/core-web-vitals に react-hooks/exhaustive-deps が含まれる

追加設定なしで警告が出るので、このルールが出ているときは // eslint-disable-line で黙らせる前に「本当に [] でいいのか」を一度考える習慣にしています。

「[] でいい理由」が説明できるなら [] で問題ありません。説明できないなら、依存配列に値を追加するのが正解です。

4パターンの整理

パターン	依存配列	使う場面
静的データのフェッチ	`[]`	URL固定・マウント時1回で十分（`useHotelsData`）
props が変わったら再フェッチ	`[url]`	URLが外から渡される（`useMapStyle`）
外部リスナーの張り直し	`[query]`	設定が変わったらリスナーを付け替え（`useMediaQuery`）
複数設定の再セットアップ	`[map, sourceId, ...]`	渡された全設定に追従（`useHotelMarkers`）

依存配列の選び方の判断基準は1つです。「effect 内で外部から来た値を参照しているか」。参照していたら依存配列に入れる。参照していなければ [] でいい。

実際に動いているサイトはこちらです。今回紹介したフックはすべてこのマップ機能の中で動いています。地図で探す｜しまなみ海道観光マップ｜しまなみ観光マップ

mojitonews.hateblo.jp

`Promise.all` で複数APIを並列fetchしつつ、1件失敗しても残りを使う設計——しまなみガイドのバス時刻表実装

2026-04-29T23:04:15+09:00

はじめに

しまなみ海道の観光ガイドサイトを個人で開発しています。マップ上にバス停を表示し、タップすると時刻表を見られる機能を実装したとき、Promise.all の使い方でひとつ判断が必要になりました。

このサイトはしまなみ海道エリアをカバーするため、複数のバス事業者の時刻表データを扱います。

中国バス
尾道バス
井笠バス
鞆鉄バス

4事業者それぞれの JSON ファイルを読み込んで、ひとつにマージして使います。このとき「4件を並列で取得したいが、1件が404でも残り3件は表示したい」という要件がありました。

左：バス停レイヤーOFF、右：バス停レイヤーON。4事業者のデータを並列フェッチし、取得できた分だけマージして表示している。

素直に Promise.all を書くと、1件でも失敗した瞬間に全体がエラーになります。この記事はその問題をどう解決したかの記録です。

`Promise.all` の「1件失敗で全滅」問題

まず基本動作の確認です。Promise.all は渡したすべての Promise が成功したときだけ解決します。

const results = await Promise.all([
  fetch('/data/chugokubus/stop-times.json').then(r => r.json()),
  fetch('/data/onomichibus/stop-times.json').then(r => r.json()),
  fetch('/data/ikasabus/stop-times.json').then(r => r.json()),
  fetch('/data/tomotetsubus/stop-times.json').then(r => r.json()),
])

4事業者のうち1事業者のファイルがまだ存在しなかった（404）場合、Promise.all 全体が reject されます。残り3事業者のデータも捨てられます。

今回はデータ追加を順次進めている途中で、まだファイルが存在しない事業者があります。「404のものは警告だけ出してスキップ、存在するものだけマージ」という動作が必要でした。

解決策：内側で catch して `null` を返す

解決策はシンプルです。各 fetch を個別の try/catch で囲み、失敗したら null を返す。Promise.all には「絶対に reject しない Promise」だけを渡します。

const results = await Promise.all(
  STOP_TIMES_SOURCES.map(async (src) => {
    try {
      const res = await fetch(src.url, { cache: 'force-cache' })

      if (res.status === 404) {
        console.warn(`[useBusTimetable] not found: ${src.label}`)
        return null  // ← 失敗ではなく null を返す
      }

      if (!res.ok) {
        console.warn(`[useBusTimetable] HTTP ${res.status}: ${src.label}`)
        return null
      }

      const json = await res.json() as BusStopTimetableByStop | null
      if (!json || typeof json !== 'object') {
        console.warn(`[useBusTimetable] invalid JSON: ${src.label}`)
        return null
      }

      return json  // ← 成功したものだけ返る

    } catch (e) {
      console.warn(`[useBusTimetable] error: ${src.label}`, e)
      return null  // ← ネットワークエラーなどもここで吸収
    }
  })
)
// results の型: (BusStopTimetableByStop | null)[]
// Promise.all 自体は絶対に reject しない

このパターンの肝は「Promise.all の外側に reject を漏らさない」ことです。各 async 関数が成功なら json、失敗なら null を返すことで、results は必ず (T | null)[] になります。

null を除いてマージする

results には成功した事業者のデータと null が混在しています。null を飛ばしながらマージします。

const merged: BusStopTimetableByStop = {}

for (const json of results) {
  if (!json) continue  // null はスキップ
  for (const [stopId, record] of Object.entries(json)) {
    merged[stopId] = record
  }
}

const hasAnyData = Object.keys(merged).length > 0

if (hasAnyData) {
  setBusTimetables(merged)
  setError(null)
} else {
  // 全事業者が失敗したときだけエラー表示
  setBusTimetables(null)
  setError('バス時刻表データの読み込みに失敗しました')
}

「全事業者が失敗した」ときだけ error をセットし、1件でも成功していればユーザーにはエラーを見せません。

`Promise.allSettled` との違い

同じことを Promise.allSettled でも書けます。

const results = await Promise.allSettled(
  STOP_TIMES_SOURCES.map(src => fetch(src.url).then(r => r.json()))
)

for (const result of results) {
  if (result.status === 'fulfilled') {
    // result.value を使う
  } else {
    // result.reason がエラー
  }
}

Promise.allSettled は ES2020 で追加されたメソッドで、全件が settle（成功または失敗）するまで待ち、{ status: 'fulfilled' | 'rejected', value/reason } の配列を返します。

今回 Promise.allSettled を使わなかった理由は2つです。

1つ目：ステータスコード単位の処理を細かく書きたかった。 Promise.allSettled の rejected はネットワークエラーやパースエラーをひとまとめにします。404 だけ warn で通過させて他のエラーコードは別処理、という分岐を書くには内側 catch のほうが素直でした。

2つ目：型が少し手間になる。 PromiseSettledResult<T> を受け取る場合、fulfilled かどうかをナローイングしてから value にアクセスする必要があります。内側 catch で T | null に統一しておくほうが後続処理がシンプルになりました。

どちらが正解というわけではありません。「fetch の成否だけを見る場合」なら Promise.allSettled のほうが意図が明確です。「ステータスコードごとに細かく分岐したい場合」は内側 catch パターンのほうが書きやすいと感じました。

クリーンアップ：`cancelled` フラグ

フックのクリーンアップも必要です。コンポーネントがアンマウントされた後に setState を呼ぶと React が警告を出します（React 18 以降は警告なしですが、後続処理が走り続けるのは無駄です）。

useEffect(() => {
  let cancelled = false

  ;(async () => {
    try {
      const results = await Promise.all(/* ... */)

      if (cancelled) return  // アンマウント済みなら setState しない

      // マージ・setState の処理
    } catch (e) {
      // fetch エラーは内側 try/catch で null を返すので、
      // ここに来るのは設計バグや setState 周りの想定外例外
      console.error('[useBusTimetable] unexpected error:', e)
      if (!cancelled) {
        setBusTimetables(null)
        setError('バス時刻表データの読み込みに失敗しました')
      }
    }
  })().catch(() => {})
  // outer try/catch が先にエラーを拾うため、
  // 末尾の .catch(() => {}) は「万が一 outer try/catch すら抜けた場合」の最後の安全網

  return () => {
    cancelled = true  // クリーンアップ時にフラグを立てる
  }
}, [])

AbortController を使ってフェッチ自体をキャンセルする方法もあります。今回は静的 JSON ファイルのフェッチで、キャンセルの恩恵が小さいため cancelled フラグだけにしています。重い API コールや長時間のストリームには AbortController が適しています。

`cache: 'force-cache'` で2回目以降を高速化

const res = await fetch(src.url, { cache: 'force-cache' })

force-cache はブラウザのHTTPキャッシュを最大限に利用するオプションです。一度ダウンロードした JSON はキャッシュから返るため、マップを開き直しても再ネットワーク通信が走りません。

バス時刻表は日次更新がなく、デプロイ時にのみ変わるファイルなので force-cache が適切です。リアルタイム性が必要なデータには no-store や no-cache を使います。

全体像

最終的なフックの構造をまとめるとこうなります。

useEffect
  └── async IIFE
        └── Promise.all([
              fetch A → try/catch → T | null,
              fetch B → try/catch → T | null,
              fetch C → try/catch → T | null,
              fetch D → try/catch → T | null,
            ])
            ↓ (T | null)[] が必ず返る
            null を除いてマージ
            ↓
            1件以上成功 → setBusTimetables(merged)
            全件失敗   → setError("失敗しました")
  return () => { cancelled = true }

呼び出し側はシンプルです：

const { busTimetables, error } = useBusTimetable()

busTimetables が null でなければマップのバス停タップ時に時刻表を表示し、null のときはバス停を非表示にします。

実際に動いているものはこちらで確認できます。マップ右上のレイヤー切替でバス停を有効にするとバス停ピンが表示されます。地図で探す｜しまなみ海道観光マップ｜しまなみ観光マップ

mojitonews.hateblo.jp

ライブラリなしでスワイプ対応 BottomSheet を React に実装した——CSSトランジションが「一発で動かない理由」と double rAF trick

2026-04-27T06:41:53+09:00

はじめに：なぜゼロから書いたのか

しまなみ海道の観光ガイドサイトを個人で開発しています。マップ上のスポットをタップすると詳細が表示されるモバイルUIを作るため、BottomSheet が必要になりました。

最初は Radix UI の <Dialog> や vaul（Drawer ライブラリ）を試しました。動きはします。ただ、使いながら「なぜこう動くのか」がわからないまま実装が進んでいく感覚に違和感がありました。

ライブラリを使えば1時間で終わる話を、わざわざ自分で書いた理由はそこです。ゼロから書いて中身を理解したかったのです。

結果として、CSSトランジションの落とし穴・スワイプ速度計算・アクセシビリティのお作法など、普段触れない領域を一通り掘り下げることになりました。この記事はその記録です。

完成品の機能

実装したコンポーネントの機能一覧です：

スワイプ（上→下）で閉じる（距離 or 速度の2段判定）
マウスドラッグでも閉じる（デスクトップ対応）
背景タップで閉じる
ESC キーで閉じる
開閉アニメーション（イージング・時間カスタマイズ可）
inert 属性によるアクセシビリティ
フォーカス復帰（閉じたら開く前にフォーカスしていた要素に戻る）
命令的 close（ref.requestClose()）
createPortal で document.body 直下にレンダリング

BottomSheet 本体の実装に外部ライブラリは使っていません（ダークモード判定にプロジェクト全体で使っている next-themes を参照しているのみです）。

実際に動いているものはこちらで確認できます。スポットをタップするとシートが開きます。地図で探す｜しまなみ海道観光マップ｜しまなみ観光マップ

今回ゼロから実装したBottomSheet。スポットをタップするとシートが下から滑り上がります

設計の出発点：`mounted` と `show` を分離する

アニメーションつきで「消える」コンポーネントを作るとき、素直に考えるとこうなります：

const [open, setOpen] = useState(false)
return open ? <Panel /> : null

これだと open=false にした瞬間 DOM からパネルが消えます。閉じるアニメーションは永遠に見えません。

解決策は 2つの状態を分けることです：

const [mounted, setMounted] = useState(false)  // DOMに存在するか
const [show, setShow]       = useState(false)  // CSSで見えているか

状態	mounted	show	画面に見える
閉じている	false	false	非表示（DOMなし）
開くアニメーション中	true	true	表示
閉じるアニメーション中	true	false	← translateY(100%)に向けてアニメ中
アニメ終了後	false	false	非表示（DOMなし）

show=false にして閉じるアニメーションが終わった後（transitionend イベントで検知）、はじめて mounted=false にして DOM から取り除きます。

const onPanelTransitionEnd = () => {
  if (!showRef.current) {
    finalizeClose()  // ここで mounted=false にする
  }
}

本題：なぜ「double rAF」が必要なのか

ここがこの実装で一番ハマった部分であり、記事の核心です。CSS トランジションを使ったことがある方なら、一度は同じ罠を踏んでいるはずです。

「シートを開く」処理を単純に書くとこうなります：

// ❌ アニメーションしない
setMounted(true)
setShow(true)

React がレンダリングしても、CSSトランジションは起動しません。

translateY(100%) → translateY(0) に変化させたいのですが、ブラウザから見ると「最初から translateY(0) な要素が突然 DOM に現れた」という扱いになります。スタート地点が存在しないのでアニメーションが発火しません。

1つの requestAnimationFrame では足りない

// ❌ これも動かないことがある
setMounted(true)
setShow(false)  // translateY(100%) でDOMに挿入
requestAnimationFrame(() => {
  setShow(true) // translateY(0) に変化 → アニメ開始…のはずが動かないことがある
})

React のステートバッチ処理の影響で、setMounted(true) と setShow(false) が同一レンダリングにまとめられ、ブラウザが「translateY(100%) の状態をペイントしたフレーム」が実際には挟まっていないことがあります。

double rAF + 強制フラッシュが解決する

setMounted(true)
setShow(false)            // [1] translateY(100%) でDOM生成
setEnableTransition(false) // トランジション無効で挿入

requestAnimationFrame(() => {                      // [2] 1フレーム後
  panelRef.current?.getBoundingClientRect()        // ← レイアウト強制フラッシュ
  requestAnimationFrame(() => {                    // [3] さらに1フレーム後
    setEnableTransition(true)                      // トランジション有効化
    setShow(true)          // translateY(0) に変化 → アニメ確実に起動
  })
})

getBoundingClientRect() を呼ぶことでブラウザに「レイアウト計算をいま確定しろ」と命令します（強制リフロー）。これにより translateY(100%) の状態が確実にペイントされ、次のフレームで translateY(0) に変化したときに「スタート地点から変化している」とブラウザが認識してトランジションが起動します。

enableTransition フラグを別で持っているのは、DOM 挿入の瞬間にトランジションが走って一瞬乱れるのを防ぐためです。ドラッグ中も同様に transitionProperty: "none" にして、指の動きにパネルが即座に追従するようにしています。

style={{
  transform: show ? "translateY(0)" : "translateY(100%)",
  transitionProperty:
    enableTransition && !draggingRef.current ? "transform" : "none",
  transitionDuration: `${duration}ms`,
}}

スワイプ判定：距離だけでは足りない

スワイプで閉じる判定を「何px以上下にドラッグしたか」だけにすると、ゆっくりちょっとだけ引っ張って離したときに閉じません。iOSのシートと同じ操作感にするには、速度（velocity）も見る必要があります。

const thresholdPx = 120        // 距離の閾値
const velocityThreshold = 0.6  // px/ms の速度閾値

const endDrag = () => {
  const dt = Math.max(1, performance.now() - lastTSRef.current) // 経過時間(ms)
  const dy = Math.max(0, lastYRef.current - dragStartYRef.current)
  const v = dy / dt  // 速度 (px/ms)

  if (dy > thresholdPx || v > velocityThreshold) {
    requestClose()  // 距離 OR 速度 のどちらかを満たしたら閉じる
  } else {
    setDragY(0)     // 閾値未満なら元の位置に戻す
  }
}

performance.now() を使うのは Date.now() より精度が高いためです（1ms 未満の解像度）。

「速度を見る」ことで「素早くフリック → 少ししか動いていなくても閉じる」という自然な操作感が生まれます。

マウスドラッグも同じロジックで対応しています。window にリスナーを付けているのは、ドラッグ中にカーソルがパネル外に出ても追従させるためです：

onMouseDown={(e) => {
  if (e.button !== 0) return
  beginDrag(e.clientY)
  const onMove = (ev: MouseEvent) => moveDrag(ev.clientY)
  const onUp = () => {
    endDrag()
    window.removeEventListener("mousemove", onMove)
    window.removeEventListener("mouseup", onUp)
  }
  window.addEventListener("mousemove", onMove)
  window.addEventListener("mouseup", onUp)
}}

`inert` 属性でアクセシビリティを担保する

「閉じるアニメーション中のシート」はDOMに残っています。この間にスクリーンリーダーやキーボードからアクセスされると困ります。

HTML の inert 属性を使うと、その要素とすべての子孫を一括で「操作不可・フォーカス不可・読み上げ不可」にできます：

useEffect(() => {
  const overlayEl = overlayRef.current
  if (!overlayEl) return

  if (!show) {
    overlayEl.setAttribute("inert", "")  // 閉じ中は非活性
  } else {
    overlayEl.removeAttribute("inert")   // 開いているときは活性
  }
}, [show])

以前は aria-hidden + 全子孫に tabindex="-1" を手動で設定する必要がありましたが、inert 1つで同等のことができます。2023年に Firefox が対応したことで、主要ブラウザがすべて揃いました。

フォーカス復帰

WAI-ARIA のダイアログパターンでは、モーダルを閉じたときに開く前にフォーカスしていた要素にフォーカスを戻すことが求められています。

実装は単純で、開くタイミングで document.activeElement を保存しておき、閉じたときに focus() を呼ぶだけです：

// 開くとき：フォーカス元を保存
const prev = document.activeElement as HTMLElement | null
if (prev && !panelRef.current?.contains(prev)) {
  restoreFocusRef.current = prev
}

// 閉じたとき（finalizeClose 内）：フォーカスを戻す
if (restoreFocusRef.current) {
  try { restoreFocusRef.current.focus() } catch {}
  restoreFocusRef.current = null
}

開くときは [data-autofocus] 属性がある要素か、フォーカス可能な最初の要素に自動フォーカスします：

const target =
  panelRef.current?.querySelector<HTMLElement>("[data-autofocus]") ||
  panelRef.current?.querySelector<HTMLElement>(
    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
  )
target?.focus()

`forwardRef` + `useImperativeHandle` で命令的 close

このシートは open props で開閉を制御しますが、「外部から close を呼びたい」ケースがあります（例：フォーム送信完了後に閉じるなど）。

useImperativeHandle で requestClose を外部に公開します：

export type SheetHandle = { requestClose: () => void }

const Sheet = forwardRef<SheetHandle, SheetProps>(function Sheet(props, ref) {
  const requestClose = useCallback(() => {
    setShow(false)
    closeTimerRef.current = window.setTimeout(finalizeClose, closeMs + 80)
  }, [closeMs, finalizeClose])

  useImperativeHandle(ref, () => ({ requestClose }), [requestClose])
})

使う側：

const sheetRef = useRef<SheetHandle>(null)

// 任意のタイミングで
sheetRef.current?.requestClose()

return <Sheet ref={sheetRef} open={open} onClose={onClose} />

`createPortal` でスタッキングコンテキストを脱出する

シートは position: fixed で画面全体に重ねる必要がありますが、コンポーネントツリーの深い場所に置かれると、親要素の transform や overflow: hidden によってクリッピングされることがあります。

createPortal で document.body 直下にレンダリングすることでこれを回避します：

const overlayRootRef = useRef<HTMLElement | null>(null)
useEffect(() => {
  overlayRootRef.current = document.body  // SSR後に取得
}, [])

if (!mounted || !overlayRootRef.current) return null

return createPortal(overlay, overlayRootRef.current)

useEffect 内で取得しているのは SSR（サーバーサイドレンダリング）時に document が存在しないためです。

まとめ

問題	解決策
CSSトランジションが動かない	double rAF + `getBoundingClientRect()` 強制フラッシュ
閉じアニメーションが見えない	`mounted` / `show` を2状態で管理し `transitionend` 後にDOMを消す
速度フリックで閉じない	`velocity = dy / dt` の2段判定
アニメ中にフォーカスが当たる	`inert` 属性で一括非活性化
閉じた後にフォーカスが迷子	`activeElement` を保存して復帰
親の `transform` に干渉される	`createPortal` で `document.body` に脱出

ライブラリを使えば確かに速く実装できます。ただ、ゼロから書くと「なぜ動くのか」がわかります。特に double rAF は、知っておくと他のアニメーション実装でも繰り返し使える知識です。

実際に動いているサイトはこちらです。マップのスポットをタップするとシートが開きます。地図で探す｜しまなみ海道観光マップ｜しまなみ観光マップ

mojitonews.hateblo.jp

useCallback が必要な場面・不要な場面——「とりあえず入れとく」はパフォーマンスを悪化させる

2026-04-24T07:30:42+09:00

しまなみ海道の観光サイト勉強も兼ねて作り始めたとき、カスタムフックを書くたびに useCallback を巻いていました。

「関数の再生成を防ぐんでしょ？　入れておいて損はないよね」——そう思っていました。

実際には、不要な useCallback はコードを読みにくくするだけでなく、パフォーマンスをわずかに悪化させることもあります。どこで使うべきで、どこでは要らないのかを整理しました。

useCallback がやっていること

const handleClick = useCallback(() => {
  doSomething();
}, []);

useCallback はメモ化された関数を返します。依存配列の中身が変わらない限り、前回レンダリング時と同じ関数参照を返し続けます。

逆に言うと、それだけです。関数の中身を「高速化」するわけではありません。

入れなくていい場面

1. ネイティブ DOM 要素への onClick

// ❌ useCallback は不要
const handleClick = useCallback(() => {
  setIsOpen(true);
}, []);

return <button onClick={handleClick}>開く</button>;

<button> などのネイティブ要素は React.memo で囲まれていません。関数参照が毎回変わっても再レンダリングは起きません。

// ✅ これで十分
return <button onClick={() => setIsOpen(true)}>開く</button>;

2. コンポーネント内だけで使う関数

// ❌ 不要
const formatLabel = useCallback((name: string) => {
  return `${name}（スポット）`;
}, []);

他のコンポーネントに渡さない、useEffect の依存にもならない関数は、メモ化しても意味がありません。

入れる意味がある場面

1. React.memo で囲んだ子コンポーネントへ渡すとき

const Child = React.memo(({ onClose }: { onClose: () => void }) => {
  return <button onClick={onClose}>閉じる</button>;
});

function Parent() {
  // ❌ useCallback なし → 毎レンダリングで新しい関数参照 → memo が意味をなさない
  const handleClose = () => setOpen(false);

  // ✅ useCallback あり → 参照が安定 → Child が不要に再レンダリングしない
  const handleClose = useCallback(() => setOpen(false), []);

  return <Child onClose={handleClose} />;
}

React.memo は props の参照で前回と比較します。関数を毎回新しく作ると、中身が同じでも「変わった」と判断されて再レンダリングが走ります。

2. 別の useCallback の依存配列に入れるとき

useCallback の依存配列に入るケースは useEffect だけとは限りません。別の useCallback から呼ばれる場合も同じ理由で参照の安定が必要になります。

このサイトの useHotelMapClickHandler.ts はその実例です。フック自体は handleHotelClick を返り値として返し、呼び出し側の PowerMap.tsx で別の useCallback の依存配列に入っています。

// PowerMap.tsx
const handleClick = useCallback(
  (e) => {
    handleHotelClick(e); // ← useHotelMapClickHandler が返した関数
  },
  [activeLayer, closeHotelPopup, handleHotelClick, mapRef], // ← 依存配列に入っている
);

handleHotelClick の参照が毎レンダリングで変わると、handleClick も毎回再生成されます。handleClick がさらに別の依存配列に入っていれば、その連鎖が続きます。参照を安定させることで、この再生成の連鎖を断ち切れます。

React.memo との組み合わせ（上）と useCallback の依存配列チェーン（下）——どちらも関数参照を安定させる必要がある場面です。

3. useEffect の依存チェーンが連なるとき

Sheet.tsx（ボトムシート）では finalizeClose と requestClose を useCallback で定義しています。

const finalizeClose = useCallback(() => {
  if (showRef.current) return;
  if (closeTimerRef.current !== null) {
    window.clearTimeout(closeTimerRef.current);
    closeTimerRef.current = null;
  }
  // ...
}, [onClose]);

構造はこうなっています。

finalizeClose → useEffect の依存配列に入っている
requestClose → finalizeClose を内部で呼び、さらに別の useEffect の依存配列に入っている
requestClose → useImperativeHandle にも渡している

useImperativeHandle で公開しているのはその延長であって、主な理由は useEffect の依存チェーンの安定化です。finalizeClose の参照が毎回変わると、それを依存に持つ requestClose も再生成され、さらにその useEffect が毎回再実行される連鎖が起きます。

useCallback 自体にコストがある

useCallback はタダではありません。

依存配列の値を毎レンダリングで比較する処理が走る
前回の関数参照をメモリに保持し続ける

関数の生成コスト（ほぼゼロに近い）より、メモ化のオーバーヘッドが上回るケースもあります。「入れておけば安全」ではなく、入れる理由がある場面でだけ使うのが正しい判断です。

判断フローチャート

この関数、useCallback 巻く？
│
├─ React.memo を使った子コンポーネントに渡す？
│   YES → 巻く
│
├─ useEffect の依存配列に入っている？
│   YES → 巻く
│
├─ 別の useCallback や useEffect の依存配列に入る？
│   YES → 巻く（依存チェーンの連鎖を断ち切る）
│
└─ 上記以外
    NO → 巻かない

まとめ

場面	useCallback
`<button onClick={fn}>` などネイティブ要素	不要
コンポーネント内だけで使う関数	不要
`React.memo` の子コンポーネントへ渡す	必要
`useEffect` の依存配列に入る	必要
別の `useCallback` の依存配列に入る	必要
`useEffect` 依存チェーンの末端で `useImperativeHandle` にも渡す	必要

「とりあえず入れとく」のをやめてから、カスタムフックのコードが読みやすくなりました。依存配列に useCallback が並んでいたら、「この関数は子や Effect から参照される重要な関数だ」という意味になります。ノイズがなくなると、コードが語れる情報量が増えます。

mojitonews.hateblo.jp

layout.tsx と page.tsx の違いがわからなかった——本サイトを作って理解できたこと

2026-04-22T09:41:11+09:00

はじめに

Next.js の App Router を使い始めてすぐ、ファイル構成で悩みました。

page.tsx と layout.tsx をどちらに何を書くのか、最初はまったくわかりませんでした。「とりあえず全部 page.tsx に書けばいいんじゃないか」と思ったこともあります。

本サイト（しまなみ海道の観光ガイドサイト）を作りながら理解できたことをまとめます。

1分でわかる結論

layout.tsx は1つだけ。page.tsx はページの数だけあります。

ファイル	役割	毎ページ表示されるか
`layout.tsx`	複数ページをまたいで共通して表示する枠組み	される（再レンダリングされない）
`page.tsx`	そのURLにアクセスしたときだけ表示される内容	そのページのみ

「layout.tsx は額縁、page.tsx は中身の絵」というイメージが一番近いです。

ファイル構成を見てみる

本サイトの src/app/ ディレクトリはこんな構成です。

src/app/
  layout.tsx              ← すべてのページ共通のレイアウト
  page.tsx                ← トップページ（/）
  spots/
    page.tsx              ← スポット一覧（/spots）
    [spotId]/
      page.tsx            ← スポット詳細（/spots/猫の細道 など）
  hotels/
    page.tsx              ← ホテル一覧（/hotels）
    [hotelNo]/
      page.tsx            ← ホテル詳細（/hotels/12345 など）
  map/
    page.tsx              ← 地図ページ（/map）
  about/
    page.tsx              ← サイト概要（/about）

layout.tsx は1つだけです。page.tsx はページの数だけあります。

layout.tsx——全ページに共通する「枠」

本サイトの src/app/layout.tsx の中身（簡略版）はこうなっています。

// src/app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ja">
      <body>
        <ClientProviders>
          {children}  {/* ここに各ページの内容が入る */}
        </ClientProviders>
      </body>
    </html>
  );
}

children の部分に各ページの page.tsx の内容が差し込まれます。

実際の layout.tsx でやっていることは4つです。

フォント設定（Noto Sans JP・Noto Serif JP を Google Fonts から読み込む）
Google Analytics タグの設置（すべてのページで計測したいため）
Google AdSense タグの設置（同上）
ClientProviders でアプリ全体を包む（Zustand・TanStack Query・テーマの初期化）

これらはどのページでも必要なので layout.tsx に書きます。「トップページだけ」「スポット詳細だけ」に必要なものは layout.tsx には書きません。

page.tsx——そのURLの「内容」

page.tsx はURLに対応する内容だけを書きます。

トップページ（src/app/page.tsx）は注目スポット一覧・エリアナビゲーション・サイクリングガイドバナーを表示します。これは / にアクセスしたときだけ見せたいものなので page.tsx に書きます。

スポット詳細ページ（src/app/spots/[spotId]/page.tsx）はこのような構造です。

// src/app/spots/[spotId]/page.tsx
export default async function SpotDetailPage({ params }: PageProps) {
  const { spotId } = await params;
  const spot = getSpotById(spotId);

  if (!spot) notFound();

  return (
    <main>
      <Breadcrumb items={[...]} />
      <SpotDetailView spot={spot} articleContent={articleContent} />
    </main>
  );
}

params.spotId に neko-no-hosomichi が入れば猫の細道のページ、ohyamazumi-jinjya が入れば大山祇神社のページが表示されます。URLが変わるたびに page.tsx だけが切り替わります。layout.tsx はそのまま残ります。

metadataもどちらに書くかで意味が変わる

Next.js では metadata オブジェクトをエクスポートするとページタイトルや説明文が設定できます。

layout.tsx に書く metadata はサイト全体のデフォルト値になります。

// src/app/layout.tsx
export const metadata: Metadata = {
  title: {
    default: "しまなみ観光マップ",         // デフォルトタイトル
    template: "%s｜しまなみ観光マップ",    // 各ページのタイトルにサフィックスを付ける
  },
  description: "尾道・今治・しまなみ海道エリアの...",
};

template: "%s｜しまなみ観光マップ" の %s は各 page.tsx が設定したタイトルに置き換わります。スポット詳細ページが title: "猫の細道" と設定すると、ブラウザのタブには「猫の細道｜しまなみ観光マップ」と表示されます。

page.tsx に書く metadata はそのページ専用の値です。

// src/app/spots/[spotId]/page.tsx
export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
  const spot = getSpotById((await params).spotId);
  return {
    title: spot.seoTitle ?? `${spot.name}｜観光スポット`,
    description: spot.shortDescription,
    // ...
  };
}

スポットによって内容が変わるので generateMetadata（関数形式）を使っています。静的なページは export const metadata = { ... } で書けます。

generateStaticParams——動的ページを静的に生成する

[spotId] のように角括弧で囲んだディレクトリは動的ルートです。URLが無数に作れる反面、ビルド時にどのURLが存在するかをNext.jsに教えてあげる必要があります。それが generateStaticParams です。

// src/app/spots/[spotId]/page.tsx
export async function generateStaticParams() {
  const spots = getAllSpots();
  return spots.map((spot) => ({ spotId: spot.id }));
}

getAllSpots() で全スポットを取得し、それぞれの id（neko-no-hosomichi など）を返します。Next.jsはビルド時にこのリストをもとに全スポット分のHTMLを事前生成します。

これは page.tsx にしか書かない（書けない）ものです。

整理すると

layout.tsx に書くもの - <html> / <body> タグ - フォント設定 - 全ページ共通のスクリプト（Analytics・AdSense） - 全ページ共通のプロバイダー（Context・QueryClient・テーマ） - サイト全体のデフォルト metadata

page.tsx に書くもの - そのURLだけが表示するUI - そのページ専用の metadata - 動的ルートの generateStaticParams

最初は「どちらに書くか」が判断できませんでしたが、「このコードは全ページで必要か、このページだけか」を考えるだけで自然に分かれていきました。

本サイト（Next.js + TypeScript + MDX）を作りながら学んでいます。

mojitonews.hateblo.jp

カスタムフックで「どこで何が動くか」を整理——useIsMobile / useGeolocate / useCloseAll の設計

2026-04-21T10:51:56+09:00

はじめに

左がデスクトップ、右がモバイルの表示です。ナビゲーションの構成やボタンの配置が変わります。

React を書いていると、コンポーネントの中にロジックが増えてきます。useEffect が2つ、useState が3つ、コールバックが4つ……気づいたら何をしているファイルなのかわからなくなっていました。

カスタムフックはこの問題を解決する手段です。「どこで何が動くか」をフックという単位に切り出すことで、コンポーネントは「何を表示するか」だけに集中できます。

ただ、カスタムフックを「なぜ作るか」は一つではありませんでした。本サイトを作りながら、目的が全然違う3種類のカスタムフックが生まれました。

useIsMobile——ブラウザAPIをラップするパターン

なぜ作ったか

地図画面はモバイルとデスクトップで表示が大きく変わります。パネルの開き方、ドロワーの有無、ボタンの配置——これらをJavaScriptで制御する必要がありました。

CSSの @media だけでは足りない場面があります。「モバイルかどうか」をコンポーネントの中で if で分岐したいとき、window.matchMedia を直接書くと毎回SSR対応・イベントリスナーの登録・クリーンアップが必要になります。これをまとめたのが useIsMobile です。

コード

// src/hooks/useIsMobile.ts
import { useEffect, useState } from "react";

export function useMediaQuery(query: string) {
  const [matches, setMatches] = useState(false);

  useEffect(() => {
    if (typeof window === "undefined") return; // SSR対策
    const mql = window.matchMedia(query);
    const onChange = () => setMatches(mql.matches);
    onChange(); // 初回判定
    mql.addEventListener?.("change", onChange);
    return () => mql.removeEventListener?.("change", onChange);
  }, [query]);

  return matches;
}

/** モバイル判定。デフォルト: max-width 768px */
export function useIsMobile(maxWidth = 768) {
  return useMediaQuery(`(max-width: ${maxWidth}px)`);
}

ポイント

useMediaQuery と useIsMobile を2段構えにした理由

useMediaQuery は汎用的な「メディアクエリをstateにする」フックです。useIsMobile はそれに「768px以下をモバイルとみなす」というこのプロジェクトのルールを乗せた薄いラッパーです。将来「タブレット判定（1024px以下）も欲しい」となったとき、useMediaQuery を再利用すれば済みます。

typeof window === "undefined" のチェック

Next.js はサーバーサイドでコンポーネントを実行するため、window が存在しない環境で window.matchMedia を呼ぶとエラーになります。useEffect の中でチェックすることで、サーバーでは何もせずスキップします。

初期値が false の理由

useState(false) で始まるのは「最初はモバイルでないとみなす」という選択です。useEffect は初回レンダリングの後に走るため、サーバーとクライアントで初期値が一致している必要があります。window が存在しないサーバーでは「モバイルかどうか不明」なので false が安全な初期値です。

使い方

// Header.tsx・RightPane.tsx での実際の使い方
// ブレークポイントは引数で渡せる。1025px以下をモバイルとみなす
const isMobile = useIsMobile(1025);

return isMobile ? <MobileLayout /> : <DesktopLayout />;

コンポーネントの中はこれだけです。window.matchMedia のことは何も知らなくていいです。ブレークポイントは引数で渡せるので、場面に応じて変えられます。

useGeolocate——コールバックとstateをセットにするパターン

なぜ作ったか

本サイトの地図では、ユーザーが「現在地ボタン」を押すと自分の位置を地図上にピンで表示します。この機能はMapboxの GeolocateControl というコントロールを使っています。

GeolocateControl は「位置情報が取れたとき」と「エラーが起きたとき」のコールバックを受け取ります。このコールバックの中でstateを更新する必要があります。

位置情報取得成功 → myPos・myAccuracy を更新 → 地図をその位置にフォーカス
位置情報取得失敗 → errMsg を更新 → エラーを表示

この「コールバック＋それに対応するstate」がセットになったのが useGeolocate です。

コード

// src/hooks/useGeolocate.ts
import { useCallback, useState } from "react";

export function useGeolocate(opts?: {
  onFocus?: (loc: { lng: number; lat: number }, accuracy?: number) => void;
}) {
  const [myPos, setMyPos] = useState<{ lng: number; lat: number }>();
  const [myAccuracy, setMyAccuracy] = useState<number | undefined>();
  const [errMsg, setErrMsg] = useState<string | null>(null);

  const onError = useCallback((e: GeolocationPositionError) => {
    setErrMsg(e.message ?? "現在地を取得できませんでした");
  }, []);

  const onGeolocate = useCallback(
    (pos: GeolocationPosition) => {
      const { latitude, longitude, accuracy } = pos.coords;
      setErrMsg(null);
      const loc = { lng: longitude, lat: latitude };
      setMyPos(loc);
      setMyAccuracy(accuracy);
      opts?.onFocus?.(loc, accuracy); // 地図をその位置にフォーカスする（外から渡す）
    },
    [opts]
  );

  return { myPos, myAccuracy, errMsg, setErrMsg, onError, onGeolocate };
}

ポイント

navigator.geolocation を直接呼ばない

このフックは navigator.geolocation.getCurrentPosition() を自分では呼びません。Mapboxの GeolocateControl が位置情報の取得を担い、結果をコールバックとして渡してきます。このフックは「結果を受け取ったらどう処理するか」だけを持っています。

useCallback を使う理由

onGeolocate と onError を useCallback で包んでいるのは、これらをMapboxのイベントリスナーに渡すためです。関数が毎回再生成されると、リスナーの付け替えが無駄に走ります。

opts?.onFocus——地図フォーカスは外から渡す

位置情報が取れたとき、地図をその座標にアニメーションで移動させたいです。しかし地図のインスタンス（Mapboxの map オブジェクト）はこのフックの外にあります。「地図を動かす処理」を onFocus として外から受け取ることで、フック自体は地図のことを知らなくて済みます。

使い方

const mapRef = useRef<mapboxgl.Map | null>(null);

const { myPos, myAccuracy, errMsg, onError, onGeolocate } = useGeolocate({
  onFocus: (loc) => {
    mapRef.current?.flyTo({ center: [loc.lng, loc.lat], zoom: 15 });
  },
});

// react-map-gl の GeolocateControl に props として渡す（PowerMap.tsx）
<GeolocateControl
  onError={onError}
  onGeolocate={onGeolocate}
/>

useCloseAll——複数storeの横断操作をまとめるパターン

なぜ作ったか

本サイトの地図画面には4種類のレイヤーがあります。ホテル・グルメ・観光スポット・バス停です。それぞれ選択状態をZustandのstoreで管理しています。

地図の背景をタップしたとき、開いているパネルをすべて閉じる必要があります。最初はコンポーネントの中に直接書いていました。

// 最初はコンポーネントの中にこれを直接書いていた
setSelectedHotelNo(null);
setSelectedSpot(null);
setSelectedRestaurant(null);
setSelectedBusStop(null);
// さらにMapboxのpopupも閉じる...

「閉じる」という操作が4箇所以上に散らばっていて、1つ追加するたびに全部の呼び出し元を直さなければなりませんでした。これを1つにまとめたのが useCloseAll です。

コード

// src/hooks/useCloseAll.ts
"use client";

import { useCallback } from "react";
import { useHotelStore } from "@/store/useHotelStore";
import { useSpotStore } from "@/store/useSpotStore";
import { useRestaurantStore } from "@/store/useRestaurantStore";
import { useBusStore } from "@/store/useBusStore";

export function useCloseAll() {
  return useCallback(() => {
    // ホテルを完全リセット
    const hs = useHotelStore.getState();
    hs.closeDetail?.();
    hs.clearSelectedHotel?.();
    hs.setSelectedHotelNo?.(null);
    useHotelStore.setState({ selectedHotelNo: null, isPaneOpen: false, isSheetOpen: false });

    // 観光スポットを完全クリア
    const ss = useSpotStore.getState();
    ss.clearSelectedSpot?.();
    ss.closeSpotPane?.();
    useSpotStore.setState?.({ selectedSpot: null, isPaneOpen: false });

    // グルメを完全クリア
    const rs = useRestaurantStore.getState();
    rs.clearSelectedRestaurant?.();
    useRestaurantStore.setState?.({ selectedRestaurant: null });

    // バス停を完全クリア
    const bs = useBusStore.getState();
    bs.clearSelectedBusStop?.();
    useBusStore.setState?.({ selectedBusStop: null });

    // MapboxのローカルPopupも閉じる（storeの外にあるため）
    if (typeof window !== "undefined") {
      window.dispatchEvent(new Event("map:close-all-popups"));
    }
  }, []);
}

※実際のコードは store 側の API が複数形式に対応するため型まわりが複雑ですが、やっていることはこれがすべてです。

ポイント

store.getState() でReactの外からstateを読む

Zustandは useHotelStore.getState() でReactのレンダリングサイクルの外からstateを読み書きできます。useCallback の中でstoreの値を操作するときに使います。

storeのメソッド + setState の二重呼び出し

hs.closeDetail?.() と useHotelStore.setState(...) を両方呼んでいます。「storeが提供しているメソッドを優先して呼び、さらに直接stateも上書きする」という念押しです。storeのAPIが途中で変わったときも、どちらかは効くようにするための防御的なコードです。

window.dispatchEvent でMapboxのPopupを閉じる

Mapboxの地図上に表示しているpopupは、Reactのstoreの外で管理されています。storeをいくら更新してもpopupは消えません。window.dispatchEvent(new Event("map:close-all-popups")) でカスタムイベントを発火し、地図コンポーネント側で addEventListener("map:close-all-popups", ...) でキャッチして閉じるようにしています。

使い方

const closeAll = useCloseAll();

// ロゴをクリックしてホームに戻るとき（Header.tsx）
const handleLogoClick = () => {
  closeAll();
};

// 閉じるボタンを押したとき（RightPane.tsx・RestaurantDetailView.tsx）
<button onClick={closeAll}>閉じる</button>

どこから呼んでも closeAll 一発で全部閉じます。

3つを並べてわかったこと

フック	切り出した理由
`useIsMobile`	ブラウザAPIの扱いを毎回書きたくなかった
`useGeolocate`	コールバックとstateがセットで動くので一緒にしたかった
`useCloseAll`	複数の場所に散らばった操作を1箇所にまとめたかった

「カスタムフックを作る理由」は一つではありませんでした。ブラウザAPIのラップ、関連するコールバックとstateの束、横断的な操作のまとめ——目的が違えば、フックの形も変わります。

共通しているのは「コンポーネントに書き続けると辛くなった」という経験から生まれていることです。最初から設計したわけではなく、コンポーネントが重くなってから切り出しました。

本サイト（Next.js + TypeScript + MDX）を作りながら学んでいます。

mojitonews.hateblo.jp

自前キャッシュをTanStack Queryに移行した——176行のコードが82行に

2026-04-21T09:56:29+09:00

はじめに

本サイトの地図画面には、ホテルのマーカーをタップすると詳細情報をAPIから取得して表示する機能があります。

この機能、最初は自分でキャッシュを実装していました。同じホテルを2回タップしたときにAPIを叩かないように、Map オブジェクトを使ってメモリに保存していたのです。

動いてはいました。でも、コードを見るたびに「これ、本当に正しく動いているのか？」という不安がありました。今回 TanStack Query（React Query）に移行したら、そのコードが丸ごと消えました。

移行前のコード——自前で全部やっていた

src/hooks/hotels/useHotelDetail.ts の中身です。

// メモリキャッシュ（同じホテル再閲覧の高速化）
const memoryCache = new Map<number, HotelDetail>();
// 同時リクエストの集約
const inFlight = new Map<number, Promise<HotelDetail>>();

ファイルのトップレベルに2つの Map が定義されていました。

memoryCache は「一度取得したホテルの詳細データを保存しておく箱」です。同じホテルをタップしたとき、まずここを見てデータがあればAPIを叩かずに返します。

inFlight は「今まさに進行中のリクエスト」を保存する箱です。同じホテルに対して2つのリクエストが同時に走るのを防ぐための仕組みで、「すでにリクエスト中なら、その Promise を共有する」という処理をしていました。

export function useHotelDetail(hotelNo: number | null) {
  const [detail, setDetail] = useState<HotelDetail | null>(null);
  const [error, setError] = useState<Error | null>(null);
  const [loading, setLoading] = useState<boolean>(false);

  // 競合回避用に最新 hotelNo を保持
  const latestNoRef = useRef<number | null>(null);
  useEffect(() => {
    latestNoRef.current = hotelNo;
  }, [hotelNo]);

  useEffect(() => {
    // キャッシュ命中なら即返す
    const cached = memoryCache.get(normalizedNo);
    if (cached) {
      setDetail(cached);
      setLoading(false);
      return;
    }

    const controller = new AbortController();

    // 進行中の同一リクエストがあればそれを共有
    const existing = inFlight.get(normalizedNo);
    const p = existing ?? fetchDetail(normalizedNo, signal);
    if (!existing) inFlight.set(normalizedNo, p);

    p.then((data) => {
      if (latestNoRef.current !== normalizedNo) return; // 競合チェック
      memoryCache.set(normalizedNo, data);
      setDetail(data);
      setLoading(false);
    })
    .catch((e) => {
      if (signal.aborted) return;
      if (latestNoRef.current !== normalizedNo) return;
      setError(e instanceof Error ? e : new Error(String(e)));
      setLoading(false);
    })
    .finally(() => {
      if (!existing) inFlight.delete(normalizedNo);
    });

    return () => controller.abort();
  }, [normalizedNo]);
}

やっていることを整理すると：

キャッシュ（memoryCache）にデータがあれば即返す
なければ inFlight を確認して、進行中なら Promise を共有、なければ新しくfetch
完了したら memoryCache に保存
latestNoRef でホテルを切り替えたときの競合（古いデータが後から届く問題）を防ぐ
AbortController でアンマウント時のリクエストをキャンセル

動いてはいましたが、コードが複雑で「この latestNoRef のチェック、本当に全パスで正しいか？」という不安が常にありました。

インストール

npm install @tanstack/react-query

これだけです。

Step 1：QueryClientProvider をルートに追加

TanStack Query はアプリ全体で QueryClient を共有します。このプロジェクトでは src/components/ClientProviders.tsx にすべての Provider が集まっているので、ここに追加しました。

変更前

import { ThemeProvider } from "next-themes";

export default function ClientProviders({ children }) {
  return (
    <ThemeProvider ...>
      {children}
    </ThemeProvider>
  );
}

変更後

import { useState } from "react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ThemeProvider } from "next-themes";

export default function ClientProviders({ children }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            staleTime: 1000 * 60 * 5, // 5分
            retry: 1,
          },
        },
      }),
  );

  return (
    <QueryClientProvider client={queryClient}>
      <ThemeProvider ...>
        {children}
      </ThemeProvider>
    </QueryClientProvider>
  );
}

なぜ useState で生成するのか

QueryClient をコンポーネントの外で const queryClient = new QueryClient() と書くと、モジュールが読み込まれたタイミングで1度だけ生成されます。useState(() => new QueryClient()) にしておくと「コンポーネントが初回レンダリングされたときに1度だけ生成する」ことが保証されます。SSRで複数インスタンスが生まれる問題を防ぐための書き方です。

staleTime: 1000 * 60 * 5 とは

「5分間はキャッシュを新鮮とみなし、再fetchしない」という設定です。ホテルの詳細情報は数分で変わるものではないので、5分はちょうどよい値でした。

Step 2：useHotelDetail.ts を useQuery に書き換え

ここがメインの変更です。

変更前

// ファイルトップレベルの自前キャッシュ
const memoryCache = new Map<number, HotelDetail>();
const inFlight = new Map<number, Promise<HotelDetail>>();

export function useHotelDetail(hotelNo: number | null) {
  const [detail, setDetail] = useState<HotelDetail | null>(null);
  const [error, setError] = useState<Error | null>(null);
  const [loading, setLoading] = useState<boolean>(false);
  const latestNoRef = useRef<number | null>(null);

  // ...キャッシュ確認・inFlight管理・競合チェック・AbortControllerの手動管理
}

変更後

import { useMemo } from "react";
import { useQuery, useQueryClient } from "@tanstack/react-query";

export function useHotelDetail(hotelNo: number | null) {
  const queryClient = useQueryClient();

  const normalizedNo = useMemo(() => {
    if (hotelNo == null) return null;
    const n = Number(hotelNo);
    return Number.isFinite(n) ? n : null;
  }, [hotelNo]);

  const { data: detail, isLoading: loading, error, refetch } = useQuery({
    queryKey: ["hotelDetail", normalizedNo],
    queryFn: ({ signal }) => fetchDetail(normalizedNo!, signal),
    enabled: normalizedNo != null,
  });

  const refresh = async () => {
    if (normalizedNo == null) return;
    await queryClient.invalidateQueries({ queryKey: ["hotelDetail", normalizedNo] });
    await refetch();
  };

  return {
    detail: detail ?? null,
    loading,
    error: error instanceof Error ? error : null,
    refresh,
  };
}

削除されたコードと、その代わりに何が担っているかの対応です。

削除したコード	TanStack Query が代わりに担うこと
`memoryCache = new Map()`	`queryKey` ごとに自動でキャッシュ。`staleTime` 内なら再fetchしない
`inFlight = new Map()`	同じ `queryKey` への同時リクエストを自動で1本に集約
`latestNoRef`	`queryKey` が変わると自動で前のクエリを無効化
`AbortController` の手動管理	`queryFn` の引数 `signal` に自動で渡される

fetchDetail 関数自体も少し変わっています。移行前は第3引数 opts で cache: "no-store" を切り替える仕組みがありました。

// 移行前
async function fetchDetail(
  hotelNo: number,
  signal?: AbortSignal,
  opts?: FetchDetailOptions, // ← refresh() 時に no-store を渡すための引数
): Promise<HotelDetail> {
  const res = await fetch(`...`, {
    cache: opts?.noStore ? "no-store" : "default",
    signal,
  });
}

移行後は refresh() が invalidateQueries でキャッシュを無効化するようになったため、no-store を渡す必要がなくなり、opts ごと削除できました。signal の受け取り方も queryFn の引数から受け取る形に変わっています。

// 変更後（queryFn の引数から signal を受け取る）
queryFn: ({ signal }) => fetchDetail(normalizedNo!, signal),

また、useQuery が返す値の名前は isLoading ですが、既存のコンポーネントは loading という名前で受け取っています。分割代入時に読み替えることで、呼び出し側のコンポーネントは一切変更不要でした。

const { data: detail, isLoading: loading, error, refetch } = useQuery({...});

動作確認

X-Vercel-Cache: STALE はキャッシュはあるが期限切れと判断され、再fetchが走った状態です。次のタップでは HIT になりキャッシュから即返ります

ブラウザの DevTools（Network タブ）を開いてホテルマーカーをタップします。/api/rakuten/hotel-detail?hotelNo=xxxxx へのリクエストが1回走ります。

同じマーカーをもう一度タップすると、リクエストが走りません。キャッシュから即座に表示されます。

5分後に再タップすると、もう1回リクエストが走ります。staleTime の5分が経過して「古いデータ」と判断されたためです。

削除できたコードの量

	移行前	移行後
ファイルの行数	176行	82行
トップレベルの Map	2個	0個
useRef	1個	0個
useState	3個	0個
useEffect	2個	0個

半分以下になりました。そして残ったコードは「何をするか」だけが書いてあり、「どうやるか」は TanStack Query に任せています。

「動いてはいるけど不安」というコードを抱えているなら、TanStack Query への移行を検討する価値はあると思います。

本サイト（Next.js + TypeScript + MDX）を作りながら学んでいます。

mojitonews.hateblo.jp

jQueryとReactの対比で学ぶ宣言的UI——サイト内の絞り込み機能で気づいた「状態を渡すだけ」の正体

2026-04-20T07:07:40+09:00

左：検索前の全29件表示　右：「尾道」と入力した直後の12件。コードは状態を変えただけです。

はじめに

「宣言的UI」という言葉、React の入門記事でよく目にするのですが、最初はいまいちピンときませんでした。

「命令的との違い」を読んで、なるほど。と思いつつ、実際に手を動かすまでは腹落ちしていませんでした。その感覚が変わったのは、本サイトを Next.js で作り始めて、スポットの絞り込み機能を実装したときのことです。

この記事では、jQuery を知っている人に向けて「宣言的UIとは何か」を before/after の対比で整理します。

jQuery で書くとしたら——「ワイが全部やる」スタイル

観光スポットをキーワードで絞り込む機能を jQuery で書くとしたら、こうなります。

$('#spot-search').on('input', function () {
  const q = $(this).val().toLowerCase();

  // 全カードをいったん非表示
  $('.spot-card').hide();

  // キーワードに一致するカードだけ表示
  $('.spot-card').filter(function () {
    return $(this).data('name').toLowerCase().includes(q); // data-name属性から取得
  }).show();

  // カウンターを更新
  const count = $('.spot-card:visible').length;
  $('#result-count').text(count + '件');
});

やっていることは明確です。入力されたら、全部隠して、一致するものだけ出して、カウンターを書き換える。手順を一行ずつ書いています。

なお、このコードは各カード要素に data-name="スポット名" 属性がついている前提です。

DOM を自分の手で動かしている感覚があります。これはこれで直感的ですし、小規模なら十分に機能します。

React で書いたら——「状態を渡すだけ」

同じ機能を Next.js（React）で実装したとき、コードはこうなりました。

const [query, setQuery] = useState("");

const filtered = useMemo(() => {
  const q = query.trim().toLowerCase();
  if (!q) return spots;
  return spots.filter(
    (s) =>
      s.name.toLowerCase().includes(q) ||
      s.shortDescription?.toLowerCase().includes(q) ||
      s.tags?.some((t) => t.toLowerCase().includes(q))
  );
}, [spots, query]);

// 入力で状態を更新するだけ
<input
  value={query}
  onChange={(e) => setQuery(e.target.value)}
  placeholder="スポット名・キーワードで検索…"
/>

// あとは状態に基づいてレンダリング
{filtered.map((spot) => (
  <SpotCard key={spot.id} spot={spot} />
))}

最初に書いたとき、正直戸惑いました。

「え、これだけ？カードを hide/show しなくていいの？」

setQuery で文字列を更新するだけで、filtered が自動的に再計算され、SpotCard が再レンダリングされます。自分で DOM を触るコードはどこにもありません。

useMemo は「query が変わったときだけ再計算する」という最適化ですが、本質は同じです。状態（query）が変われば、画面が勝手についてきます。

実際に動いている——本サイトのスポット検索機能

上のコードは、本サイトのスポット一覧ページ（shimanami-guide.jp/spots）でそのまま動いています。

ページを開くと、最初はすべてのスポットが表示されています。

しまなみ海道の観光スポット一覧。全29件が表示された初期状態です。

検索バーに「尾道」と入力すると、一致するスポットだけが残ります。

「尾道」と入力した瞬間に12件へ絞り込まれました。検索ボタンは配置していません。

DOM を直接触るコードは1行もありません。setQuery("尾道") が走った瞬間に filtered が再計算され、画面が切り替わります。状態を変えただけで、これが起きています。

「あ、これが React の正体か」という瞬間

本サイトの地図コンポーネントを作っていて、ある瞬間に気づきました。

jQuery のときは「どう動かすか」を書いていました。
React のときは「どういう状態のとき、何を表示するか」を書いています。

jQuery は手順書です。「Aをして、Bをして、Cを変える」と書きます。
React は完成図です。「この状態のとき、画面はこう見えるべき」と宣言します。

これが宣言的UI（Declarative UI）の正体でした。

命令的（jQuery）：「ステップ1: 非表示にする。ステップ2: 対象を表示する。ステップ3: カウンターを更新する」
宣言的（React）：「query がこの値のとき、画面はこう見えるべき」

宣言的UIの何がうれしいのか

状態の管理が一元化されます。

jQuery だと、複数の場所で DOM を操作するうちに「どれが正しい状態か」が分からなくなることがあります。カードは非表示なのにカウンターが更新されていない、といったバグが起きやすいです。

React は状態（query）が唯一の真実です。状態が変われば、それに依存するすべての UI が自動的に整合性を保って更新されます。

状態（state）
  └── filtered（派生）
        └── SpotCard の表示（UI）
        └── resultCount の表示（UI）

状態を変えれば、UI は勝手についてきます。

jQuery が悪いわけじゃない

誤解してほしくないのですが、jQuery は今も現役で正解なケースがあります。

既存の HTML テンプレート（WordPress など）に少し動きを加えたい
ページ遷移のある MPA（マルチページアプリ）で軽い操作だけしたい
バンドルサイズを最小限にしたい小規模サイト

こういうときに React を持ち込むのは過剰です。jQuery は今も優秀なツールです。

ただ、状態が複数あって、それに応じた UI が連動するような場面では、宣言的UIの考え方が圧倒的にコードを整理してくれます。

まとめ

	jQuery（命令的）	React（宣言的）
書くもの	「何をするか」の手順	「どう見えるべきか」の宣言
DOM 操作	自分で書く	React が担う
状態管理	散在しやすい	一元化される
向いている場面	既存 HTML への追加・小規模	状態が多い・連動する UI

jQueryは命令書、Reactは完成図を渡す。

この一文が、宣言的UIを一番シンプルに表していると思います。本サイトを作りながら、私が手を動かして初めてその意味が腹落ちしました。

「Reactよくわからん」と思っていた頃の私に、この記事を渡したかったです。

本サイト（Next.js + TypeScript + MDX）を作りながら学んでいます。

"use client" はどこに書くのか——エラーが出るたびにつけ足していたら全部 Client Component になっていた

2026-04-17T13:59:39+09:00

サーバー領域（緑）でgetAllSpots()を実行してSpotを取得し、クライアント領域（紫）のHomeClient・SpotsListClientにpropsで渡します。MapboxやuseStateなどブラウザ専用の処理（オレンジ）はツリーの末端に置きます

以前、fs を使ったらビルドエラーが出た話を書きました。

mojitonews.hateblo.jp

あのときは「fs はサーバー専用だから Client Component で呼べない」という原因にたどり着いて終わりました。ただその後も同じ問題を別の形で踏み続けました。エラーが出る → とりあえず "use client" を先頭に追加 → 直る。この繰り返しをしているうちに、気づけばプロジェクトのほぼ全コンポーネントに "use client" がついていました。「Pages Router のときは全部クライアントだったんだから、同じでいいんじゃないの？」と思っていました。

今回はその先——「では "use client" はどこに書くべきか」という設計の判断基準を、実際のコードで整理します。

状況	"use client"
useState / useEffect を使う	必要
onClick などのイベントハンドラを使う	必要
Mapbox など WebGL・DOM API を使うライブラリ	必要
fs でファイルを読む / DB にアクセスする	不要（サーバー専用）
ただデータを受け取って表示するだけ	不要

状況	推奨
処理が直線的に流れる（順番にawaitするだけ）	async/await
try/catch/finallyで複数のエラーを整理したい	async/await
useEffectの中で書きたいが処理が単純	IIFE + async/await
すでにPromise変数が手元にある	.then()チェーン
useEffectの外でPromiseを共有・合流させたい	.then()チェーン
.finally()だけ使いたい（クリーンアップ処理）	.then()チェーンの末尾に.finally()

	Server Component	Client Component
実行環境	Node.js（サーバー）	ブラウザ
`fs` / `path`	✅ 使える	❌ 使えない
`useState` / `useEffect`	❌ 使えない	✅ 使える
イベントハンドラ	❌ 不可	✅ 使える
DB への直接アクセス	✅ 可能	❌ 不可

用途	技術
フレームワーク	Next.js 15（App Router）
言語	TypeScript
スタイリング	Tailwind CSS
コンテンツ管理	MDX
ホスティング	Vercel
開発補助	Claude Code（AI CLI）

Shimanami RouteLab｜しまなみ海道のスポット紹介サイトを個人開発

`useEffect` の第2引数（依存配列）を空にしていい場面・してはいけない場面——しまなみガイドの実装から整理した

はじめに

まず：依存配列とは何か

パターン1：[] でいい場面——「初回だけ取得すればいい」静的データ

パターン2：[依存値] が必要な場面——「URLが変わったら取り直す」

パターン3：[query] が必要な場面——「設定が変わったらリスナーを張り直す」

パターン4：複数の依存値——「渡された値が変わるたびに再セットアップ」

なぜ [] にしてはいけない場面があるのか：stale closure 問題

ESLint の react-hooks/exhaustive-deps を使う

4パターンの整理

`Promise.all` で複数APIを並列fetchしつつ、1件失敗しても残りを使う設計——しまなみガイドのバス時刻表実装

はじめに

Promise.all の「1件失敗で全滅」問題

解決策：内側で catch して null を返す

null を除いてマージする

Promise.allSettled との違い

クリーンアップ：cancelled フラグ

cache: 'force-cache' で2回目以降を高速化

全体像

ライブラリなしでスワイプ対応 BottomSheet を React に実装した——CSSトランジションが「一発で動かない理由」と double rAF trick

はじめに：なぜゼロから書いたのか

完成品の機能

設計の出発点：mounted と show を分離する

本題：なぜ「double rAF」が必要なのか

1つの requestAnimationFrame では足りない

double rAF + 強制フラッシュが解決する

スワイプ判定：距離だけでは足りない

inert 属性でアクセシビリティを担保する

フォーカス復帰

forwardRef + useImperativeHandle で命令的 close

createPortal でスタッキングコンテキストを脱出する

まとめ

useCallback が必要な場面・不要な場面——「とりあえず入れとく」はパフォーマンスを悪化させる

useCallback がやっていること

入れなくていい場面

1. ネイティブ DOM 要素への onClick

2. コンポーネント内だけで使う関数

入れる意味がある場面

1. React.memo で囲んだ子コンポーネントへ渡すとき

2. 別の useCallback の依存配列に入れるとき

3. useEffect の依存チェーンが連なるとき

useCallback 自体にコストがある

判断フローチャート

まとめ

layout.tsx と page.tsx の違いがわからなかった——本サイトを作って理解できたこと

はじめに

1分でわかる結論

ファイル構成を見てみる

layout.tsx——全ページに共通する「枠」

page.tsx——そのURLの「内容」

metadataもどちらに書くかで意味が変わる

generateStaticParams——動的ページを静的に生成する

整理すると

カスタムフックで「どこで何が動くか」を整理——useIsMobile / useGeolocate / useCloseAll の設計

はじめに

useIsMobile——ブラウザAPIをラップするパターン

なぜ作ったか

コード

ポイント

使い方

useGeolocate——コールバックとstateをセットにするパターン

なぜ作ったか

コード

ポイント

使い方

useCloseAll——複数storeの横断操作をまとめるパターン

なぜ作ったか

コード

ポイント

使い方

3つを並べてわかったこと

自前キャッシュをTanStack Queryに移行した——176行のコードが82行に

はじめに

移行前のコード——自前で全部やっていた

インストール

Step 1：QueryClientProvider をルートに追加

Step 2：useHotelDetail.ts を useQuery に書き換え

動作確認

削除できたコードの量

パターン1：`[]` でいい場面——「初回だけ取得すればいい」静的データ

パターン2：`[依存値]` が必要な場面——「URLが変わったら取り直す」

パターン3：`[query]` が必要な場面——「設定が変わったらリスナーを張り直す」

なぜ `[]` にしてはいけない場面があるのか：stale closure 問題

ESLint の `react-hooks/exhaustive-deps` を使う

`Promise.all` の「1件失敗で全滅」問題

解決策：内側で catch して `null` を返す

`Promise.allSettled` との違い

クリーンアップ：`cancelled` フラグ

`cache: 'force-cache'` で2回目以降を高速化

設計の出発点：`mounted` と `show` を分離する

`inert` 属性でアクセシビリティを担保する

`forwardRef` + `useImperativeHandle` で命令的 close

`createPortal` でスタッキングコンテキストを脱出する

`server-only` パッケージという保険もある

手を動かして初めてわかった　Next.js + TypeScript で個人サイトを作りながら学ぶという選択