تثبيت TypeScript باستخدام npm ومعرفة الإصدار

TypeScript حزمة npm اسمها typescript. ثبّتها في مشروعك وتحقق من أنها تعمل:

npm install --save-dev typescript
npx tsc --version

Version 7.0.2

توفر الحزمة الأمر tsc، وهو مترجم TypeScript. تحتاج إلى Node.js وnpm (الذي يأتي مع Node.js) لتثبيتها؛ احصل على Node.js من nodejs.org أو من مدير الحزم في نظامك، وتحقق منه بـ node --version.

لا تحتاج إلى تثبيت أي شيء لتجربة TypeScript. هذا المثال يُترجم ويعمل في متصفحك:

function add(a: number, b: number): number {
    return a + b;
}

console.log(`2 + 3 = ${add(2, 3)}`);

تثبيت TypeScript في مشروع

التثبيت الموصى به محلي، كاعتمادية تطوير للمشروع:

mkdir hello-ts
cd hello-ts
npm init -y
npm install --save-dev typescript

يضع npm install --save-dev typescript (صيغته المختصرة npm i -D typescript) المترجم في node_modules ويسجله في package.json:

{
    "devDependencies": {
        "typescript": "^7.0.2"
    }
}

هي اعتمادية تطوير لأنها لازمة لبناء الكود فقط، لا لتشغيله. كل من ينسخ المشروع ويشغّل npm install يحصل على إصدار المترجم نفسه.

لتشغيل المترجم المحلي، اسبقه بـ npx، الذي يبحث عن الأوامر في node_modules/.bin:

npx tsc --version

داخل سكربتات package.json يمكنك كتابة tsc دون npx، لأن npm يضيف node_modules/.bin إلى PATH عند تشغيل السكربتات:

{
    "scripts": {
        "build": "tsc",
        "typecheck": "tsc --noEmit"
    }
}

بعدها يترجم npm run build الكود، ويفحص npm run typecheck الأنواع دون كتابة أي ملف.

معرفة إصدار TypeScript

npm ls typescript

hello-ts@1.0.0 /home/ana/hello-ts
└── typescript@7.0.2

إذا طبع npx tsc --version وtsc --version إصدارين مختلفين، فللمشروع مترجمه الخاص والمترجم العام أقدم أو أحدث منه. إصدار المشروع هو المهم في بنائه.

تثبيت TypeScript عالميًا

يمنحك التثبيت العام أمر tsc في كل طرفية، دون npx:

npm install -g typescript
tsc --version

على macOS وLinux قد يفشل هذا بأخطاء صلاحيات EACCES عندما يكون Node.js مثبتًا على مستوى النظام. تثبيت Node.js عبر مدير إصدارات مثل nvm أو fnm يتجنب ذلك، ولا يُنصح باستخدام sudo npm install -g.

استخدم الأمر العام للتجارب السريعة. أما في مشروع حقيقي فاحتفظ بتثبيت محلي أيضًا: عندها يسجل package.json الإصدار، ولا يستطيع تحديث المترجم العام تغيير طريقة بناء المشروع.

التثبيت باستخدام pnpm أو Yarn أو Bun

كل مدير حزم JavaScript يثبّت الحزمة نفسها:

pnpm add -D typescript
yarn add -D typescript
bun add -d typescript

شغّل المترجم بـ pnpm tsc أو yarn tsc أو bunx tsc.

إنشاء tsconfig.json باستخدام tsc --init

ملف tsconfig.json يجعل المجلد مشروع TypeScript ويحمل خيارات المترجم. أنشئ واحدًا:

npx tsc --init

Created a new tsconfig.json

You can learn more at https://aka.ms/tsconfig

الملف المُنشأ (في TypeScript 7) يفعّل strict وبعض الفحوص الأخرى، ويستخدم "module": "nodenext" و"target": "esnext"، ويحتوي على أسطر معلّقة لـ rootDir وoutDir. أزل التعليق عن هذين السطرين حتى يقرأ المترجم من src ويكتب إلى dist:

{
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist",
        "module": "nodenext",
        "target": "esnext",
        "types": [],
        "strict": true
    }
}

هذا عرض مختصر؛ الملف الحقيقي يحتوي على خيارات أكثر، ولكل منها تعليق. تشرح صفحة tsconfig وظيفتها. وتشغيل npx tsc --init مرة أخرى في المجلد نفسه يفشل بالخطأ error TS5054: A 'tsconfig.json' file is already defined، لذلك لا يستبدل إعداداتك أبدًا.

ترجمة أول ملف

أنشئ src/index.ts:

