AI Assisted
この記事は筆者の実装経験をもとに実装コードをベースで執筆し、AIによる校閲・推敲を経て公開しています。

Next.js 16 staleTimes 設定変更ガイド

Next.js 16 で staleTimes.static の最小値が 30 秒に変更されました。この記事では、staleTimes とは何か、なぜ変更されたのか背景を解説し、対応方法を紹介します。

---

staleTimes とは

役割

staleTimes は、クライアントサイドルーターキャッシュの設定です。ページ遷移時に、既に取得したページデータをブラウザ側でどれくらいキャッシュするかを制御します。

ホーム → 記事A → ホーム（戻る）
         ↑
    この「戻る」時にキャッシュを使うか？

設定項目

基本構文

// next.config.js
const nextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 30,   // 動的ページは30秒キャッシュ
      static: 180,   // 静的ページは180秒キャッシュ
    },
  },
}

動作例

static: 60 の場合：

1. ユーザーがホームページを表示
2. 記事Aに遷移
3. 60秒以内にホームに戻る → キャッシュから表示（サーバーリクエストなし）
4. 60秒経過後にホームに戻る → サーバーから再取得

使いどころ

• 開発環境: キャッシュを短くして変更をすぐ確認したい
• 本番環境: キャッシュを長くしてパフォーマンス向上
• リアルタイム性が必要なページ: dynamic: 0 でキャッシュ無効化

---

なぜ最小値が 30 秒に変わったのか

1. パフォーマンスの保護

static: 0 を設定すると、ページ遷移のたびにサーバーリクエストが発生します。これはユーザー体験とサーバー負荷の両面で問題になります。

Next.js チームは、静的ページに対して最低限のキャッシュを強制することで、パフォーマンスの劣化を防ぐ設計に変更しました。

2. 意図しない設定ミスの防止

開発環境でキャッシュを無効化したまま本番にデプロイするケースがありました。最小値を設けることで、極端なパフォーマンス劣化を防いでいます。

3. dynamic と static の役割分担

リアルタイム性が必要なページは dynamic として実装し、dynamic: 0 でキャッシュを無効化できます。静的ページは最低 30 秒のキャッシュを許容するという設計思想です。

---

何が変わったのか

---

対応方法

エラーメッセージ

static: 0 を設定していると、以下の警告が表示されます：

⚠ Invalid next.config.js options detected:
⚠     Number must be greater than or equal to 30 at "experimental.staleTimes.static"

修正方法

// next.config.js

// ❌ 従来（エラーになる）
experimental: {
  staleTimes: {
    dynamic: 0,
    static: 0,  // 最小値 30 未満でエラー
  },
}

// ✅ 新（最小値 30 に修正）
experimental: {
  staleTimes: {
    dynamic: 0,   // 動的ページはキャッシュ無効のまま
    static: 30,   // 静的ページは最小値 30 秒
  },
}

---

対応しないとどうなるか

警告は表示されますが、アプリケーションは動作します。ただし、将来的にエラーに昇格する可能性があるため、早めに修正しておくことをおすすめします。

---

注意点

開発環境でキャッシュを完全無効化したい場合

static は最小 30 秒になりますが、開発中にキャッシュが邪魔になることは少ないはずです。30 秒は十分短い値です。

どうしてもキャッシュを無効化したい場合は、ブラウザの DevTools で「Disable cache」を有効にするか、ハードリロード（Cmd+Shift+R）を使用してください。

本番環境での推奨値

本番環境では、より長いキャッシュ時間を設定することでパフォーマンスが向上します。

// 本番向け設定例
experimental: {
  staleTimes: {
    dynamic: 30,   // 動的ページも30秒キャッシュ
    static: 180,   // 静的ページは3分キャッシュ
  },
}

---

まとめ

• staleTimes はクライアントサイドルーターキャッシュの設定
• Next.js 16 で staleTimes.static の最小値が 30 秒に変更
• static: 0 はエラーになるため、static: 30 以上に修正が必要
• パフォーマンス保護と設定ミス防止が変更の目的

---

参考

• Next.js 16 Release Blog
• staleTimes Configuration