Instalasi TypeScript #

TypeScript bukan bahasa yang berdiri sendiri — ia adalah superset JavaScript yang harus dikompilasi terlebih dahulu sebelum bisa dijalankan di runtime manapun. Ini berarti kamu memerlukan toolchain yang tepat sejak awal: Node.js sebagai runtime, npm sebagai package manager, dan compiler TypeScript (tsc) sebagai jembatan antara kode .ts yang kamu tulis dengan JavaScript yang dieksekusi mesin. Proses setup ini terkesan sederhana, tapi banyak developer melewatkan detail penting — terutama soal perbedaan instalasi global vs lokal, dan bagaimana tsconfig.json mengontrol seluruh perilaku compiler. Artikel ini memandu kamu dari nol hingga punya lingkungan TypeScript yang siap dipakai untuk proyek nyata.

Prasyarat: Node.js dan npm #

TypeScript diinstal melalui npm, sehingga Node.js adalah fondasi dari seluruh toolchain ini. Sebelum melangkah lebih jauh, pastikan kamu memahami apa yang sebenarnya kamu instal — npm sudah bundled bersama Node.js, jadi kamu tidak perlu menginstalnya secara terpisah.

Kunjungi nodejs.org dan unduh versi LTS (Long Term Support). Versi LTS mendapat pembaruan keamanan jangka panjang dan jauh lebih stabil untuk pengembangan sehari-hari dibanding versi Current yang berisi fitur eksperimental. Pada saat artikel ini ditulis, Node.js LTS berada di versi 20.x.

Setelah instalasi selesai, verifikasi bahwa keduanya terpasang dengan benar:

node -v
# v20.x.x

npm -v
# 10.x.x

Jika salah satu perintah menghasilkan error command not found, berarti proses instalasi belum selesai dengan benar. Di Linux/macOS, pastikan direktori instalasi Node.js sudah masuk ke variabel PATH. Di Windows, coba tutup dan buka kembali terminal setelah instalasi.

Jangan gunakan Node.js yang diinstal dari package manager sistem (seperti apt di Ubuntu atau brew di macOS) untuk development — versinya sering tertinggal jauh. Gunakan nvm (Node Version Manager) agar bisa berpindah antar versi Node.js dengan mudah, terutama jika kamu mengelola banyak proyek dengan kebutuhan Node.js yang berbeda.

Opsional: Gunakan nvm untuk Manajemen Versi #

Jika kamu mengerjakan lebih dari satu proyek TypeScript, sangat disarankan menggunakan nvm sejak awal:

# Install nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Install Node.js LTS terbaru
nvm install --lts

# Set sebagai default
nvm alias default node

# Verifikasi
node -v

Dengan nvm, berpindah versi Node.js antar proyek semudah menjalankan nvm use 18 atau nvm use 20.

Instalasi TypeScript: Global vs Lokal #

Ini adalah keputusan pertama yang harus kamu buat, dan sering disalahpahami. Ada dua cara menginstal TypeScript: secara global (tersedia di seluruh sistem) atau secara lokal (hanya tersedia di dalam proyek tertentu). Keduanya punya kasus penggunaan yang berbeda.

Instalasi Global #

Instalasi global menempatkan binary tsc di PATH sistem sehingga bisa dijalankan dari direktori manapun:

npm install -g typescript

Verifikasi instalasi:

tsc --version
# Version 5.x.x

Kapan menggunakan instalasi global? Untuk eksperimen cepat, script satu-off, atau saat kamu baru belajar TypeScript dan belum punya proyek yang terdefinisi. Ini juga berguna di mesin development personal kamu.

Instalasi Lokal (Per Proyek) #

Instalasi lokal hanya tersedia di dalam proyek tempat TypeScript diinstal. Ini adalah pendekatan yang direkomendasikan untuk proyek tim dan produksi:

# Inisialisasi proyek baru terlebih dahulu
mkdir proyek-typescript && cd proyek-typescript
npm init -y

# Install TypeScript sebagai dev dependency
npm install --save-dev typescript

Atau menggunakan Yarn:

yarn add --dev typescript

Setelah instalasi lokal, tsc tidak langsung tersedia di terminal — kamu perlu memanggilnya melalui npx atau melalui npm scripts:

