nft

تتبع ملف العقدة

تستخدم لتحديد الملفات بالضبط (بما في ذلك node_modules ) ضرورية لوقت تشغيل التطبيق.

هذا مشابه لـ @Vercel/NCC باستثناء عدم إجراء تجميع وبالتالي لا يعتمد على WebPack. هذا يحقق نفس فوائد تهزئة الأشجار دون تحريك أي أصول أو ثنائيات.

الاستخدام

تثبيت

npm i @vercel/nft

الاستخدام

توفير قائمة ملفات المصدر كمدخلات:

 const { nodeFileTrace } = require ( '@vercel/nft' ) ;
const files = [ './src/main.js' , './src/second.js' ] ;
const { fileList } = await nodeFileTrace ( files ) ;

ستتضمن قائمة الملفات جميع وحدات node_modules والأصول التي قد تكون مطلوبة بواسطة رمز التطبيق.

خيارات

قاعدة

المسار الأساسي لقائمة الملفات - سيتم توفير جميع الملفات على أنها نسبة إلى هذه القاعدة.

بشكل افتراضي ، يتم استخدام process.cwd() :

 const { fileList } = await nodeFileTrace ( files , {
  base : process . cwd ( ) ,
} ) ;

يتم تجاهل أي ملفات/مجلدات فوق base في القائمة والتحليل.

عملية CWD

عند تطبيق التحليل ، تعتمد وظائف معينة على قيمة process.cwd() ، مثل path.resolve('./relative') أو حتى عملية استدعاء process.cwd() .

يتيح تعيين خيار processCwd توجيه هذا التحليل إلى المسار الصحيح لضمان اكتشاف الأصول بشكل صحيح.

 const { fileList } = await nodeFileTrace ( files , {
  processCwd : path . resolve ( __dirname ) ,
} ) ;

بشكل افتراضي processCwd هو نفس base .

الصادرات والواردات

بشكل افتراضي ، يتم دعم التتبع الافتراضي لـ Node.js "الصادرات" و "الواردات" ، مع "node" ، "require" ، "import" و "default" التي يتم تتبعها على النحو المحدد.

بدلاً من ذلك ، يمكن توفير قائمة الشروط الصريحة:

 const { fileList } = await nodeFileTrace ( files , {
  conditions : [ 'node' , 'production' ] ,
} ) ;

يجب تضمين تصدير "node" فقط بشكل صريح (إذا لزم الأمر) عند تحديد قائمة شرط التصدير الدقيقة. سيتم دائمًا تتبع الشروط "require" و "import" و "default" على النحو المحدد ، بغض النظر عن الظروف المخصصة التي يتم تعيينها.

الصادرات فقط

عند تتبع تصدير الحقل "main" / الفهرس ، سيظل تتبع إصدارات Node.js دون دعم "exports" .

يمكن تعطيل ذلك بخيار exportsOnly :

 const { fileList } = await nodeFileTrace ( files , {
  exportsOnly : true ,
} ) ;

أي حزمة مع "exports" لن يتم تتبع صادراتها فقط ، ولن يتم تضمين الرئيسي على الإطلاق. هذا يمكن أن يقلل من حجم الإخراج عند استهداف node.js 12.17.0 أو الأحدث.

مسارات

الحالة: تجريبي. قد يتغير في أي وقت.

تعريفات مسار الدقة المخصصة للاستخدام.

 const { fileList } = await nodeFileTrace ( files , {
  paths : {
    'utils/' : '/path/to/utils/' ,
  } ,
} ) ;

زمام المائلة الخريطة دلائل الخريطة ، والمسارات الدقيقة خريطة بالضبط فقط.

السنانير

يمكن توصيل وظائف FS التالية عن طريق تمريرها كخيارات:

• readFile(path): Promise<string>
• stat(path): Promise<FS.Stats>
• readlink(path): Promise<string>
• resolve(id: string, parent: string): Promise<string | string[]>

حل متقدم

عند توفير خطاف حل مخصص ، تكون مسؤولاً عن إرجاع مسارات مطلقة أو أكثر إلى الملفات التي تم حلها بناءً على إدخال id . ومع ذلك ، قد يكون الأمر أنك تريد فقط زيادة أو تجاوز سلوك حل في بعض الحالات. يمكنك استخدام حل nft الأساسي من خلال استيراده. تتوقع دالة resolve Buildin حجج إضافية تحتاج إلى إعادة توجيهها من الخطاف

• resolve(id: string, parent: string, job: Job, isCjs: boolean): Promise<string | string[]>