function greet(name: string): string {
    return `Hello, ${name}!`;
}

const names = ["Ada", "Grace", "Linus"];
for (const name of names) {
    console.log(greet(name));
}

ثم ترجم وشغّل:

npx tsc
node dist/index.js

Hello, Ada!
Hello, Grace!
Hello, Linus!

يقرأ npx tsc دون وسائط ملف tsconfig.json، ويفحص أنواع كل ملف يتضمنه، ويكتب الناتج في dist. مع الإعدادات المُنشأة تحصل على index.js إضافة إلى index.d.ts (تعريفات الأنواع) وملفات .map (خرائط المصدر) لكل ملف.

أمران يجب معرفتهما عن الناتج:

• أخطاء الأنواع لا توقف الناتج افتراضيًا. يبلّغ tsc عن الأخطاء، وينتهي برمز خروج غير صفري، ومع ذلك يكتب JavaScript. اضبط "noEmitOnError": true حتى لا يُكتب شيء ما دامت هناك أخطاء.
• عند وجود tsconfig.json لا تمرر أسماء ملفات. الأمر npx tsc src/index.ts يفشل بالخطأ error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. شغّل npx tsc وحده، أو أضف --ignoreConfig إذا أردت فعلًا ترجمة ملف واحد بالإعدادات الافتراضية.

وضع المراقبة

يُبقي الخيار --watch (المختصر -w) المترجم يعمل ويعيد الترجمة كلما تغيّر ملف:

npx tsc --watch

06:28:22 AM - Starting compilation in watch mode...

06:28:22 AM - Found 0 errors. Watching for file changes.

اتركه مفتوحًا في طرفية بجانب محررك. أوقفه بـ Ctrl+C.

تثبيت إصدار محدد من TypeScript

أضف الإصدار بعد @:

npm install --save-dev typescript@7.0.2   # an exact version
npm install --save-dev typescript@6       # the newest 6.x
npm install --save-dev typescript@latest  # the newest stable release
npm install --save-dev typescript@next    # nightly builds of the next version

TypeScript 6 هو آخر إصدار مترجمه مكتوب بـ JavaScript. بعض الأدوات التي تستدعي واجهة JavaScript البرمجية للمترجم ما زالت تحتاج إليه، وهذا ما تغطيه صفحة TypeScript 7 إلى جانب طريقة الترقية.

إعداد المحرر

يدعم VS Code لغة TypeScript بشكل مدمج: افتح ملف .ts فتحصل على خطوط تحت الأخطاء وإكمال تلقائي وعرض الأنواع عند التمرير وإعادة التسمية دون تثبيت أي شيء. وللحصول على سرعة TypeScript 7 في المحرر، ينشر فريق TypeScript إضافة مخصصة تنقل VS Code إلى خادم اللغة الأصلي في TypeScript 7. يدعم WebStorm وبقية بيئات JetBrains لغة TypeScript مباشرة، وتستخدم Neovim وVim وEmacs وZed وSublime Text خادم لغة TypeScript عبر دعمها لـ LSP.

أخطاء التثبيت الشائعة

This is not the tsc command you are looking for. شغّلت npx tsc في مجلد لم تُثبَّت فيه TypeScript، فجلب npx حزمة قديمة يصادف أن اسمها tsc. ثبّت الحزمة الحقيقية بـ npm install --save-dev typescript.

tsc: command not found، أو 'tsc' is not recognized as an internal or external command على Windows. TypeScript غير مثبتة عالميًا، أو مجلد npm العام ليس ضمن PATH. استخدم npx tsc في مشروع فيه تثبيت محلي، أو ثبّتها عالميًا وافتح طرفية جديدة.

error TS2591: Cannot find name 'process' (أو require؛ أما __dirname فيعطي TS2304). أنواع واجهات Node.js البرمجية موجودة في حزمة منفصلة. ثبّتها بـ npm install --save-dev @types/node، ثم أضف "types": ["node"] إلى compilerOptions: لم تعد TypeScript 7 تحمّل كل حزم @types المثبتة تلقائيًا.

error TS5011: The common source directory of 'tsconfig.json' is './src'. ملفاتك في src وضبطت outDir دون rootDir. أضف "rootDir": "./src".

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. يكتب npm init -y القيمة "type": "commonjs" في package.json، فيعامل إعداد tsc --init ("module": "nodenext" مع verbatimModuleSyntax) كل ملف .ts على أنه CommonJS، حيث لا يُسمح بـ import وexport. غيّرها إلى "type": "module"، واكتب الاستيرادات النسبية بامتداد .js: import { add } from "./math.js".