Menu

instrumentation-client.js

instrumentation-client.js|tsファイルを使用すると、アプリケーションがインタラクティブになる前に実行される監視、分析コード、およびその他の副作用を追加できます。これはパフォーマンストラッキング、エラー監視、polyfill、またはその他のクライアント側の可観測性ツールを設定するのに役立ちます。

これを使用するには、ファイルをアプリケーションのルート、またはsrcフォルダ内に配置します。

使用方法

サーバー側インストルメンテーションとは異なり、特定の関数をエクスポートする必要はありません。監視コードをファイルに直接記述できます：

instrumentation-client.ts
TypeScript
// パフォーマンス監視の設定
performance.mark('app-init')
 
// 分析の初期化
console.log('Analytics initialized')
 
// エラートラッキングの設定
window.addEventListener('error', (event) => {
  // エラートラッキングサービスに送信
  reportError(event.error)
})

エラーハンドリング： インストルメンテーションコードの周りにtry-catchブロックを実装して、堅牢な監視を確保します。これにより、個別のトラッキング障害が他のインストルメンテーション機能に影響を与えるのを防ぎます。

ルーターナビゲーションの追跡

onRouterTransitionStart関数をエクスポートして、ナビゲーションが開始されたときに通知を受け取ることができます：

instrumentation-client.ts
TypeScript
performance.mark('app-init')
 
export function onRouterTransitionStart(
  url: string,
  navigationType: 'push' | 'replace' | 'traverse'
) {
  console.log(`Navigation started: ${navigationType} to ${url}`)
  performance.mark(`nav-start-${Date.now()}`)
}

onRouterTransitionStart関数は2つのパラメータを受け取ります：

  • url: string - ナビゲート先のURL
  • navigationType: 'push' | 'replace' | 'traverse' - ナビゲーションのタイプ

パフォーマンスの考慮事項

インストルメンテーションコードを軽量に保ちます。

Next.jsは開発時の初期化時間を監視し、16msを超える場合は警告をログに出力します。これはスムーズなページロードに影響を与える可能性があります。

実行タイミング

instrumentation-client.jsファイルはアプリケーションのライフサイクルの特定のポイントで実行されます：

  1. HTMLドキュメントがロードされた後
  2. React hydrationが開始される前
  3. ユーザーインタラクションが可能になる前

このタイミングにより、早期のアプリケーションライフサイクルイベントをキャプチャする必要があるエラートラッキング、分析、パフォーマンス監視を設定するのに理想的です。

例

エラートラッキング

Reactが開始される前にエラートラッキングを初期化し、デバッグコンテキストを改善するためのナビゲーションブレッドクラムを追加します。

instrumentation-client.ts
TypeScript
import Monitor from './lib/monitoring'
 
Monitor.initialize()
 
export function onRouterTransitionStart(url: string) {
  Monitor.pushEvent({
    message: `Navigation to ${url}`,
    category: 'navigation',
  })
}

分析トラッキング

分析を初期化し、ユーザー行動分析のための詳細なメタデータを含むナビゲーションイベントを追跡します。

instrumentation-client.ts
TypeScript
import { analytics } from './lib/analytics'
 
analytics.init()
 
export function onRouterTransitionStart(url: string, navigationType: string) {
  analytics.track('page_navigation', {
    url,
    type: navigationType,
    timestamp: Date.now(),
  })
}

パフォーマンス監視

Performance Observer APIとパフォーマンスマークを使用して、Time to Interactiveとナビゲーションパフォーマンスを追跡します。

instrumentation-client.ts
TypeScript
const startTime = performance.now()
 
const observer = new PerformanceObserver(
  (list: PerformanceObserverEntryList) => {
    for (const entry of list.getEntries()) {
      if (entry instanceof PerformanceNavigationTiming) {
        console.log('Time to Interactive:', entry.loadEventEnd - startTime)
      }
    }
  }
)
 
observer.observe({ entryTypes: ['navigation'] })
 
export function onRouterTransitionStart(url: string) {
  performance.mark(`nav-start-${url}`)
}

Polyfill

アプリケーションコードが実行される前にpolyfillをロードします。即座にロードするには静的importを使用し、機能検出に基づいた条件付きロードには動的importを使用します。

instrumentation-client.ts
TypeScript
import './lib/polyfills'
 
if (!window.ResizeObserver) {
  import('./lib/polyfills/resize-observer').then((mod) => {
    window.ResizeObserver = mod.default
  })
}

バージョン履歴

バージョン変更内容
v15.3導入時期：instrumentation-client