Cách chạy file TypeScript: tsc, Node.js, tsx, ts-node

Một tệp TypeScript không thể chạy nguyên trạng, vì trình duyệt và các engine JavaScript không hiểu chú thích kiểu. Phải có thứ gì đó xóa kiểu đi trước. Thứ đó hoặc là trình biên dịch TypeScript (tsc), vốn cũng kiểm tra kiểu, hoặc là một công cụ nhanh hơn chỉ gỡ bỏ kiểu. Cách nhanh nhất để chạy code trên trang này là nút Chạy:

type Task = { title: string; done: boolean };

const tasks: Task[] = [
    { title: "Install TypeScript", done: true },
    { title: "Run a .ts file", done: false },
];

for (const task of tasks) {
    console.log(`${task.done ? "[x]" : "[ ]"} ${task.title}`);
}

Đầu ra:

[x] Install TypeScript
[ ] Run a .ts file

Mọi khối code chạy được trong tài liệu này đều hoạt động giống nhau: code được TypeScript 7 kiểm tra kiểu với strict bật, và chỉ chạy khi không có lỗi kiểu. Với những thử nghiệm dài hơn, playground TypeScript là cùng trình soạn thảo đó trên một trang riêng. Phần còn lại của trang này nói về cách chạy tệp .ts trên máy của bạn.

Tổng quan các lựa chọn

Cột khiến nhiều người bất ngờ là cột đầu tiên: phần lớn các lựa chọn nhanh đều chạy cả code có lỗi kiểu. Một dự án thường chạy code bằng một trong số đó và chạy riêng tsc --noEmit, trong trình soạn thảo và trong CI, để bắt lỗi.

Biên dịch bằng tsc, rồi chạy bằng Node

Đây là cách chạy được ở mọi nơi và kiểm tra mọi thứ. Khi dự án đã cài TypeScript và có tsconfig.json đặt "rootDir": "./src" và "outDir": "./dist":

npx tsc
node dist/index.js

tsc kiểm tra kiểu tất cả các tệp, rồi ghi các tệp .js vào dist. Với một tệp đơn lẻ không thuộc dự án nào, hãy truyền tên tệp. Khi đó nó dùng các tùy chọn mặc định và ghi index.js ngay cạnh index.ts:

npx tsc index.ts
node index.js

(Nếu thư mục có tsconfig.json, tsc sẽ từ chối tên tệp với error TS5112; hãy chạy npx tsc không kèm tên tệp, hoặc thêm --ignoreConfig.)

Mặc định tsc vẫn ghi ra JavaScript khi có lỗi kiểu, nên node có thể chạy một chương trình đã không qua được bước kiểm tra. Thêm "noEmitOnError": true vào cấu hình để ngăn điều đó, hoặc nối các lệnh trong một script để bước thứ hai chỉ chạy khi bước đầu thành công:

{
    "scripts": {
        "build": "tsc",
        "start": "tsc && node dist/index.js"
    }
}

Khi phát triển, npx tsc --watch biên dịch lại mỗi lần bạn lưu.

Chạy TypeScript trực tiếp bằng Node.js

Node.js hiện nay tự chạy được tệp .ts:

node index.ts

Node gỡ bỏ chú thích kiểu, thay chúng bằng khoảng trắng để số dòng trong stack trace vẫn khớp, rồi chạy phần còn lại. Tính năng này bật mặc định từ Node.js 23.6.0 và 22.18.0, không còn in cảnh báo từ 24.3.0 và 22.18.0, và được đánh dấu ổn định trong Node.js 24.12.0 và 25.2.0. Các bản phát hành cũ hơn có tính năng này (từ 22.6 đến 22.17, và từ 23.0 đến 23.5) cần cờ: node --experimental-strip-types index.ts.

Đi kèm là bốn quy tắc:

• Không kiểm tra kiểu. Một tệp có const age: number = "forty" vẫn chạy và in ra forty.
• Chỉ cú pháp xóa được. Mọi thứ phải trở thành code JavaScript, thay vì biến mất, đều bị từ chối: enum, khối namespace có code chạy lúc runtime, parameter property trong hàm khởi tạo như constructor(private name: string), và alias import x = require(). Node dừng lại với SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode.
• tsconfig.json bị bỏ qua. Các tùy chọn như paths hay target không có tác dụng.
• Import cần tên tệp thật. Viết import { add } from "./math.ts", có cả phần mở rộng, và đánh dấu import chỉ dùng cho kiểu bằng type: import { add, type Pair } from "./math.ts". Không có type, Node sẽ tìm một export lúc runtime tên là Pair và thất bại với SyntaxError: The requested module './math.ts' does not provide an export named 'Pair'.

Hai tùy chọn trình biên dịch khiến tsc áp dụng cùng các quy tắc đó, để trình soạn thảo cảnh báo bạn trước cả Node: "erasableSyntaxOnly": true báo error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled. khi gặp enum, và "verbatimModuleSyntax": true bắt buộc dùng từ khóa type cho import chỉ dùng cho kiểu. Để vẫn viết phần mở rộng .ts trong import mà vẫn biên dịch được bằng tsc, thêm "rewriteRelativeImportExtensions": true, tùy chọn này đổi ./math.ts thành ./math.js trong đầu ra.

Node.js 24 còn có --experimental-transform-types, cờ này sinh code cho enum và parameter property thay vì từ chối chúng. Nó in ra một ExperimentalWarning, và Node.js 26 đã bỏ cờ này, nên đừng xây dựng dựa trên nó.

