APIリファレンスファイルシステム規約instrumentation-client.js

instrumentation-client.js

instrumentation-client.js|ts ファイルを使用すると、アプリケーションがインタラクティブになる前に実行される監視、分析コード、その他の副作用を追加できます。これは、パフォーマンス追跡、エラー監視、ポリフィル、またはその他のクライアントサイドのオブザーバビリティツールを設定するのに役立ちます。

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

使用方法

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

// Set up performance monitoring
performance.mark('app-init')
 
// Initialize analytics
console.log('Analytics initialized')
 
// Set up error tracking
window.addEventListener('error', (event) => {
  // Send to your error tracking service
  reportError(event.error)
})

エラー処理: 監視コードを try-catch ブロックで囲み、堅牢な監視を実装します。これにより、個々の追跡の失敗が他の監視機能に影響を与えるのを防ぐことができます。

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

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 ファイルは、アプリケーションライフサイクルの特定の時点で実行されます。

HTML ドキュメントが読み込まれた後
React のハイドレーションが開始される前
ユーザーインタラクションが可能になる前

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

例

エラー追跡

React が開始される前にエラー追跡を初期化し、デバッグコンテキストを向上させるためにナビゲーションパンくずを追加します。

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

分析追跡

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

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

パフォーマンス監視

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

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}`)
}

Polyfills

アプリケーションコードが実行される前にポリフィルをロードします。静的インポートを使用して即時ロードし、動的インポートを使用して機能検出に基づいて条件付きロードします。

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

バージョン履歴

バージョン	変更履歴
`v15.3`	`instrumentation-client` が導入されました