ts node
1.0.0
تنفيذ TypeScript و repl for node.js ، مع خريطة المصدر ودعم ESM الأصلي.
يمكن أيضًا العثور على أحدث وثائق على موقعنا: https://typestrong.org/ts-node
nodeTSErrorSyntaxErrorERR_REQUIRE_ESMERR_UNKNOWN_FILE_EXTENSIONnode_modulesTS-NODE هو محرك تنفيذ TypeScript و REPLID لـ Node.js.
إنه يحول TypeScript إلى JavaScript ، مما يتيح لك تنفيذ TypeScript مباشرة على Node.js دون تجميع. يتم تحقيق ذلك من خلال تثبيت واجهات برمجة تطبيقات وحدة تحميل Node ، مما يتيح استخدامها بسلاسة جنبًا إلى جنب مع أدوات ومكتبات Node.js الأخرى.
tsconfig.json تحليل
# Locally in your project.
npm install -D typescript
npm install -D ts-node
# Or globally with TypeScript.
npm install -g typescript
npm install -g ts-node
# Depending on configuration, you may also need these
npm install -D tslib @types/node نصيحة: يتيح لك تثبيت الوحدات النمطية محليًا التحكم في الإصدارات ومشاركتها من خلال package.json . ستقوم TS-Node دائمًا بحل المترجم من cwd قبل التحقق من التثبيت الخاص به.
# Execute a script as `node` + `tsc`.
ts-node script.ts
# Starts a TypeScript REPL.
ts-node
# Execute code with TypeScript.
ts-node -e ' console.log("Hello, world!") '
# Execute, and print, code with TypeScript.
ts-node -p -e ' "Hello, world!" '
# Pipe scripts to execute with TypeScript.
echo ' console.log("Hello, world!") ' | ts-node
# Equivalent to ts-node --transpileOnly
ts-node-transpile-only script.ts
# Equivalent to ts-node --cwdMode
ts-node-cwd script.ts
# Equivalent to ts-node --esm
ts-node-esm script.ts لكتابة البرامج النصية بأقصى قدر من الحمل ، حدد الخيارات في tsconfig.json وحذفها من shebang.
#!/usr/bin/env ts-node
// ts-node options are read from tsconfig.json
console . log ( "Hello, world!" ) يتطلب تضمين الخيارات داخل Shebang علامة env -S ، والتي تتوفر على الإصدارات الحديثة من env . (التوافق)
#!/usr/bin/env -S ts-node --files
// This shebang works on Mac and Linux with newer versions of env
// Technically, Mac allows omitting `-S`, but Linux requires it لاختبار نسختك من env للتوافق مع -S :
# Note that these unusual quotes are necessary
/usr/bin/env --debug ' -S echo foo bar ' يمكنك تسجيل TS-Node دون استخدام CLI: node -r ts-node/register و node --loader ts-node/esm
في كثير من الحالات ، سيمكن تعيين NODE_OPTIONS ts-node داخل أدوات العقدة الأخرى وعمليات الطفل ومواضيع العمال. يمكن دمج هذا مع أعلام العقدة الأخرى.
NODE_OPTIONS= " -r ts-node/register --no-warnings " node ./index.tsأو ، إذا كنت بحاجة إلى دعم ESM الأصلي:
NODE_OPTIONS= " --loader ts-node/esm " هذا يخبر أي عمليات عقدة تتلقى هذا البيئة متغيرًا لتثبيت خطافات ts-node قبل تنفيذ التعليمات البرمجية الأخرى.
إذا كنت تستدعي العقدة مباشرة ، فيمكنك تجنب متغير البيئة وتمرير تلك الأعلام إلى العقدة.
node --loader ts-node/esm --inspect ./index.ts يمكنك طلب TS-NODE وتسجيل الحمل للمستقبل يتطلب باستخدام require('ts-node').register({ /* options */ }) .
تحقق من واجهة برمجة التطبيقات لدينا لمزيد من الميزات.
تدعم TS-Node مجموعة متنوعة من الخيارات التي يمكن تحديدها عبر tsconfig.json ، كعلامات CLI ، كمتغيرات بيئة ، أو برمجيًا.
للحصول على قائمة كاملة ، راجع الخيارات.
يجب أن تأتي أعلام CLI TS-NODE قبل البرنامج النصي PORTPOONT. على سبيل المثال:
$ ts-node --project tsconfig-dev.json say-hello.ts Ronald
Hello, Ronald ! TS-Node يجد وتحميل tsconfig.json تلقائيًا. يمكن تحديد معظم خيارات TS-Node في كائن "ts-node" باستخدام أسماء Camelcase البرنامجية. نوصي بهذا لأنه يعمل حتى عندما لا يمكنك تمرير أعلام CLI ، مثل node --require ts-node/register وعند استخدام shebangs.
استخدم --skipProject لتخطي تحميل tsconfig.json . استخدم --project لتحديد المسار بشكل صريح إلى tsconfig.json .
عند البحث ، يتم حله باستخدام نفس سلوك البحث مثل tsc . بشكل افتراضي ، يتم تنفيذ هذا البحث بالنسبة إلى البرنامج النصي POONTER. في --cwdMode أو إذا لم يتم تحديد أي نقطة إدخال -على سبيل المثال عند استخدام Repl -يتم إجراء البحث بالنسبة إلى --cwd / process.cwd() .
يمكنك استخدام هذا التكوين النموذج كنقطة انطلاق:
{
// This is an alias to @tsconfig/node16: https://github.com/tsconfig/bases
"extends" : "ts-node/node16/tsconfig.json" ,
// Most ts-node options can be specified here using their programmatic names.
"ts-node" : {
// It is faster to skip typechecking.
// Remove if you want ts-node to do typechecking.
"transpileOnly" : true ,
"files" : true ,
"compilerOptions" : {
// compilerOptions specified here will override those declared below,
// but *only* in ts-node. Useful if you want ts-node and tsc to use
// different options with a single tsconfig.json.
}
} ,
"compilerOptions" : {
// typescript options here
}
}يسرد مخطط JSON المجمل لدينا جميع الخيارات المتوافقة.
@TSConfig/قواعد تحافظ على التكوينات الموصى بها لعدة إصدارات العقدة. على أنها راحة ، يتم تجميع هذه مع TS-DODE.
{
"extends" : "ts-node/node16/tsconfig.json" ,
// Or install directly with `npm i -D @tsconfig/node16`
"extends" : "@tsconfig/node16/tsconfig.json" ,
} إذا لم يتم تحميل أي tsconfig.json من القرص ، فسيستخدم TS-Node أحدث الإعدادات الافتراضية الموصى بها من @tsconfig/bases متوافق مع إصدارات node typescript . مع أحدث node و typescript ، هذا هو @tsconfig/node16 .
الإصدارات الأقدم من typescript غير متوافقة مع @tsconfig/node16 . في هذه الحالات ، سنستخدم التكوين الافتراضي الأقدم.
عندما تكون في شك ، ستسجل ts-node --showConfig التكوين الذي يتم استخدامه ، وسيقوم ts-node -vv بتسجيل إصدارات node و typescript .
node يجب تمرير أعلام node مباشرة إلى node ؛ لا يمكن نقلهم إلى TS-Node Binary ولا يمكن تحديدها في tsconfig.json
نوصي باستخدام متغير بيئة NODE_OPTIONS لتمرير الخيارات إلى node .
NODE_OPTIONS= ' --trace-deprecation --abort-on-uncaught-exception ' ts-node ./index.ts بدلاً من ذلك ، يمكنك استدعاء node مباشرة وتثبيت TS -Node عبر --require / -r
node --trace-deprecation --abort-on-uncaught-exception -r ts-node/register ./index.ts تدعم جميع أعلام سطر الأوامر كل من- --camelCase و-- --hyphen-case .
يمكن إعلان معظم الخيارات في tsconfig.json: التكوين عبر tsconfig.json
يدعم ts-node --print ( -p ) ، --eval ( -e ) ، --require ( -r ) و --interactive ( -i ) مماثلة لـ node.js cli.
يدعم ts-node --project و- --showConfig مماثلة ل TSC CLI.
متغيرات البيئة ، عند توفرها ، موجودة في ALL_CAPS
ts-node --helpيطبع نص المساعدة
ts-node -v
ts-node -vvv يطبع الإصدار. -vv يشمل إصدارات مترجم عقدة و typextript. -vvv يتضمن مسارات مطلقة لتركيبات TS-Done و TypeScript.
ts-node -e < typescript code >
# Example
ts-node -e ' console.log("Hello world!") 'تقييم الرمز
ts-node -p -e < typescript code >
# Example
ts-node -p -e ' "Hello world!" ' نتيجة طباعة --eval
ts-node -iيفتح REPL حتى لو لم يكن stdin هو محطة
ts-node --esm
ts-node-esmbootstrap مع محمل ESM ، مما يتيح دعم ESM الكامل
ts-node -P < path/to/tsconfig >
ts-node --project < path/to/tsconfig >مسار إلى ملف TSConfig.
لاحظ الحرف الكبيرة -P . هذا يختلف عن خيار مشروع tsc -p/--project .
البيئة: TS_NODE_PROJECT
ts-node --skipProjectتخطي دقة تكوين المشروع وتحميلها
الافتراضي: false
البيئة: TS_NODE_SKIP_PROJECT
ts-node -c
ts-node --cwdMode
ts-node-cwdحل التكوين بالنسبة إلى الدليل الحالي بدلاً من دليل البرنامج النصي للدخول
ts-node -O < json compilerOptions >
ts-node --compilerOptions < json compilerOptions >كائن JSON لدمج مع خيارات البرمجيات
البيئة: TS_NODE_COMPILER_OPTIONS
ts-node --showConfig طباعة tsconfig.json ، بما في ذلك خيارات ts-node ، والخروج
ts-node -T
ts-node --transpileOnly استخدم transpileModule من نوع TypeScrip
الافتراضي: false
البيئة: TS_NODE_TRANSPILE_ONLY
ts-node --typeCheck مقابل --transpileOnly
الافتراضي: true
البيئة: TS_NODE_TYPE_CHECK
ts-node -H
ts-node --compilerHostاستخدم واجهة برمجة تطبيقات برنامج التحويل البرمجي لـ TypeScript
الافتراضي: false
البيئة: TS_NODE_COMPILER_HOST
ts-node --files تحميل files ، include exclude من tsconfig.json على بدء التشغيل. هذا قد يتجنب بعض حالات فشل typechecking. انظر الأنواع المفقودة للحصول على التفاصيل.
الافتراضي: false
البيئة: TS_NODE_FILES
ts-node -D < code,code >
ts-node --ignoreDiagnostics < code,code >تجاهل تحذيرات TypeScript حسب رمز التشخيص
البيئة: TS_NODE_IGNORE_DIAGNOSTICS
ts-node -I < regexp matching ignored files >
ts-node --ignore < regexp matching ignored files >تجاوز أنماط المسار لتخطي التجميع
افتراضي: /node_modules/
البيئة: TS_NODE_IGNORE
ts-node --skipIgnoreتخطي تجاهل الشيكات
الافتراضي: false
البيئة: TS_NODE_SKIP_IGNORE
ts-node -C < name >
ts-node --compiler < name >حدد برنامج التحويل البرمجي TypeScript مخصص
الافتراضي: typescript
البيئة: TS_NODE_COMPILER
ts-node --swc transpile مع SWC. يعني --transpileOnly
الافتراضي: false
ts-node --transpiler < name >
# Example
ts-node --transpiler ts-node/transpilers/swcاستخدم جهاز Transpiler من طرف ثالث
ts-node --preferTsExtsإعادة ترتيب ملحقات الملفات بحيث تفضل واردات typeScript
الافتراضي: false
البيئة: TS_NODE_PREFER_TS_EXTS
ts-node --logErrorسجلات TypeScript أخطاء إلى Stderr بدلاً من إلقاء الاستثناءات
الافتراضي: false
البيئة: TS_NODE_LOG_ERROR
ts-node --prettyاستخدم التنسيق التشخيصي الجميل
الافتراضي: false
البيئة: TS_NODE_PRETTY
TS_NODE_DEBUG=true ts-nodeتمكين تسجيل التصحيح
ts-node -r < module name or path >
ts-node --require < module name or path >تتطلب وحدة عقدة قبل التنفيذ
ts-node --cwd < path/to/directory >تتصرف كما لو تم الاحتجاج به في دليل العمل هذا
الافتراضي: process.cwd()
البيئة: TS_NODE_CWD
ts-node --emit تنبعث من ملفات الإخراج في دليل .ts-node . يتطلب --compilerHost
الافتراضي: false
البيئة: TS_NODE_EMIT
ts-node --scope النطاق المترجم إلى الملفات داخل scopeDir . يتم تجاهل أي شيء خارج هذا الدليل.
الافتراضي: false
البيئة: TS_NODE_SCOPE
ts-node --scopeDir < path/to/directory > الدليل الذي يكون فيه التحويل البرمجي محدودًا عند تمكين scope .
الافتراضي: أولاً من: tsconfig.json "rootdir" في حالة تحديد ، دليل يحتوي على tsconfig.json ، أو cwd إذا لم يتم تحميل tsconfig.json .
البيئة: TS_NODE_SCOPE_DIR
تجاوز نوع الوحدة النمطية لبعض الملفات ، متجاهلة حقل package.json "type" . انظر تجاوز نوع الوحدة للحصول على التفاصيل.
الافتراضي: Obeys package.json "type" و tsconfig.json "module"
لا يمكن تحديدها إلا عبر tsconfig.json أو API.
TS_NODE_HISTORY= < path/to/history/file > ts-nodeمسار إلى ملف السجل للاستبدال
الافتراضي: ~/.ts_node_repl_history
ts-node --noExperimentalReplAwait تعطيل المستوى الأعلى في انتظار REPL. أي ما يعادل العقدة --no-experimental-repl-await
الافتراضي: ممكّن إذا كان إصدار TypeScript 3.8 أو أعلى والهدف هو ES2018 أو أعلى.
البيئة: TS_NODE_EXPERIMENTAL_REPL_AWAIT set false لتعطيل
قم بتمكين السنانير التجريبية التي تعيد الواردات وتتطلب مكالمات لدعمها:
import "./foo.js" تنفيذ foo.ts حاليا سيتم تعيين الامتدادات التالية:.js إلى .ts ، .tsx ، أو .jsx.cjs إلى .cts.mjs إلى .mts.jsx إلى .tsxفي المستقبل ، سيدعم هذا الخطاف أيضًا:
baseUrl ، pathsrootDirsoutDir إلى تعيينات rootDir للمشاريع المركبة والونوروبوسللحصول على التفاصيل ، انظر #1514.
افتراضي: false ، ولكن من المحتمل أن يتم تمكينه افتراضيًا في إصدار مستقبلي
لا يمكن تحديدها إلا عبر tsconfig.json أو API.
ts-node --experimentalSpecifierResolution node مثل Node's- --experimental-specifier-resolution ، ولكن يمكن أيضًا تعيينها في tsconfig.json للراحة. يتطلب تمكين esm .
الافتراضي: explicit
يتضمن واجهة برمجة التطبيقات خيارات إضافية غير معروضة هنا.
دعم SWC مدمج عبر علامة- --swc أو "swc": true .
SWC عبارة عن جهاز نقل متوافق مع TypeScript الذي تم تنفيذه في الصدأ. هذا يجعلها ترتيبًا أسرع من transpileOnly .
لاستخدامه ، قم أولاً بتثبيت @swc/core أو @swc/wasm . إذا كنت تستخدم importHelpers ، قم أيضًا بتثبيت @swc/helpers . إذا كان target أقل من "ES2015" واستخدام وظائف async / await أو المولد ، فستقوم أيضًا بتثبيت regenerator-runtime .
npm i -D @swc/core @swc/helpers regenerator-runtime ثم أضف ما يلي إلى tsconfig.json .
{
"ts-node" : {
"swc" : true
}
}يستخدم SWC
@swc/helpersبدلاً منtslib. إذا كنت قد قمت بتمكينimportHelpers، فيجب عليك أيضًا تثبيت@swc/helpers.
تتم كتابة TypeScript دائمًا تقريبًا باستخدام بناء جملة import الحديثة ، ولكن يتم تحويلها أيضًا قبل تنفيذها بواسطة وقت التشغيل الأساسي. يمكنك اختيار إما التحويل إلى CommonJs أو الحفاظ على بناء جملة import الأصلي ، باستخدام دعم ESM الأصلي للعقدة. التكوين مختلف لكل.
هنا مقارنة موجزة بين الاثنين.
| CommonJs | وحدات ecmascript الأصلية |
|---|---|
اكتب بناء جملة import الأصلي | اكتب بناء جملة import الأصلي |
يحول import إلى require() | لا يحول import |
| تنفذ العقدة البرامج النصية باستخدام محمل Commonjs الكلاسيكي | تنفذ العقدة البرامج النصية باستخدام محمل ESM الجديد |
استخدم أي من:ts-nodenode -r ts-node/registerNODE_OPTIONS="ts-node/register" noderequire('ts-node').register({/* options */}) | استخدم أي من:ts-node --esmts-node-esmتعيين "esm": true في tsconfig.jsonnode --loader ts-node/esmNODE_OPTIONS="--loader ts-node/esm" node |
عادة ما يكون التحويل إلى CommonJs أبسط وأكثر دعمًا على نطاق واسع لأنه أقدم. يجب إزالة "type": "module" من package.json وتعيين "module": "CommonJS" في tsconfig.json .
{
// This can be omitted; commonjs is the default
"type" : "commonjs"
} {
"compilerOptions" : {
"module" : "CommonJS"
}
} إذا كان يجب عليك الاحتفاظ بـ "module": "ESNext" لـ tsc أو WebPack أو أداة إنشاء أخرى ، فيمكنك تعيين تجاوز لـ TS-Node.
{
"compilerOptions" : {
"module" : "ESNext"
} ,
"ts-node" : {
"compilerOptions" : {
"module" : "CommonJS"
}
}
} السنانير المحمولة ESM للعقدة تجريبية وتخضع للتغيير. يعد دعم ESM الخاص بـ TS-Node مستقرًا قدر الإمكان ، لكنه يعتمد على واجهات برمجة التطبيقات التي يمكن للعقدة أن تنكسر في إصدارات جديدة من العقدة. وبالتالي لا ينصح بالإنتاج.
للاطلاع على الاستخدام الكامل والقيود وتوفير التعليقات ، انظر #1007.
يجب تعيين "type": "module" في package.json و "module": "ESNext" في tsconfig.json .
{
"type" : "module"
} {
"compilerOptions" : {
"module" : "ESNext" // or ES2015, ES2020
} ,
"ts-node" : {
// Tell ts-node CLI to install the --loader automatically, explained below
"esm" : true
}
} يجب عليك أيضًا ضمان تمرير --loader . ستقوم TS-DONODE CLI بذلك تلقائيًا باستخدام خيار esm الخاص بنا.
ملاحظة: -يجب أن تفرخ
--esmعملية الطفل لتمريرها--loader. قد يتغير هذا إذا أضافت العقدة القدرة على تثبيت خطافات المحمل في العملية الحالية.
# pass the flag
ts-node --esm
# Use the convenience binary
ts-node-esm
# or add `"esm": true` to your tsconfig.json to make it automatic
ts-nodeإذا كنت لا تستخدم CLI لدينا ، فمرر علامة المحمل إلى العقدة.
node --loader ts-node/esm ./index.ts
# Or via environment variable
NODE_OPTIONS= " --loader ts-node/esm " node ./index.ts يستخدم TS-Node تكوينات افتراضية معقولة لتقليل Boilerplate مع الاستمرار في احترام tsconfig.json إذا كان لديك واحد. إذا لم تكن متأكدًا من التكوين الذي يتم استخدامه ، فيمكنك تسجيله باستخدام ts-node --showConfig . هذا مشابه لخيارات tsc --showConfig ولكنه يتضمن خيارات "ts-node" أيضًا.
تحترم TS-NODE أيضًا إصدار typescript المثبت محليًا ، ولكن التثبيت العالمي يعطل على typescript . إذا لم تكن متأكدًا من الإصدارات المستخدمة ، فسيقوم ts-node -vv بتسجيلها.
$ ts-node -vv
ts-node v10.0.0
node v16.1.0
compiler v4.2.2
$ ts-node --showConfig
{
" compilerOptions " : {
" target " : " es6 " ,
" lib " : [
" es6 " ,
" dom "
],
" rootDir " : " ./src " ,
" outDir " : " ./.ts-node " ,
" module " : " commonjs " ,
" moduleResolution " : " node " ,
" strict " : true,
" declaration " : false,
" sourceMap " : true,
" inlineSources " : true,
" types " : [
" node "
],
" stripInternal " : true,
" incremental " : true,
" skipLibCheck " : true,
" importsNotUsedAsValues " : " error " ,
" inlineSourceMap " : false,
" noEmit " : false
},
" ts-node " : {
" cwd " : " /d/project " ,
" projectSearchDir " : " /d/project " ,
" require " : [],
" project " : " /d/project/tsconfig.json "
}
} من المهم التمييز بين الأخطاء عن TS-Node ، والأخطاء من برنامج التحويل البرمجي TypeScript ، والأخطاء من node . من المهم أيضًا أن نفهم عندما تكون الأخطاء ناتجة عن خطأ في النوع في الكود الخاص بك ، أو خطأ في الرمز الخاص بك ، أو عيب في التكوين الخاص بك.
TSError اكتب الأخطاء من التحويل البرمجي يتم إلقاؤها على أنها TSError . هذه هي نفس الأخطاء التي تحصل عليها من tsc .
SyntaxError أي خطأ ليس TSError هو من node.js (على سبيل المثال SyntaxError ) ، ولا يمكن إصلاحه بواسطة typeScript أو ts-node. هذه أخطاء في الكود أو التكوين الخاص بك.
قد لا يدعم إصدار node الخاص بك جميع بناء جملة JavaScript المدعوم من TypeScript. يجب أن يحول المترجم هذا الجملة هذا عبر خيار "التسوية السفلية" ، والذي يتم التحكم فيه بواسطة خيار TSConfig "target" . وإلا فإن الكود الخاص بك سوف يجمع بشكل جيد ، ولكن العقدة ستلقي SyntaxError .
على سبيل المثال ، node 12 لا تفهم ?. مشغل التسلسل الاختياري. إذا كنت تستخدم "target": "esnext" ، فإن بناء جملة TypeScript التالي:
const bar : string | undefined = foo ?. bar ;سوف يجمع في هذا javaScript:
const a = foo ?. bar ; عندما تحاول تشغيل هذا الرمز ، ستقوم Node 12 بإلقاء SyntaxError . لإصلاح هذا ، يجب أن تبدي إلى "target": "es2019" أو أقل حتى تحولات typescript ?. في شيء ما يمكن أن تفهم node .
ERR_REQUIRE_ESM يتم إلقاء هذا الخطأ بواسطة العقدة عندما تكون الوحدة النمطية require() D ، لكن العقدة تعتقد أنه يجب تنفيذها كـ ESM الأصلي. يمكن أن يحدث هذا لعدة أسباب:
webpack.config.ts ، والذي يجب تنفيذه كـ commonjs.ctsERR_UNKNOWN_FILE_EXTENSIONيتم إلقاء هذا الخطأ بواسطة العقدة عندما تحتوي الوحدة على امتداد ملف غير معترف به ، أو لا يوجد امتداد على الإطلاق ، ويتم تنفيذه كـ ESM الأصلي. يمكن أن يحدث هذا لعدة أسباب:
mocha .ts-node-esm ، ts-node --esm ، أو إضافة "ts-node": {"esm": true} إلى tsconfig.json. مستنداتwebpack.config.ts ، والذي يجب تنفيذه كـ commonjs.cts لا تقوم TS-Node بتحميل files بفارغ الصبر ، include أو exclude افتراضيًا. وذلك لأن الغالبية العظمى من المشاريع لا تستخدم جميع الملفات في دليل المشروع (على سبيل المثال Gulpfile.ts ، اختبارات وقت التشغيل مقابل) وتوحل كل ملف لأنواع الأنواع يبطئ وقت بدء التشغيل. بدلاً من ذلك ، تبدأ TS-Node بملف البرنامج النصي (على سبيل المثال ts-node index.ts ) و TypeScript يحل التبعيات بناءً على الواردات والمراجع.
في بعض الأحيان ، يؤدي هذا التحسين إلى أنواع مفقودة. لحسن الحظ ، هناك طرق أخرى لتضمينها في TypeChecking.
بالنسبة للتعريفات العالمية ، يمكنك استخدام خيار typeRoots برنامج التحويل البرمجي. يتطلب ذلك تنظيم تعريفات النوع الخاص بك كحزم نوع (وليس ملفات تعريف TypeScript). يمكن العثور على مزيد من التفاصيل حول كيفية عمل هذا في دليل TypeScript.
مثال tsconfig.json :
{
"compilerOptions" : {
"typeRoots" : [ "./node_modules/@types" , "./typings" ]
}
}مثال بنية المشروع:
<project_root>/
-- tsconfig.json
-- typings/
-- <module_name>/
-- index.d.ts
مثال ملف إعلان الوحدة النمطية:
declare module '<module_name>' {
// module definitions go here
} للحصول على تعريفات الوحدة ، يمكنك استخدام paths :
{
"compilerOptions" : {
"baseUrl" : "." ,
"paths" : {
"custom-module-type" : [ "types/custom-module-type" ]
}
}
} خيار آخر هو توجيهات Triple-Slash. قد يكون هذا مفيدًا إذا كنت تفضل عدم تغيير compilerOptions أو بنية تعريفات النوع الخاصة بك لـ typeRoots . فيما يلي مثال على توجيه ثلاثي الإزاحة كمسار نسبي داخل مشروعك:
/// <reference path="./types/lib_greeter" />
import { Greeter } from "lib_greeter"
const g = new Greeter ( ) ;
g . sayHello ( ) ; إذا لم يكن أي من العمل أعلاه ، ويجب عليك استخدام files أو include أو exclude خيار files .
عند تنفيذ TypeScript باستخدام npx أو yarn dlx ، يوجد الرمز ضمن دليل node_modules مؤقتًا.
يتم تجاهل محتويات node_modules بشكل افتراضي. إذا فشل التنفيذ ، تمكين skipIgnore .
هذه الحيل ستجعل TS-DODEST أسرع.
غالبًا ما يكون من الأفضل typecheck كجزء من اختباراتك أو ترنك. يمكنك تشغيل tsc --noEmit للقيام بذلك. في هذه الحالات ، يمكن لـ TS-Node تخطي TypeCking ، مما يجعله أسرع بكثير.
لتخطي TypeChecking في TS-Node ، قم بعمل واحد مما يلي:
transpileOnly من تخطي typechecking بدون SWC إذا كان يجب عليك تمامًا typecheck في TS-DODER:
require() التي قد تؤدي إلى تكرار typechecking المتكرر ؛ تفضل import--files ؛ قد يكون المرء أسرع اعتمادًا على مشروعكtsc --showConfig ؛ تأكد من تضمين جميع الملفات المنفذةskipLibChecktypes لتجنب تحميل @types غير ضرورية يعمل TS-Node عن طريق تسجيل السنانير لـ .ts و .tsx و .js و/أو .jsx .
أحمال node الفانيليا .js عن طريق قراءة الكود من القرص وتنفيذها. يعمل خطافنا في الوسط ، ويحول الكود من TypeScript إلى JavaScript ويمرر النتيجة إلى node للتنفيذ. سيحترم هذا التحول tsconfig.json كما لو كنت قد جمعت عبر tsc .
نقوم أيضًا بتسجيل بعض السنانير الأخرى لتطبيق sourcemaps لتكديس آثار و remap من .js واردات إلى .ts .
TS-Node يحول بعض الملفات ويتجاهل الآخرين. نشير إلى هذه الآلية على أنها "تحديد النطاق". هناك العديد من الخيارات لتكوين النطاق ، بحيث تقوم TS-DODENG بتحويل الملفات فقط في مشروعك.
تحذير:
لا يزال من الممكن تنفيذ ملف تم تجاهله بواسطة Node.js. تجاهل ملف يعني أننا لا نقوم بتحويله من TypeScript إلى JavaScript ، لكنه لا يمنع التنفيذ.
إذا كان ملفًا يتطلب تحويلًا ولكن تم تجاهله ، فقد تفشل العقدة في حلها أو محاولة تنفيذها كـ Vanilla JavaScript. قد يتسبب ذلك في أخطاء بناء الجملة أو الفشل الأخرى ، لأن العقدة لا تفهم بناء جملة نوع TypeScript أو ميزات Ecmascript حافة النزيف.
يتم تحويل .js و .jsx فقط عند تمكين allowJs .
يتم تحويل .tsx و .jsx فقط عند تمكين jsx .
تحذير:
عند استخدام TS-NODE مع
allowJs، يتم تحويل جميع ملفات JavaScript غير المجهزة بواسطة TS-DODE.
node_modules بشكل افتراضي ، تتجنب TS-Node تجميع الملفات في /node_modules/ لثلاثة أسباب:
إذا كنت بحاجة إلى استيراد TypeScript غير المنقولة في node_modules ، فاستخدم --skipIgnore أو TS_NODE_SKIP_IGNORE لتجاوز هذا التقييد.
في حالة وجود ملف JavaScript الذي تم تجميعه بنفس الاسم الذي يوجد به ملف TypeScript بالفعل ، سيتم تجاهل ملف TypeScript. سوف تستورد TS-Node javaScript مسبقًا.
لإجبار TS-Node على استيراد مصدر TypeScript ، وليس JavaScript مسبقًا ، استخدم- --preferTsExts .
سيحدد خيارات scope و scopeDir من التحويل إلى الملفات داخل الدليل.
سوف يتجاهل خيار ignore لدينا الملفات التي تطابق تعبيرات منتظمة أو أكثر.
يمكنك استخدام TS-Node مع مسارات TSConfig لتحميل الوحدات النمطية وفقًا لقسم paths في tsconfig.json .
{
"ts-node" : {
// Do not forget to `npm i -D tsconfig-paths`
"require" : [ "tsconfig-paths/register" ]
}
} يشرح دليل TypeScript الرسمي الغرض المقصود لـ "paths" في "أعلام دقة الوحدة الإضافية".
يحتوي برنامج التحويل البرمجي TypeScript على مجموعة من الأعلام الإضافية لإبلاغ المترجم بالتحولات التي من المتوقع أن تحدث للمصادر لإنشاء الإخراج النهائي.
من المهم أن نلاحظ أن المترجم لن يقوم بأي من هذه التحولات ؛ إنه يستخدم فقط أجزاء من المعلومات لتوجيه عملية حل وحدة استيراد الوحدة النمطية إلى ملف التعريف الخاص بها.
هذا يعني أن "paths" تهدف إلى وصف التعيينات التي يؤديها أداة الإنشاء أو وقت التشغيل بالفعل ، وليس لإخبار أداة الإنشاء أو وقت التشغيل كيفية حل الوحدات. وبعبارة أخرى ، فإنهم يعتزمون كتابة وارداتنا بطريقة تفهمها node بالفعل. لهذا السبب ، لا تقوم TS-Node بتعديل سلوك قرار الوحدة في node لتنفيذ تعيينات "paths" .
تتطلب بعض المشاريع مترجم TypeScript المصحح الذي يضيف ميزات إضافية. على سبيل المثال ، تضيف ttypescript و ts-patch القدرة على تكوين محولات مخصصة. هذه هي بدائل إسقاط لوحدة الفانيليا typescript وتنفيذ نفس واجهة برمجة التطبيقات.
على سبيل المثال ، لاستخدام ttypescript و ts-transformer-keys ، أضف هذا إلى tsconfig.json :
{
"ts-node" : {
// This can be omitted when using ts-patch
"compiler" : "ttypescript"
} ,
"compilerOptions" : {
// plugin configuration is the same for both ts-patch and ttypescript
"plugins" : [
{ "transform" : "ts-transformer-keys/transformer" }
]
}
} يدعم TS-Node جهاز إرسال الأطراف الثالثة كملابس إضافية. يمكن لعمليات النقل مثل SWC تحويل TypeScript إلى JavaScript بشكل أسرع بكثير من برنامج التحويل البرمجي TypeScript. ستظل تستفيد من tsconfig.json Discovery و Sourcemap دعم TS-Dewse و Sourcemap و Global TS-DODE CLI. تستمد المكونات الإضافية تلقائيًا تكوينًا مناسبًا من tsconfig.json الحالي الذي يبسط Project Boilerplate.
ما هو الفرق بين التحويل البرمجي وجهاز Transpiler؟
لأغراضنا ، يقوم برنامج التحويل البرمجي بتنفيذ واجهة برمجة تطبيقات TypeScript ويمكنه أداء TypeChecking. جهاز Transpiler الطرف الثالث لا. كلا تحويل typeScript إلى JavaScript.
يسمح خيار transpiler باستخدام المكونات الإضافية Transpiler من طرف ثالث مع TS-Node. يجب إعطاء transpiler اسم الوحدة التي يمكن أن تكون require() د. يتعرض المكون الإضافي swc المدمج على أنه ts-node/transpilers/swc .
على سبيل المثال ، لاستخدام " @cspotcode/fast-ts-compiler" ، قم أولاً بتثبيته في مشروعك: npm install @cspotcode/fast-ts-compiler
ثم أضف ما يلي إلى tsconfig الخاص بك:
{
"ts-node" : {
"transpileOnly" : true ,
"transpiler" : "@cspotcode/fast-ts-compiler"
}
}لكتابة البرنامج المساعد الخاص بك Transpiler ، تحقق من مستندات API الخاصة بنا.
الإضافات require() D بواسطة TS-Node ، بحيث يمكن أن تكون نصًا محليًا أو وحدة عقدة منشورة على NPM. يجب أن تصدر الوحدة وظيفة create موصوفة بواسطة واجهة TranspilerModule الخاصة بنا. يتم استدعاء create بواسطة TS-NODE عند بدء التشغيل لإنشاء مثيلات أو أكثر من Transpiler. يتم استخدام الحالات لتحويل TypeScript إلى JavaScript.
للحصول على مثال عمل ، تحقق من المكون الإضافي SWC الخاص بنا: https://github.com/typestrong/ts-node/blob/main/src/transpilers/swc.ts
كلما كان ذلك ممكنًا ، يوصى باستخدام وضع
NodeNextأوNode16الخاص بـ TypeScript بدلاً من الخيارات الموضحة في هذا القسم. تعيين"module": "NodeNext"واستخدام ملحق ملف.ctsيجب أن يعمل بشكل جيد لمعظم المشاريع.
عند تحديد كيفية تجميع الملف وتنفيذه-إما شائع أو وحدة ECMASCRIPT الأصلية-يتطابق TS-NODE إلى سلوك node وسلوك tsc . هذا يعني أنه يتم تحويل ملفات typeScript وفقًا لخيار tsconfig.json "module" وتنفيذها وفقًا لقواعد Node الخاصة بـ package.json "type" . تعيين "module": "NodeNext" وكل شيء يجب أن يعمل.
في حالات نادرة ، قد تحتاج إلى تجاوز هذا السلوك لبعض الملفات. على سبيل المثال ، تقرأ بعض الأدوات name-of-tool.config.ts . إذا كان لديك package.json تم تكوينه باستخدام "type": "module" و tsconfig.json مع "module": "esnext" ، فإن التكوين هو ecmascript الأصلي بشكل افتراضي وسيثير خطأ. ستحتاج إلى فرض التكوين وأي البرامج النصية الداعمة للتنفيذ على أنها شائعة.
في هذه الحالات ، يمكن أن يتجاوز خيار moduleTypes الخاص بنا بعض الملفات الشائعة أو ESM. يمكن الإفراط في الإفراط في الاستخدام باستخدام ملحقات ملف .mts و .cts و .cjs و .mjs . يحقق moduleTypes نفس التأثير لملفات .ts و .js ، ويتجاوز أيضًا تكوين tsconfig.json "module" بشكل مناسب.
يوضح المثال التالي TS-NODE لتنفيذ تكوين WebPack كـ CommonJs:
{
"ts-node" : {
"transpileOnly" : true ,
"moduleTypes" : {
"webpack.config.ts" : "cjs" ,
// Globs are also supported with the same behavior as tsconfig "include"
"webpack-config-scripts/**/*" : "cjs"
}
} ,
"compilerOptions" : {
"module" : "es2020" ,
"target" : "es2020"
}
} كل مفتاح هو نمط كروي مع نفس بناء الجملة مثل مجموعة TSConfig "include" . عندما تتطابق أنماط متعددة في نفس الملف ، فإن النمط الأخير له الأسبقية.
cjs لتلائم الملفات لتجميع وتنفيذ كشائعين.esm يطابق الملفات لتجميع وتنفيذ وحدات ecmascript الأصلية.package إعادة تعيين أي من ما سبق إلى السلوك الافتراضي ، والذي يطيع package.json "type" و tsconfig.json "module" . يتم تحويل الملفات ذات نوع الوحدة النمطية المتجاوز مع نفس القيود مثل isolatedModules . سيؤثر هذا فقط على حالات نادرة مثل استخدام const enum s مع تعطيل preserveConstEnums .
تهدف هذه الميزة إلى تسهيل السيناريوهات حيث لا يمكن تكوين compilerOptions العادي و package.json . على سبيل المثال ، لا يمكن إعطاء webpack.config.ts package.json الخاصة به. json لتجاوز "type" . كلما أمكن ، يجب أن تفضل استخدام تكوينات package.json و tsconfig.json .
تم توثيق واجهة برمجة تطبيقات TS-DOODE الكاملة هنا: مستندات API
فيما يلي بعض النقاط البارزة لما يمكنك إنجازه:
create() ينشئ خدمة برنامج التحويل البرمجي TS-Node دون تسجيل أي خطافات.createRepl() بإنشاء مثيل لخدمة Repl ، حتى تتمكن من إنشاء Repls التي تعمل بنظام TypeScript.createEsmHooks() ينشئ خطافات Loader ESM الخاصة بنا ، مناسبة للتأليف مع اللوادر الأخرى أو زيادة الميزات الإضافية.تركز TS-Node على إضافة دعم TypeScript من الدرجة الأولى إلى العقدة. مشاهدة الملفات وإعادة تحميل التعليمات البرمجية خارج نطاق المشروع.
إذا كنت ترغب في إعادة تشغيل عملية ts-node في الملف ، فإن أدوات NODE.JS الحالية مثل NODEMON و ONCHANGE و NODE-DEV.
هناك أيضًا ts-node-dev ، وهو إصدار معدّل من node-dev باستخدام ts-node للتجميع الذي سيعيد تشغيل العملية في تغيير الملف. لاحظ أن ts-node-dev غير متوافق مع محمل ESM الأصلي.
على افتراض أنك تقوم بتكوين AVA عبر package.json ، أضف أحد التكوينات التالية.
استخدم هذا التكوين إذا لم يكن لدى package.json "type": "module" .
{
"ava" : {
"extensions" : [
"ts"
] ,
"require" : [
"ts-node/register"
]
}
} هذا التكوين ضروري إذا كان package.json الخاصة بك "type": "module" .
{
"ava" : {
"extensions" : {
"ts" : "module"
} ,
"nonSemVerExperiments" : {
"configurableModuleFormat" : true
} ,
"nodeArguments" : [
"--loader=ts-node/esm"
]
}
} دعم TS-DONODE مدمج في GULP.
# Create a `gulpfile.ts` and run `gulp`.
gulpانظر أيضًا: https://gulpjs.com/docs/en/getting-started/javaScript-and-gulpfiles#transpilation
قم بإنشاء تكوين node.js جديد وأضف -r ts-node/register إلى "معلمات العقدة."
ملاحظة: إذا كنت تستخدم وسيطة سطر الأوامر --project <tsconfig.json> وفقًا لخيارات التكوين ، وتريد تطبيق هذا السلوك نفسه عند الإطلاق في intellij ، حدد ضمن "متغيرات البيئة": TS_NODE_PROJECT=<tsconfig.json> .
mocha --require ts-node/register --extensions ts,tsx --watch --watch-files src ' tests/**/*.{ts,tsx} ' [...args]أو حدد الخيارات عبر ملف تكوين Mocha الخاص بك.
{
// Specify "require" for CommonJS
"require" : "ts-node/register" ,
// Specify "loader" for native ESM
"loader" : "ts-node/esm" ,
"extensions" : [ "ts" , "tsx" ] ,
"spec" : [
"tests/**/*.spec.*"
] ,
"watch-files" : [
"src"
]
}انظر أيضًا: https://mochajs.org/#configuring-mocha-nodejs
mocha --require ts-node/register --watch-extensions ts,tsx " test/**/*.{ts,tsx} " [...args] ملاحظة: -يتم استخدام --watch-extensions فقط في- --watch Mode.
ts-node node_modules/tape/bin/tape [...args] قم بإنشاء تكوين تصحيح Node.js جديد ، أضف -r ts-node/register إلى العقدة ونقل program إلى قائمة args (لذلك لا يبحث VS Code عن outFiles ).
{
"configurations" : [ {
"type" : "node" ,
"request" : "launch" ,
"name" : "Launch Program" ,
"runtimeArgs" : [
"-r" ,
"ts-node/register"
] ,
"args" : [
"${workspaceFolder}/src/index.ts"
]
} ] ,
} ملاحظة: إذا كنت تستخدم وسيطة سطر الأوامر --project <tsconfig.json> وفقًا لخيارات التكوين ، وتريد تطبيق هذا السلوك نفسه عند الإطلاق في VS Code ، أضف مفتاح "ENV" في تكوين التشغيل: "env": { "TS_NODE_PROJECT": "<tsconfig.json>" } .
في كثير من الحالات ، سيمكن تعيين NODE_OPTIONS ts-node داخل أدوات العقدة الأخرى وعمليات الطفل ومواضيع العمال.
NODE_OPTIONS= " -r ts-node/register "أو ، إذا كنت بحاجة إلى دعم ESM الأصلي:
NODE_OPTIONS= " --loader ts-node/esm " هذا يخبر أي عمليات عقدة تتلقى هذا البيئة متغيرًا لتثبيت خطافات ts-node قبل تنفيذ التعليمات البرمجية الأخرى.
تم ترخيص TS-Node بموجب ترخيص MIT. معهد ماساتشوستس للتكنولوجيا
يتضمن TS-Node رمز المصدر من Node.js المرخص له بموجب ترخيص MIT. معلومات الترخيص Node.JS
يتضمن TS-Node رمز المصدر من برنامج التحويل البرمجي TypeScript الذي يتم ترخيصه بموجب ترخيص Apache 2.0. معلومات ترخيص TypeScript
