Belajar TypeScript - Build Output, Bundling, dan Source Maps

#Pendahuluan

Kode TypeScript harus diubah menjadi JavaScript agar bisa dijalankan. Episode 20 membahas apa yang terjadi pada proses itu: bagaimana tsc menerjemahkan kode, ke mana hasilnya diletakkan, dan bagaimana tetap bisa di-debug padahal sudah diubah bentuknya.

Build yang dikendalikan menghasilkan artefak yang dapat diprediksi. Target runtime menentukan sintaks JavaScript yang dihasilkan. Module dan bundler menentukan bentuk distribusinya. Source maps memastikan error di produksi tetap menunjuk ke kode TypeScript asli, bukan ke JavaScript hasil kompilasi.

Episode 20 membedah opsi-opsi build utama, peran source maps, deklarasi tipe untuk konsumen library, dan bagaimana bundler berperan di produksi.

#Opsi Output: target, module, dan outDir

Pengaturan dasar build dimulai di tsconfig:

Konfigurasi output

{
    "compilerOptions": {
        "target": "ES2022",
        "module": "NodeNext",
        "outDir": "dist",
        "rootDir": "src"
    }
}

Opsi target menentukan versi ECMAScript dari output, misalnya ES2022. Opsi module menentukan format modul JavaScript. outDir menempatkan hasil kompilasi, dan rootDir membatasi struktur input agar susunan folder di dist mencerminkan src. Menjalankan tsc lalu men-deploy isi dist adalah pola paling dasar dan paling mudah dipahami.

Opsi lib menentukan kumpulan API runtime yang dikenal compiler, misalnya ES2022 untuk fitur bahasa dan DOM untuk lingkungan browser. Memilih lib yang tepat mencegah pemakaian API yang tidak tersedia di target. target dan lib harus dipilih bersamaan agar output tidak memakai fitur di luar jangkauan runtime.

Info

Bila target runtime lebih lama dari fitur yang kalian pakai, tsc menurunkan sintaks, tapi API tambahan seperti Array.findLast tetap butuh lib yang sesuai. Untuk kasus ini pertimbangkan polyfill atau naikkan target bila memungkinkan.

#Source Maps

Source maps menghubungkan output ke kode asli:

Aktifkan source maps

{
    "compilerOptions": {
        "sourceMap": true,
        "sourceRoot": "../src"
    }
}

Dengan sourceMap: true, tsc menghasilkan file .map di samping tiap file output. Stack trace di produksi bisa dipetakan kembali ke file dan baris TypeScript asli, sehingga debugging tidak menebak-nebak di JavaScript yang sudah diubah. Opsi sourceRoot mengarahkan lokasi kode sumber di map.

Saat development, source maps membantu stack trace di editor dan runner seperti tsx. Saat produksi, map bisa di-upload ke layanan pelacak error seperti Sentry untuk menemukan baris asli setiap insiden. Memilih untuk menyimpan atau membuang map adalah keputusan antara kemudahan debugging dan kerahasiaan kode.

Info

Source maps bisa mengekspos struktur kode kalian. Untuk aplikasi internal, biarkan menyala. Untuk library komersial yang sangat tertutup, pertimbangkan menghapus map saat distribusi.

#Declaration dan Declaration Maps

Bila membangun library, output tipe sama pentingnya dengan output kode:

Deklarasi untuk library

{
    "compilerOptions": {
        "declaration": true,
        "declarationMap": true,
        "declarationDir": "dist/types"
    }
}

Opsi declaration: true menghasilkan file .d.ts untuk setiap modul. Konsumen library yang menulis TypeScript memakai deklarasi ini untuk mendapat tipe. declarationMap menghubungkan deklarasi ke kode sumber, sehingga editor bisa lompat ke definisi asli saat menekan go-to-definition.

#Bundler dan Alat Produksi

Untuk aplikasi frontend dan backend modern, bundler menggantikan tsc untuk output runtime:

Bundle library dengan tsup

bunx tsup src/index.ts --format esm --dts

Perintah bunx tsup memakai esbuild untuk menggabungkan kode dan menghasilkan deklarasi tipe sekaligus. Bundler menyelesaikan impor, membuang kode mati, dan menghasilkan output yang optimal. Framework seperti Vite dan Next.js memakai bundler serupa di balik layar.

Saat membangun aplikasi penuh, bundler juga menangani aset seperti CSS dan gambar, membagi kode menjadi beberapa chunk, dan menerapkan optimasi seperti minifikasi. Tsc tidak melakukan semua ini; tsc hanya menghasilkan file per modul. Karena itu, aplikasi modern hampir selalu memakai bundler sebagai tahap terakhir build.

Build tsc diikuti bundling

tsc --project tsconfig.build.json
bunx tsup src/index.ts --format esm --dts

Perbedaan pembagian kerja yang umum:

Tip

tsc dipakai untuk pemeriksaan tipe dan menghasilkan deklarasi .d.ts, sementara bundler bertanggung jawab atas JavaScript runtime yang dioptimalkan. Pembagian ini menjadi standar di banyak toolchain modern.

#Penutup

Episode 20 mengendalikan hasil akhir kompilasi: pengaturan target, module, dan outDir menentukan bentuk output; source maps menjaga debugging tetap terarah; deklarasi melayani konsumen library; dan bundler menyempurnakan artefak produksi.

Inti yang harus dibawa pulang:

target, module, outDir, dan rootDir mengatur bentuk output tsc.
Source maps memetakan stack trace kembali ke kode TypeScript.
declaration: true menghasilkan .d.ts untuk konsumen library.
declarationMap menghubungkan deklarasi ke kode sumber asli.
Bundler seperti tsup menggabungkan kode dan menulis deklarasi.
tsc untuk tipe dan deklarasi; bundler untuk JavaScript runtime.

Di episode 21 selanjutnya kita akan membahas performansi kompilasi dan incremental builds, yaitu mempercepat tsc di proyek yang terus membesar.