Khối code này dùng hai tính năng mà node index.ts từ chối. Nó chạy được ở đây vì trình soạn thảo biên dịch nó bằng trình biên dịch TypeScript, vốn sinh JavaScript cho cả hai:

enum Level {
    Low = 1,
    High = 3,
}

class Counter {
    constructor(private count: number) {} // a parameter property

    add(level: Level): number {
        this.count += level;
        return this.count;
    }
}

const c = new Counter(0);
console.log(c.add(Level.Low), c.add(Level.High)); // 1 4

Phiên bản xóa được của cùng đoạn code dùng một đối tượng const và một trường bình thường, Node chạy được nguyên trạng:

const Level = { Low: 1, High: 3 } as const;
type Level = (typeof Level)[keyof typeof Level]; // 1 | 3

class Counter {
    private count: number;

    constructor(count: number) {
        this.count = count;
    }

    add(level: Level): number {
        this.count += level;
        return this.count;
    }
}

const c = new Counter(0);
console.log(c.add(Level.Low), c.add(Level.High)); // 1 4

tsx

tsx chạy một tệp TypeScript chỉ trong một bước, không cần cấu hình và không giới hạn cú pháp:

npm install --save-dev tsx
npx tsx index.ts
npx tsx watch index.ts   # rerun on every change

Nó biến đổi code bằng esbuild, nên enum, namespace và parameter property đều chạy được, và import không có phần mở rộng được phân giải giống như trong một bundler. Giống type stripping của Node, nó không kiểm tra kiểu. Đây là lựa chọn phổ biến cho script, dev server và test trên các phiên bản Node.js ra đời trước type stripping, hoặc khi code dùng cú pháp mà Node từ chối.

ts-node

ts-node từng là cách tiêu chuẩn để chạy TypeScript trên Node.js trong nhiều năm, và vẫn là thứ mà nhiều bài hướng dẫn và dự án cũ dùng (npx ts-node index.ts, node -r ts-node/register). Mặc định nó kiểm tra kiểu, bằng API JavaScript của trình biên dịch TypeScript.

API đó chính là thứ TypeScript 7 không còn đi kèm: trình biên dịch của nó là một chương trình native, và package typescript 7 không cung cấp API trình biên dịch nào cho JavaScript. Khi đã cài TypeScript 7, ts-node crash trước khi chạy được bất cứ thứ gì:

TypeError: Cannot read properties of undefined (reading 'fileExists')
    at readConfig (/project/node_modules/ts-node/dist/configuration.js:91:33)

Bản phát hành mới nhất của ts-node, 10.9.2, có từ tháng 12 năm 2023. Với code mới, hãy dùng tsx hoặc node index.ts. Một thiết lập cũ phụ thuộc vào ts-node vẫn chạy được nếu dự án giữ TypeScript 6 (npm install --save-dev typescript@6) và có tsconfig.json, kể cả chỉ là {} rỗng. Nếu không có tệp này, ts-node quay về các giá trị mặc định có sẵn, trong đó có cách phân giải module node10 mà TypeScript 6 đã ngừng hỗ trợ, và npx ts-node index.ts thoát ra mà không chạy tệp cũng không in lỗi nào.

Deno và Bun

Cả hai runtime đều coi TypeScript là một loại tệp chính thức:

deno run index.ts    # runs without checking
deno check index.ts  # type-checks, reports errors, runs nothing

bun index.ts         # runs without checking

Cả hai đều không cần cài typescript hay có tsconfig.json, và đều hỗ trợ enum cùng các tính năng không xóa được khác. Deno đi kèm bản trình biên dịch TypeScript riêng cho deno check. Bun chỉ gỡ bỏ kiểu, nên trong một dự án Bun bạn vẫn cài typescript và chạy tsc --noEmit để tìm lỗi kiểu.

Chỉ tsc mới chặn chương trình có lỗi kiểu

Chỉ những cách chạy tsc trước mới từ chối chạy chương trình có lỗi kiểu. Trình soạn thảo trên trang này là một trong số đó, nên khối code này dừng lại ở trình biên dịch:

// This does not compile: the editor type-checks before it runs anything.
function area(width: number, height: number): number {
    return width * height;
}

console.log(area(3, "4"));

index.ts(6,21): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

Lưu thành tệp và chạy bằng node index.ts, npx tsx index.ts hoặc bun index.ts, cùng đoạn code đó vẫn chạy và in ra 12, vì 3 * "4" chuyển chuỗi thành số. Đó là lý do nên giữ tsc --noEmit trong quy trình ngay cả khi một công cụ nhanh hơn chạy code:

{
    "scripts": {
        "dev": "tsx watch src/index.ts",
        "typecheck": "tsc --noEmit"
    }
}

Bạn nên dùng cách nào?

• Đang học, hoặc thử nhanh: nút Chạy trên các trang này, hoặc playground.
• Một script hay công cụ nhỏ trên Node.js hiện tại: node index.ts, với erasableSyntaxOnly trong cấu hình để trình soạn thảo đánh dấu mọi thứ Node sẽ từ chối.
• Mọi dự án Node.js, mọi cú pháp: tsx để chạy, tsc --noEmit để kiểm tra.
• Một thư viện hay bất cứ thứ gì bạn phát hành: tsc, vì nó còn ghi ra các tệp .d.ts mà người dùng của bạn cần.
• Code front end: bundler hoặc framework của bạn (Vite, Next.js, Angular CLI) chạy TypeScript cho bạn; thêm tsc --noEmit để kiểm tra.