# Panggil tsc dari instalasi lokal
npx tsc --version

# Atau definisikan di package.json scripts

Anti-pattern umum: Mengandalkan instalasi TypeScript global untuk proyek tim. Ini menyebabkan masalah serius ketika anggota tim memiliki versi TypeScript yang berbeda — kode yang berhasil dikompilasi di mesin satu bisa gagal di mesin lain karena perbedaan behavior antar versi. Selalu instal TypeScript sebagai devDependency di package.json.

Perbandingan Global vs Lokal #

Struktur Proyek TypeScript #

Sebelum masuk ke konfigurasi, penting untuk memahami struktur direktori yang lazim digunakan di proyek TypeScript. Ini bukan aturan baku, tapi konvensi yang diterima luas:

proyek-typescript/
  ├── src/              # Source TypeScript (.ts)
  │   ├── index.ts
  │   └── utils/
  │       └── helper.ts
  ├── dist/             # Output JavaScript hasil kompilasi (.js)
  ├── node_modules/     # Dependencies
  ├── package.json
  ├── package-lock.json
  └── tsconfig.json     # Konfigurasi TypeScript compiler

Pemisahan src/ dan dist/ adalah praktik terbaik: source TypeScript tidak bercampur dengan output JavaScript. Direktori dist/ biasanya masuk ke .gitignore karena bisa selalu di-generate ulang dari source.

Konfigurasi TypeScript: tsconfig.json #

File tsconfig.json adalah pusat kontrol TypeScript compiler. Tanpa file ini, tsc menggunakan pengaturan default yang sering tidak optimal untuk proyek nyata. Generate file konfigurasi awal dengan:

npx tsc --init

Perintah ini menghasilkan tsconfig.json dengan ratusan opsi yang hampir semuanya dikomentari. Berikut adalah konfigurasi yang lebih bersih dan cocok untuk proyek TypeScript modern:

