התקנת 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 בפרויקט

ההתקנה המומלצת היא מקומית, כ-dev dependency של הפרויקט:

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"
    }
}

זה dev dependency כי צריך אותו רק כדי לבנות את הקוד, לא כדי להריץ אותו. כל מי שמשכפל את הפרויקט ומריץ npm install מקבל את אותה גרסת קומפיילר.

כדי להריץ את הקומפיילר המקומי, הוסיפו לפניו npx, שמוצא פקודות ב-node_modules/.bin:

npx tsc --version

בתוך ה-scripts של package.json אפשר לכתוב tsc בלי npx, כי npm מוסיף את node_modules/.bin ל-PATH של ה-scripts:

{
    "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 מדפיסים גרסאות שונות, לפרויקט יש קומפיילר משלו, והגלובלי ישן או חדש יותר. הגרסה של הפרויקט היא זו שקובעת לגבי ה-build שלו.

התקנה גלובלית של 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 (source maps) לכל קובץ.

שני דברים שכדאי לדעת על הפלט:

• שגיאות טיפוסים לא עוצרות את הפלט כברירת מחדל. 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

--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. כלים מסוימים שקוראים ל-API של JavaScript של הקומפיילר עדיין צריכים אותה, והעמוד על TypeScript 7 מסביר את זה יחד עם הדרך לשדרג.

הגדרת העורך

ל-VS Code יש תמיכה מובנית ב-TypeScript: פתחו קובץ .ts ותקבלו סימון שגיאות בקו תחתון, השלמה אוטומטית, טיפוסים במעבר עכבר ושינוי שמות, בלי להתקין כלום. בשביל המהירות של TypeScript 7 בעורך, צוות TypeScript מפרסם תוסף ייעודי שמעביר את VS Code ל-language server הנייטיבי של TypeScript 7. WebStorm ושאר סביבות הפיתוח של JetBrains תומכות ב-TypeScript מהקופסה, ו-Neovim, Vim, Emacs, Zed ו-Sublime Text משתמשים ב-language server של 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). הטיפוסים של ה-API של 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", וכתבו imports יחסיים עם סיומת .js: import { add } from "./math.js".