Declaration Files (.d.ts)

Declaration Files (.d.ts)

Declaration files adalah file berekstensi .d.ts yang hanya berisi informasi tipe, tanpa implementasi sama sekali. Anggap saja mereka kartu identitas untuk kode JavaScript yang tidak punya tipe bawaan. TypeScript membaca kartu identitas ini untuk mengetahui fungsi apa saja yang tersedia di sebuah library, parameternya bertipe apa, dan nilai kembaliannya seperti apa, tanpa perlu melihat isi kode aslinya.

Kenapa file semacam ini ada? Karena sebagian besar ekosistem npm ditulis dalam JavaScript murni. Ketika kamu mengimpor library JavaScript ke proyek TypeScript, compiler buta total terhadap bentuk library tersebut. Tanpa declaration file, kamu kehilangan autocomplete, pengecekan tipe, dan dokumentasi inline, tiga alasan utama orang memakai TypeScript. Declaration files menjembatani celah ini sehingga kamu mendapat type safety penuh tanpa menunggu maintainer library menulis ulang kodenya.

Solusi termudah untuk library populer adalah DefinitelyTyped, repositori komunitas raksasa yang berisi declaration files untuk ribuan library JavaScript. Paket-paket ini dipublikasikan di npm dengan pola nama @types/nama-library. Contohnya, untuk memakai lodash cukup jalankan npm install -D @types/lodash. TypeScript otomatis memeriksa folder node_modules/@types setiap kali compile, jadi tidak ada konfigurasi tambahan yang diperlukan. Kalau library yang kamu pakai sudah menyertakan tipenya sendiri (biasanya ada field types di package.json-nya), kamu tidak perlu apa-apa lagi.

Error nyata: TS7016

Masalah muncul saat kamu mengimpor library JavaScript yang tidak punya declaration file bawaan dan tidak tersedia di DefinitelyTyped. Misalkan ada library internal bernama legacy-math:

import { tambah } from "legacy-math";

const hasil = tambah(2, 3);
console.log(hasil);

Compiler menolak kode ini dengan pesan error:

Pesan ini berarti TypeScript tidak menemukan informasi tipe untuk modul tersebut, dan dalam mode strict ia dilarang menebak tipenya sebagai any secara diam-diam. Error ini sangat umum saat mengadopsi TypeScript di proyek lama yang memakai banyak dependency JavaScript lawas.

Cara memperbaiki

Ada dua jalan keluar. Pertama, cek dulu apakah tipe komunitas tersedia lalu pasang dengan npm install -D @types/legacy-math. Kalau tidak ada, jalan kedua adalah menulis declaration file sendiri. Buat file bernama legacy-math.d.ts di proyekmu:

declare module "legacy-math" {
  export function tambah(a: number, b: number): number;
  export function kali(a: number, b: number): number;
  export const VERSI: string;
}

Setelah file ini ada, error TS7016 hilang dan kamu langsung mendapat autocomplete penuh untuk tambah, kali, dan VERSI. Perhatikan kata kunci declare: ia memberi tahu compiler bahwa blok ini hanya deskripsi tipe, bukan kode yang akan dijalankan, sehingga tidak menghasilkan output JavaScript apa pun.

Catatan teknis: file .d.ts tidak pernah di-compile menjadi JavaScript. Kalau kamu tidak sengaja menulis logika di dalamnya, logika itu hilang saat build, jadi simpan hanya deklarasi tipe di sana.

Pola yang umum dipakai tim adalah mengetik ulang API library secara bertahap. Mulai dari fungsi yang benar-benar kamu pakai, biarkan sisanya menyusul belakangan. Dengan begitu migrasi ke TypeScript tidak terhambat hanya karena satu dependency JavaScript yang belum punya tipe.