Cara Menjalankan File TypeScript: tsc, Node.js, tsx, ts-node

File TypeScript tidak bisa dijalankan apa adanya, karena browser dan engine JavaScript tidak memahami anotasi tipe. Harus ada yang menghapus tipenya lebih dulu. Yang melakukannya bisa compiler TypeScript (tsc), yang juga mengecek tipe, atau alat yang lebih cepat yang hanya menghapusnya. Cara tercepat untuk menjalankan kode di halaman ini adalah tombol Jalankan:

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}`);
}

Output:

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

Setiap blok yang bisa dijalankan di dokumentasi ini bekerja dengan cara yang sama: kodenya dicek tipenya oleh TypeScript 7 dengan strict aktif, dan hanya dijalankan kalau tidak ada error tipe. Untuk eksperimen yang lebih panjang, playground TypeScript adalah editor yang sama di halamannya sendiri. Sisa halaman ini membahas cara menjalankan file .ts di komputermu sendiri.

Sekilas Semua Pilihan

Kolom yang sering mengejutkan orang adalah kolom pertama: sebagian besar pilihan yang cepat menjalankan kode yang masih punya error tipe. Proyek pada umumnya menjalankan kode dengan salah satunya dan menjalankan tsc --noEmit secara terpisah, di editor dan di CI, untuk menangkap error-nya.

Compile dengan tsc, Lalu Jalankan dengan Node

Inilah pendekatan yang berfungsi di mana saja dan mengecek semuanya. Dengan TypeScript terpasang di proyek dan tsconfig.json yang mengatur "rootDir": "./src" dan "outDir": "./dist":

npx tsc
node dist/index.js

tsc mengecek tipe semua file, lalu menulis file .js ke dist. Untuk satu file tanpa proyek, berikan nama file-nya. Compiler lalu memakai opsi default dan menulis index.js di sebelah index.ts:

npx tsc index.ts
node index.js

(Kalau folder itu punya tsconfig.json, tsc menolak nama file dengan error TS5112; jalankan npx tsc saja, atau tambahkan --ignoreConfig.)

Secara default, tsc tetap menulis JavaScript walaupun ada error tipe, jadi node bisa menjalankan program yang gagal dicek. Tambahkan "noEmitOnError": true ke konfigurasi untuk mencegahnya, atau rangkai perintahnya dalam script supaya langkah kedua hanya berjalan kalau langkah pertama berhasil:

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

Untuk development, npx tsc --watch meng-compile ulang setiap kali kamu menyimpan.

Menjalankan TypeScript Langsung dengan Node.js

Node.js versi terbaru bisa menjalankan file .ts sendiri:

node index.ts

Node menghapus anotasi tipe, menggantinya dengan spasi supaya nomor baris di stack trace tetap cocok, lalu menjalankan sisanya. Fitur ini aktif secara default sejak Node.js 23.6.0 dan 22.18.0, tidak lagi menampilkan peringatan sejak 24.3.0 dan 22.18.0, dan ditandai stabil di Node.js 24.12.0 dan 25.2.0. Rilis sebelumnya yang sudah punya fitur ini (22.6 sampai 22.17, dan 23.0 sampai 23.5) butuh flag: node --experimental-strip-types index.ts.

Ada empat aturan yang menyertainya:

• Tidak ada pengecekan tipe. File berisi const age: number = "forty" tetap berjalan dan mencetak forty.
• Hanya sintaks yang bisa dihapus. Apa pun yang harus berubah menjadi kode JavaScript, bukan sekadar hilang, ditolak: enum, blok namespace berisi kode runtime, parameter property di constructor seperti constructor(private name: string), dan alias import x = require(). Node berhenti dengan SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode.
• tsconfig.json diabaikan. Opsi seperti paths atau target tidak berpengaruh.
• Import butuh nama file yang sebenarnya. Tulis import { add } from "./math.ts", lengkap dengan ekstensinya, dan tandai import yang hanya berisi tipe dengan type: import { add, type Pair } from "./math.ts". Tanpa type, Node mencari export runtime bernama Pair dan gagal dengan SyntaxError: The requested module './math.ts' does not provide an export named 'Pair'.

Dua opsi compiler membuat tsc menerapkan aturan yang sama, jadi editor memperingatkanmu sebelum Node melakukannya: "erasableSyntaxOnly": true melaporkan error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled. pada sebuah enum, dan "verbatimModuleSyntax": true mewajibkan kata kunci type pada import yang hanya berisi tipe. Supaya tetap bisa menulis ekstensi .ts di import dan tetap meng-compile dengan tsc, tambahkan "rewriteRelativeImportExtensions": true, yang mengubah ./math.ts menjadi ./math.js di output.

Node.js 24 juga punya --experimental-transform-types, yang membuat kode untuk enum dan parameter property alih-alih menolaknya. Opsi ini menampilkan ExperimentalWarning, dan Node.js 26 menghapus flag tersebut, jadi jangan mengandalkannya.

Blok ini memakai dua fitur yang ditolak oleh node index.ts. Blok ini berjalan di sini karena editornya meng-compile kode dengan compiler TypeScript, yang membuat JavaScript untuk keduanya:

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

Versi yang bisa dihapus dari kode yang sama memakai object const dan field biasa, yang bisa dijalankan Node apa adanya:

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 menjalankan file TypeScript dalam satu langkah, tanpa konfigurasi dan tanpa batasan sintaks:

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

tsx mentransformasi kode dengan esbuild, jadi enum, namespace, dan parameter property berfungsi, dan import tanpa ekstensi di-resolve seperti di bundler. Seperti type stripping milik Node, tsx tidak mengecek tipe. tsx adalah pilihan yang umum untuk script, dev server, dan test di versi Node.js yang belum punya type stripping, atau kalau kodenya memakai sintaks yang ditolak Node.

ts-node

Selama bertahun-tahun, ts-node adalah cara standar untuk menjalankan TypeScript di Node.js, dan masih dipakai banyak tutorial dan proyek lama (npx ts-node index.ts, node -r ts-node/register). Secara default ts-node mengecek tipe, memakai API JavaScript milik compiler TypeScript.

API itulah yang tidak disertakan TypeScript 7: compiler-nya adalah program native, dan paket typescript 7 tidak mengekspos API compiler ke JavaScript. Dengan TypeScript 7 terpasang, ts-node crash sebelum menjalankan apa pun:

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

Rilis terbaru ts-node, 10.9.2, berasal dari Desember 2023. Untuk kode baru, pakai tsx atau node index.ts. Setup lama yang bergantung pada ts-node tetap berfungsi kalau proyeknya tetap memakai TypeScript 6 (npm install --save-dev typescript@6) dan punya tsconfig.json, bahkan yang kosong, {}. Tanpa file itu, ts-node kembali ke default bawaan yang memuat module resolution node10 yang sudah deprecated di TypeScript 6, dan npx ts-node index.ts berhenti tanpa menjalankan file-nya atau menampilkan error.

Deno dan Bun

Kedua runtime ini memperlakukan TypeScript sebagai jenis file kelas satu:

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

bun index.ts         # runs without checking

Keduanya tidak butuh typescript terpasang atau tsconfig.json, dan keduanya mendukung enum serta fitur lain yang tidak bisa dihapus. Deno menyertakan salinan compiler TypeScript-nya sendiri untuk deno check. Bun hanya menghapus tipe, jadi di proyek Bun kamu tetap memasang typescript dan menjalankan tsc --noEmit untuk menemukan error tipe.

Error Tipe Hanya Menghentikan Program dengan tsc

Hanya cara yang menjalankan tsc lebih dulu yang menolak menjalankan program yang punya error tipe. Editor di halaman ini termasuk salah satunya, jadi blok ini berhenti di compiler:

// 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'.

Kalau disimpan sebagai file dan dijalankan dengan node index.ts, npx tsx index.ts atau bun index.ts, kode yang sama tetap berjalan dan mencetak 12, karena 3 * "4" mengonversi string-nya. Itulah alasan untuk tetap menyertakan tsc --noEmit dalam alur kerjamu, bahkan saat alat yang lebih cepat yang menjalankan kodenya:

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

Mana yang Sebaiknya Kamu Pakai?

• Belajar, atau tes cepat: tombol Jalankan di halaman ini, atau playground.
• Script atau alat kecil di Node.js versi terbaru: node index.ts, dengan erasableSyntaxOnly di konfigurasi supaya editor menandai apa pun yang akan ditolak Node.
• Proyek Node.js apa pun, sintaks apa pun: tsx untuk menjalankan, tsc --noEmit untuk mengecek.
• Library atau apa pun yang kamu publikasikan: tsc, karena ia juga menulis file .d.ts yang dibutuhkan penggunamu.
• Kode front end: bundler atau framework-mu (Vite, Next.js, Angular CLI) menjalankan TypeScript untukmu; tambahkan tsc --noEmit untuk pengecekannya.