التهيئة الآلية (Instrumentation)

إذا قمت بتصدير دالة باسم register من ملف instrumentation.ts (أو .js) في الدليل الجذري لمشروعك (أو داخل مجلد src إذا كنت تستخدم واحدًا)، فسنقوم باستدعاء هذه الدالة عند بدء تشغيل أي نسخة جديدة من خادم Next.js.

معلومة مفيدة

• هذه الميزة تجريبية. لاستخدامها، يجب عليك الموافقة صراحةً عن طريق تعريف experimental.instrumentationHook = true; في ملف next.config.js الخاص بك.
• يجب أن يكون ملف instrumentation في جذر مشروعك وليس داخل مجلد app أو pages. إذا كنت تستخدم مجلد src، فضع الملف داخل src بجانب pages و app.
• إذا كنت تستخدم خيار تكوين pageExtensions لإضافة لاحقة، فستحتاج أيضًا إلى تحديث اسم ملف instrumentation ليتطابق.
• لقد أنشأنا مثالًا أساسيًا with-opentelemetry يمكنك استخدامه.

عند نشر دالة register الخاصة بك، سيتم استدعاؤها عند كل إقلاع بارد (ولكن مرة واحدة بالضبط في كل بيئة).

في بعض الأحيان، قد يكون من المفيد استيراد ملف في الكود الخاص بك بسبب الآثار الجانبية التي سيسببها. على سبيل المثال، قد تستورد ملفًا يحدد مجموعة من المتغيرات العامة، ولكن لا تستخدم الملف المستورد صراحةً في الكود الخاص بك. سيظل لديك إمكانية الوصول إلى المتغيرات العامة التي أعلن عنها الحزمة.

يمكنك استيراد الملفات ذات الآثار الجانبية في instrumentation.ts، والتي قد ترغب في استخدامها في دالة register كما هو موضح في المثال التالي:

import { init } from 'package-init'

export function register() {
  init()
}

import { init } from 'package-init'

export function register() {
  init()
}

ومع ذلك، نوصي باستيراد الملفات ذات الآثار الجانبية باستخدام import من داخل دالة register بدلاً من ذلك. يوضح المثال التالي استخدامًا أساسيًا لـ import في دالة register:

export async function register() {
  await import('package-with-side-effect')
}

export async function register() {
  await import('package-with-side-effect')
}

بفعلك هذا، يمكنك تجميع جميع الآثار الجانبية في مكان واحد في الكود الخاص بك، وتجنب أي عواقب غير مقصودة من استيراد الملفات.

نستدعي register في جميع البيئات، لذا من الضروري استيراد أي كود لا يدعم كلًا من edge و nodejs بشكل مشروط. يمكنك استخدام متغير البيئة NEXT_RUNTIME للحصول على البيئة الحالية. سيبدو استيراد كود خاص ببيئة معينة كما يلي:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}