Next.js/output file tracing

تتتبع Next.js تقائيًا كل صفحة واعتمادياتها أثناء بناء التطبيق لتحديد جميع الملفات المطلوبة لنشر نسخة الإنتاج من التطبيق، ويتيح ذلك إمكانية تقليل حجم ملفات النشر. فعندما استخدمت Docker سابقًا لنشر تطبيقك، كنت بحاجة إلى تثبيت جميع ملفات الاعتماديات dependencies التي تشير إليها حزمة التطبيق حتى تستطيع تشغيله next start. لكن بإمكانك ابتداءً من النسخة 12 تتبع ملفات الخرج في المجلد /next. كي يضم فقط الملفات الضرورية.

تلغي هذه الميزة أيضًا الحاجة إلى الوجهة serverless الملغاة التي قد تسبب مشاكل عدة، وتنشئ نسخًا إضافيةً غير ضرورية.

كيف تعمل ميزة تتبع ملفات الخرج

تستخدم Next.js التوجيه vercel/nft@ أثناء بناء التطبيق next build لتحلل كل من import و require و fs بشكل ساكن لتحديد جميع الملفات التي قد تحمّلها الصفحة. كما يجري التحقق من الملفات التي يحتاجها خادم إنتاج Next.js ووضعها في ملف الخرج next/next-server.js.nft.json. الذي يمكن رفعه في مرحلة الإنتاج.

ولرفع الملفات ذات الامتداد nft.json. المنتقلة إلى مجلد الخرج next.، بإمكانك قراءة قائمة الملفات التي تنتهي بالامتداد nft.json. في كل ملف تتبع ونسخها إلى مكان نشر التطبيق.

النسخ التلقائي للملفات المُتتبعة

يمكن أن تُنشئ Next.js مجلدًا قائمًا بذاته standalone ينسخ الملفات الضرورية لنشر نسخة الإنتاج فقط بما في ذلك الملفات الموجودة في المجلد node_modules. ولتشغيل النسخ التلقائي، عليك أولًا تفعيل الميزة outputStandalone في الملف next.config.js:

module.exports = {
  output: 'standalone',
}

سينتج عن ذلك المجلد next/standalone. الذي يمكن نشره بشكل مستقل دون الحاجة إلى تثبيت وحدات node_modules.

إضافة إلى ذلك، بإمكانك استخدام ملف JavaScript المصغر server.js الذي ينتج عن العملية بدلًا من next start. لا ينسخ الخادم المصغّر السابق server.js المجلدين public أو next/static. افتراضيًا لأن من يتعامل معهما عادة هي شبكة توزيع المحتوى CDN. مع ذلك يمكن نسخ محتوى هذين المجلدين إلى standalone/public و standalone/.next/static يدويًا ليخدّمهما الملف server.js تلقائيًا بعد ذلك.

ملاحظة: يُقرأ الملف next.config.js أثناء عمليةي البناء next build ويحوَّل إلى ملف الخرج server.js، إن كان أحد الخيارين القديمين serverRuntimeConfig أو publicRuntimeConfig مستخدمين، فستُحدَّد القيم إلى القيم المولدة وقت البناء.

إن كان مشروعك يستخدم ميزة تحسين الصور مع المُحمِّل الافتراضي loader، فيجب تنزيل الاعتمادية sharp:

npm i sharp
// or
yarn add sharp
// or
pnpm add sharp

محاذير

• يُستخدم مجلد المشروع افتراضيًا للتتبع في حال كان مهيّأً ضمن مستودع وحيد monorepo. أما عند تنفيذ الأمر next build packages/web-app، سيكون المجلد packages/web-app هو الجذر الذي يستخدم للتتبع ولن تتضمن عملية التتبع أي ملف خارج هذا المجلد. ولإضافة الملفات التي تقع خارجه، لا بد من ضبط قيمة experimental.outputFileTracingRoot في ملف التهيئة next.config.js:

// packages/web-app/next.config.js
module.exports = {
  experimental: {
    // سيضيف ذلك ملفات من قاعدة المستودع الوحيد وصولًا إلى مجلدين أعلى
    outputFileTracingRoot: path.join(__dirname, '../../'),
  },
}

• قد تخفق Next.js أحيانًا في تضمين بعض الملفات المطلوبة أو قد تضم ملفات غير مستخدمة. بإمكانك في هذه الحالات تصدير خاصيتي تهيئة الصفحة unstable_includeFiles و unstable_excludeFiles بالترتيب. إذ تقبل كل خاصية مصفوفة من تعابير المطابقة minimatch globs المرتبطة بجذر المشروع لتضمين أو إزالة الملفات أثناء التتبع.
• لا تقدّم Next.js أي شيء حاليًا للملفات nft.json.، وينبغي أن تُقرأ من قبل المنصة التي ستنشر عليها التطبيق (مثل Vercel) كي يجري نشره بأصغر حزمة ممكنة. لكن قد يظهر أمر جديد في النسخات المستقبلة لاستغلال ملفات nft.json..

استخدام الميزة turbotrace التجريبية

قد تكون عملية تتبع الاعتماديات بطيئة بما أنها تستدعي عمليات معالجة وتحليل معقدة، لذا أنشأنا ميزة turbotrace في لغة رست بديلًا سريعًا وذكيًا للعملية المقابلة المنفذة بجافاسكربت، ولتفعيلها، يمكنك إضافة الضبط التالي في ملف next.config.js:

// next.config.js
module.exports = {
  experimental: {
    turbotrace: {
      // control the log level of the turbotrace, default is `error`
      logLevel?:
      | 'bug'
      | 'fatal'
      | 'error'
      | 'warning'
      | 'hint'
      | 'note'
      | 'suggestions'
      | 'info',
      // control if the log of turbotrace should contain the details of the analysis, default is `false`
      logDetail?: boolean
      // show all log messages without limit
      // turbotrace only show 1 log message for each categories by default
      logAll?: boolean
      // control the context directory of the turbotrace
      // files outside of the context directory will not be traced
      // set the `experimental.outputFileTracingRoot` has the same effect
      // if the `experimental.outputFileTracingRoot` and this option are both set, the `experimental.turbotrace.contextDirectory` will be used
      contextDirectory?: string
      // if there is `process.cwd()` expression in your code, you can set this option to tell `turbotrace` the value of `process.cwd()` while tracing.
      // for example the require(process.cwd() + '/package.json') will be traced as require('/path/to/cwd/package.json')
      processCwd?: string,
      // control the maximum number of files that are passed to the `turbotrace`
      // default is 128
      maxFiles?: number;
    },
  },
}

المصادر

• الصفحة Output File Tracing من توثيق Next.js الرسمي.