Cài đặt TypeScript bằng npm và kiểm tra phiên bản

TypeScript là một package npm tên typescript. Cài nó vào dự án và kiểm tra xem đã chạy được chưa:

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

Version 7.0.2

Package này cung cấp lệnh tsc, tức trình biên dịch TypeScript. Bạn cần Node.js và npm (đi kèm Node.js) để cài; tải Node.js từ nodejs.org hoặc trình quản lý package của hệ điều hành, rồi kiểm tra bằng node --version.

Bạn không cần cài gì để thử TypeScript. Khối code này biên dịch và chạy ngay trên trình duyệt:

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

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

Cài TypeScript trong một dự án

Cách cài được khuyên dùng là cài cục bộ, dưới dạng dev dependency của dự án:

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

npm install --save-dev typescript (dạng ngắn npm i -D typescript) đặt trình biên dịch vào node_modules và ghi lại trong package.json:

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

Đây là dev dependency vì nó chỉ cần để build code, không cần để chạy. Ai clone dự án và chạy npm install cũng nhận cùng một phiên bản trình biên dịch.

Để chạy trình biên dịch cục bộ, thêm npx phía trước; npx tìm lệnh trong node_modules/.bin:

npx tsc --version

Trong các script của package.json, bạn có thể viết tsc mà không cần npx, vì npm thêm node_modules/.bin vào PATH khi chạy script:

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

Sau đó npm run build sẽ biên dịch, còn npm run typecheck kiểm tra kiểu mà không ghi ra tệp nào.

Kiểm tra phiên bản TypeScript

npm ls typescript

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

Nếu npx tsc --version và tsc --version in ra hai phiên bản khác nhau, dự án có trình biên dịch riêng và bản toàn cục cũ hơn hoặc mới hơn. Phiên bản của dự án mới là phiên bản quyết định cách nó được build.

Cài TypeScript toàn cục

Cài toàn cục cho bạn lệnh tsc ở mọi terminal mà không cần npx:

npm install -g typescript
tsc --version

Trên macOS và Linux, lệnh này có thể lỗi quyền EACCES khi Node.js được cài cho toàn hệ thống. Cài Node.js qua một trình quản lý phiên bản như nvm hoặc fnm sẽ tránh được lỗi đó, còn sudo npm install -g thì không nên dùng.

Dùng lệnh toàn cục cho những thử nghiệm nhanh. Với dự án thật, hãy giữ thêm một bản cài cục bộ: khi đó package.json ghi lại phiên bản, và việc cập nhật trình biên dịch toàn cục không thể thay đổi cách dự án được build.

Cài bằng pnpm, Yarn hoặc Bun

Mọi trình quản lý package JavaScript đều cài cùng một package:

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

Chạy trình biên dịch bằng pnpm tsc, yarn tsc hoặc bunx tsc.

Tạo tsconfig.json bằng tsc --init

Tệp tsconfig.json đánh dấu một thư mục là dự án TypeScript và chứa các tùy chọn của trình biên dịch. Tạo tệp này:

npx tsc --init

Created a new tsconfig.json

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

Tệp được tạo ra (TypeScript 7) bật strict cùng một số kiểm tra khác, dùng "module": "nodenext" và "target": "esnext", và có các dòng bị chú thích cho rootDir và outDir. Bỏ chú thích hai dòng đó để trình biên dịch đọc từ src và ghi ra dist:

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

Đây là bản rút gọn; tệp thật có nhiều tùy chọn hơn, mỗi tùy chọn kèm một chú thích. Trang tsconfig giải thích chúng làm gì. Chạy lại npx tsc --init trong cùng thư mục sẽ lỗi error TS5054: A 'tsconfig.json' file is already defined, nên lệnh này không bao giờ ghi đè thiết lập của bạn.

Biên dịch tệp đầu tiên

Tạo 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));
}

Rồi biên dịch và chạy:

npx tsc
node dist/index.js

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

npx tsc không kèm đối số sẽ đọc tsconfig.json, kiểm tra kiểu mọi tệp mà nó bao gồm và ghi kết quả vào dist. Với thiết lập được tạo sẵn, mỗi tệp cho ra index.js cùng index.d.ts (khai báo kiểu) và các tệp .map (source map).

Hai điều cần biết về kết quả:

• Mặc định, lỗi kiểu không chặn việc sinh kết quả. tsc báo lỗi, thoát với mã khác 0, và vẫn ghi ra JavaScript. Đặt "noEmitOnError": true để không ghi gì khi còn lỗi.
• Khi đã có tsconfig.json, đừng truyền tên tệp. npx tsc src/index.ts lỗi error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Hãy chạy npx tsc không kèm gì, hoặc thêm --ignoreConfig nếu bạn thật sự muốn biên dịch một tệp với thiết lập mặc định.

Chế độ watch

--watch (dạng ngắn -w) giữ trình biên dịch chạy liên tục và biên dịch lại mỗi khi có tệp thay đổi:

npx tsc --watch

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

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

Để nó chạy trong một terminal cạnh trình soạn thảo. Dừng bằng Ctrl+C.

Cài một phiên bản TypeScript cụ thể

Thêm phiên bản sau dấu @:

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 là phiên bản cuối cùng có trình biên dịch viết bằng JavaScript. Một số công cụ gọi tới API JavaScript của trình biên dịch vẫn cần nó; trang TypeScript 7 nói về điều này cùng cách nâng cấp.

Thiết lập trình soạn thảo

VS Code có sẵn hỗ trợ TypeScript: mở một tệp .ts là bạn có gạch chân lỗi, tự động hoàn thành, xem kiểu khi rê chuột và đổi tên mà không cần cài gì. Để có tốc độ của TypeScript 7 trong trình soạn thảo, nhóm TypeScript phát hành một extension riêng chuyển VS Code sang language server TypeScript 7 bản native. WebStorm và các IDE khác của JetBrains hỗ trợ TypeScript ngay từ đầu, còn Neovim, Vim, Emacs, Zed và Sublime Text dùng một language server TypeScript qua hỗ trợ LSP của chúng.

Lỗi cài đặt thường gặp

This is not the tsc command you are looking for. Bạn đã chạy npx tsc trong một thư mục chưa cài TypeScript, và npx tải về một package cũ tình cờ có tên tsc. Cài package thật bằng npm install --save-dev typescript.

tsc: command not found, hoặc 'tsc' is not recognized as an internal or external command trên Windows. TypeScript chưa được cài toàn cục, hoặc thư mục npm toàn cục không nằm trong PATH. Dùng npx tsc trong một dự án có bản cài cục bộ, hoặc cài toàn cục rồi mở một terminal mới.

error TS2591: Cannot find name 'process' (hoặc require; __dirname thì báo TS2304). Kiểu của các API riêng của Node.js nằm trong một package riêng. Cài nó bằng npm install --save-dev @types/node, rồi thêm "types": ["node"] vào compilerOptions: TypeScript 7 không còn tự động nạp mọi package @types đã cài.

error TS5011: The common source directory of 'tsconfig.json' is './src'. Các tệp của bạn nằm trong src và bạn đã đặt outDir nhưng chưa đặt rootDir. Thêm "rootDir": "./src".

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. npm init -y ghi "type": "commonjs" vào package.json, nên cấu hình của tsc --init ("module": "nodenext" cùng verbatimModuleSyntax) coi mọi tệp .ts là CommonJS, nơi import và export không được phép. Đổi thành "type": "module", và viết import tương đối có phần mở rộng .js: import { add } from "./math.js".