{
  "compilerOptions": {
    // Target runtime dan output
    "target": "ES2022",
    "module": "CommonJS",
    "lib": ["ES2022"],

    // Direktori input dan output
    "rootDir": "./src",
    "outDir": "./dist",

    // Keamanan tipe
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,

    // Kualitas kode
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,

    // Interoperabilitas
    "esModuleInterop": true,
    "resolveJsonModule": true,

    // Source maps untuk debugging
    "sourceMap": true,

    // Tidak emit jika ada error
    "noEmitOnError": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Opsi Konfigurasi yang Paling Penting #

target menentukan versi JavaScript output. ES2022 adalah pilihan yang aman untuk Node.js 18+ dan browser modern. Jika kamu menarget browser lama, gunakan ES5 atau ES2015.

strict: true mengaktifkan semua pemeriksaan tipe yang ketat sekaligus. Ini adalah opsi terpenting — jangan nonaktifkan hanya karena membuatmu harus menulis lebih banyak kode. Disiplin tipe di awal menghemat debugging berjam-jam di kemudian hari.

noEmitOnError: true memastikan TypeScript tidak menghasilkan file JavaScript jika ada error kompilasi. Tanpa opsi ini, kamu bisa tidak sengaja men-deploy kode yang sebenarnya mengandung error tipe.

sourceMap: true menghasilkan file .map yang menghubungkan kode JavaScript output dengan baris TypeScript asalnya. Ini sangat penting untuk debugging — stack trace akan menunjuk ke baris TypeScript, bukan baris JavaScript yang dihasilkan.

Aktifkan strict: true sejak hari pertama proyek. Mengaktifkannya di proyek yang sudah berjalan jauh lebih menyakitkan karena kamu harus memperbaiki ratusan atau ribuan type error sekaligus. Memulai dengan strict dari awal adalah investasi kecil yang menghasilkan manfaat besar.

Menulis dan Mengompilasi Kode TypeScript #

Dengan tsconfig.json yang sudah terkonfigurasi, saatnya menulis kode TypeScript pertama. Buat file src/index.ts:

// src/index.ts

// TypeScript menambahkan anotasi tipe eksplisit
const pesan: string = "Halo, TypeScript!";
const angka: number = 42;
const aktif: boolean = true;

// Interface mendefinisikan bentuk object
interface Pengguna {
  id: number;
  nama: string;
  email: string;
}

// Fungsi dengan parameter bertipe dan return type eksplisit
function buatPengguna(id: number, nama: string, email: string): Pengguna {
  return { id, nama, email };
}

// TypeScript akan error jika tipe tidak cocok
// ANTI-PATTERN: buatPengguna("satu", 123, true) — TypeScript akan menolak ini

const pengguna = buatPengguna(1, "Budi Santoso", "[email protected]");
console.log(`Pesan: ${pesan}`);
console.log(`Pengguna:`, pengguna);

Kompilasi file ini:

npx tsc

Jika tidak ada error, kamu akan menemukan dist/index.js dan dist/index.map sebagai hasil kompilasi. Jalankan output JavaScript:

node dist/index.js
# Pesan: Halo, TypeScript!
# Pengguna: { id: 1, nama: 'Budi Santoso', email: '[email protected]' }

Mode Watch: Kompilasi Otomatis #

Saat development aktif, menjalankan tsc manual setiap kali ada perubahan sangat tidak efisien. Gunakan flag --watch untuk kompilasi otomatis:

npx tsc --watch

Sekarang setiap kali kamu menyimpan file .ts, compiler otomatis mendeteksi perubahan dan mengkompilasi ulang. Kamu akan melihat output seperti ini di terminal:

[3:45:21 PM] Starting compilation in watch mode...
[3:45:22 PM] Found 0 errors. Watching for file changes.

Menangani Error Kompilasi #

Salah satu nilai utama TypeScript adalah mendeteksi error sebelum runtime. Coba buat error yang disengaja:

// src/index.ts — tambahkan baris ini

// ANTI-PATTERN: Menetapkan nilai string ke variabel number
const nilai: number = "bukan angka";
//    ^^^^^ Error: Type 'string' is not assignable to type 'number'

// BENAR: Tipe harus konsisten
const nilaiBenar: number = 42;

TypeScript akan langsung melaporkan:

src/index.ts:XX:7 - error TS2322: Type 'string' is not assignable to type 'number'.
Found 1 error.

Karena noEmitOnError: true aktif, tidak ada file JavaScript yang dihasilkan selama masih ada error. Ini memaksa kamu menyelesaikan masalah tipe sebelum bisa men-deploy.

Alur Kompilasi TypeScript #

Penting untuk memahami apa yang terjadi di balik layar saat kamu menjalankan tsc:

flowchart TD
    A[File .ts] --> B[TypeScript Compiler - tsc]
    B --> C{Type Checking}
    C -- Ada Error --> D[Laporan Error]
    C -- Bersih --> E[JavaScript Generator]
    D --> F[Tidak Ada Output - noEmitOnError]
    E --> G[File .js]
    E --> H[File .map - sourceMap]
    G --> I[Node.js / Browser]
    H --> J[Debugger]

    style D fill:#ff6b6b,color:#fff
    style F fill:#ff6b6b,color:#fff
    style G fill:#51cf66,color:#fff
    style H fill:#339af0,color:#fff

TypeScript compiler melakukan dua hal sekaligus: type checking (memverifikasi kebenaran tipe) dan transpilation (mengubah TypeScript menjadi JavaScript). Keduanya terjadi dalam satu langkah tsc, tapi secara konseptual terpisah — ini mengapa kamu bisa menggunakan Babel untuk transpilasi saja tanpa type checking jika diperlukan.

ts-node: Jalankan TypeScript Tanpa Build Step #

Untuk development dan scripting, ada tool yang jauh lebih praktis dari siklus tsc → node: ts-node. Tool ini mengeksekusi TypeScript secara langsung tanpa perlu menghasilkan file JavaScript terlebih dahulu.

# Install ts-node sebagai dev dependency
npm install --save-dev ts-node

# Jalankan file TypeScript langsung
npx ts-node src/index.ts

ts-node sangat berguna untuk:

• Menjalankan script satu-off
• REPL TypeScript interaktif (npx ts-node tanpa argumen)
• Menjalankan test runner
• Debugging cepat tanpa perlu build

Jangan gunakan ts-node di produksi. ts-node melakukan kompilasi on-the-fly yang lebih lambat dan mengonsumsi lebih banyak memori dibanding menjalankan JavaScript yang sudah dikompilasi. Gunakan tsc untuk build produksi, dan jalankan output JavaScript dari dist/.

Konfigurasi npm Scripts #

Tambahkan scripts yang berguna ke package.json agar workflow development lebih nyaman:

{
  "name": "proyek-typescript",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "build:watch": "tsc --watch",
    "start": "node dist/index.js",
    "dev": "ts-node src/index.ts",
    "clean": "rm -rf dist"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "ts-node": "^10.9.0"
  }
}

Sekarang workflow development kamu menjadi:

npm run dev        # Jalankan langsung tanpa build (development)
npm run build      # Kompilasi ke dist/ (persiapan produksi)
npm start          # Jalankan hasil kompilasi (produksi)
npm run build:watch  # Watch mode untuk development aktif

Verifikasi Setup Lengkap #

Sebelum mulai menulis kode serius, verifikasi bahwa semua komponen terpasang dengan benar menggunakan checklist ini:

VERIFIKASI INSTALASI:
  □ node -v         → menampilkan versi (v18.x atau v20.x)
  □ npm -v          → menampilkan versi (v9.x atau v10.x)
  □ npx tsc --version → menampilkan Version 5.x.x
  □ tsconfig.json ada di root proyek
  □ "strict": true aktif di tsconfig.json

VERIFIKASI WORKFLOW:
  □ npm run dev berhasil menjalankan src/index.ts
  □ npm run build menghasilkan file di dist/
  □ npm start berhasil menjalankan dist/index.js
  □ Sengaja buat type error → compiler melaporkan error
  □ Perbaiki error → compiler berhasil mengompilasi

Kapan Tidak Menggunakan tsc Langsung #

Untuk proyek berskala besar, tsc sering diintegrasikan ke dalam build tool yang lebih kompleks. Berikut panduan singkat:

Tetap gunakan tsc langsung jika:
  ✓ Proyek Node.js backend sederhana hingga menengah
  ✓ Library TypeScript yang akan dipublikasikan ke npm
  ✓ Script dan tooling internal

Pertimbangkan bundler (Webpack, Vite, esbuild) jika:
  ✗ Kamu membangun aplikasi frontend (React, Vue, dll.)
  ✗ Proyek membutuhkan code splitting dan lazy loading
  ✗ Perlu optimasi bundle size untuk browser
  ✗ Integrasi dengan CSS module, asset handling, dll.

Framework seperti Next.js, Nuxt, atau NestJS sudah menangani konfigurasi TypeScript secara internal — kamu tidak perlu mengkonfigurasi tsc secara manual jika menggunakan framework-framework tersebut.

Ringkasan #

• Node.js LTS adalah fondasi — instal melalui nodejs.org atau gunakan nvm untuk manajemen versi yang lebih fleksibel.
• Instal TypeScript sebagai devDependency — jangan andalkan instalasi global untuk proyek tim karena versi TypeScript antar mesin bisa berbeda dan menyebabkan inkonsistensi.
• tsconfig.json bukan opsional — file ini mengontrol seluruh perilaku compiler; aktifkan strict: true sejak hari pertama untuk mendapat manfaat penuh dari sistem tipe TypeScript.
• noEmitOnError: true — opsi penting yang memastikan tidak ada JavaScript yang dihasilkan selama masih ada error tipe, mencegah deploy kode bermasalah secara tidak sengaja.
• Pisahkan src/ dan dist/ — source TypeScript tidak boleh bercampur dengan output JavaScript; masukkan dist/ ke .gitignore.
• ts-node untuk development, tsc untuk produksi — gunakan ts-node untuk eksekusi langsung saat development, tapi selalu kompilasi ke JavaScript untuk deployment produksi.
• Source maps wajib aktif — dengan sourceMap: true, debugger akan menunjuk ke baris TypeScript asli, bukan JavaScript yang dihasilkan compiler.
• npm scripts menyederhanakan workflow — definisikan build, dev, start di package.json agar seluruh tim menggunakan perintah yang sama.