فيما يلي مثال يوضح أحد المعرف الذي يتم حله على مسار مفصل بينما يتم حل جميع المسارات الأخرى بواسطة المحلول المدمج

 const { nodeFileTrace , resolve } = require ( '@vercel/nft' ) ;
const files = [ './src/main.js' , './src/second.js' ] ;
const { fileList } = await nodeFileTrace ( files , {
  resolve : async ( id , parent , job , isCjs ) => {
    if ( id === './src/main.js' ) {
      return '/path/to/some/resolved/main/file.js' ;
    } else {
      return resolve ( id , parent , job , isCjs ) ;
    }
  } ,
} ) ; 

TypeScript

يدعم الدقة الداخلية حل ملفات .ts في آثار افتراضيًا.

من خلال طبيعة الاندماج في أنظمة الإنشاء الحالية ، لم يتم تضمين برنامج التحويل البرمجي TypeScript في هذا المشروع - بل طبقة تحويل TypeScript تتطلب تكاملًا منفصلاً في خطاف readFile .

ملف IO Concurrency

في بعض المشاريع الكبيرة ، قد يعالج منطق تتبع الملف العديد من الملفات في نفس الوقت. في هذه الحالة ، إذا لم تقصر عدد الملفات المتزامنة ، فمن المحتمل أن تحدث مشاكل OOM.

نستخدم افتراضيًا من 1024 تزامن لموازنة الأداء واستخدام الذاكرة لعمليات FS. يمكنك زيادة هذه القيمة إلى عدد أعلى للسرعة الأسرع ، ولكن كن على دراية بقضايا الذاكرة إذا كان التزامن مرتفعًا جدًا.

 const { fileList } = await nodeFileTrace ( files , {
  fileIOConcurrency : 2048 ,
} ) ; 

تحليل

تسمح خيارات التحليل بتخصيص مقدار التحليل الذي يجب إجراءه لتوظيف قائمة التبعية بالضبط.

بشكل افتراضي ، يتم إجراء أكبر قدر ممكن من التحليل لضمان عدم وجود ملفات ربما يتم حاجة إليها من التتبع.

لتعطيل جميع التحليل ، حدد analysis: false . بدلاً من ذلك ، يمكن تخصيص خيارات التحليل الفردي عبر:

 const { fileList } = await nodeFileTrace ( files , {
  // default
  analysis : {
    // whether to glob any analysis like __dirname + '/dir/' or require('x/' + y)
    // that might output any file in a directory
    emitGlobs : true ,
    // whether __filename and __dirname style
    // expressions should be analyzed as file references
    computeFileReferences : true ,
    // evaluate known bindings to assist with glob and file reference analysis
    evaluatePureExpressions : true ,
  } ,
} ) ; 

يتجاهل

يمكن توفير مخصصة المخصصة لتخطي إدراج الملف (وبالتالي تحليل الملف للمراجع بدوره أيضًا).

 const { fileList } = await nodeFileTrace ( files , {
  ignore : [ './node_modules/pkg/file.js' ] ,
} ) ;

سوف تجاهل أيضا قبول وظيفة أو كرات.

لاحظ أن المسار المقدم لتجاهله بالنسبة base .

مخبأ

لاستمرار ذاكرة التخزين المؤقت للملف بين الإنشاءات ، تمرير كائن cache الفارغة:

 const cache = Object . create ( null ) ;
const { fileList } = await nodeFileTrace ( [ 'index.ts' ] , { cache } ) ;
// later:
{
  const { fileList } = await nodeFileTrace ( [ 'index.ts' ] , { cache } ) ;
}

لاحظ أن إبطال ذاكرة التخزين المؤقت غير مدعوم ، لذا فإن الافتراض هو أنه لا يتم تغيير نظام الملفات بين التشغيل.

أسباب

للحصول على الأسباب الأساسية لإدراج الملفات الفردية ، يتم أيضًا توفير reasons كائن من خلال الإخراج:

 const { fileList , reasons } = await nodeFileTrace ( files ) ;

reasons الإخراج ستكون بعد ذلك كائنًا للنموذج التالي:

 {
  [ file : string ] : {
    type : 'dependency' | 'asset' | 'sharedlib' ,
    ignored : true | false ,
    parents : string [ ]
  }
}

تتضمن reasons أيضًا ملفات تم تجاهلها على أنها ignored: true ، مع ignoreReason .

يتم تضمين كل ملف لأنه يشير إليه ملف آخر. ستحتوي قائمة parents على قائمة جميع الملفات التي تسببت في تضمين هذا الملف.