KAL
Menu

ES Modules dalam TypeScript

Sintaks import dan export, import khusus tipe, dan opsi verbatimModuleSyntax.

Daftar isi

Sistem modul menjadi dasar penyusunan program TypeScript yang terdiri atas lebih dari satu berkas. Topik ini membahas sintaks export dan import untuk bertukar nilai antarberkas, impor khusus tipe melalui import type, serta opsi verbatimModuleSyntax yang menegakkan aturan impor pada hasil kompilasi. Pembahasan menggunakan dua kelompok contoh, yaitu sepasang berkas statistik nilai dan sebuah proyek kecil yang memiliki tsconfig.json sendiri. Setelah membaca topik ini, program dapat dipecah menjadi modul dengan aturan yang diperiksa compiler secara menyeluruh.

Ekspor dan impor antarberkas#

Setiap berkas TypeScript menjadi sebuah modul (module) begitu di dalamnya terdapat export atau import, dan nilai yang diekspor membentuk kontrak yang dapat dipakai berkas lain. Berkas statistik.ts di bawah ini mengekspor satu fungsi dan satu konstanta, sedangkan laporan.ts mengambil keduanya melalui daftar nama di dalam kurung kurawal. Bentuk ini disebut named import, yaitu impor yang menyebut nama setiap nilai secara eksplisit. Sintaks export default juga sah untuk menandai satu nilai utama per berkas, tetapi seluruh contoh pada topik ini memakai ekspor bernama agar kontraknya terbaca jelas. Specifier, yaitu teks jalur yang ditulis setelah from pada pernyataan impor, ditulis lengkap dengan ekstensi seperti ./statistik.ts karena contoh pada topik ini dijalankan langsung dengan node.

ts statistik.ts 
export function rataRata(nilai: number[]): number {
  const total = nilai.reduce((a, b) => a + b, 0);
  return total / nilai.length;
}

export const LABEL = "rekap nilai";
ts laporan.ts 
// tidak-dijalankan
import { LABEL, rataRata } from "./statistik.ts";

const nilaiUjian = [80, 90, 100];
console.log(LABEL, rataRata(nilaiUjian));
bash 
# menjalankan laporan langsung dari berkas TypeScript-nya
node --no-warnings laporan.ts
text Keluaran 
rekap nilai 90

Kontrak tersebut diperiksa compiler secara statis sebelum program dijalankan. Daftar { LABEL, rataRata } harus cocok dengan nilai yang diekspor oleh statistik.ts, dan tipe argumen rataRata harus berupa number[]. Pemanggilan rataRata(nilaiUjian) mengembalikan 90 karena total 270 dibagi tiga, sehingga keluarannya membuktikan bahwa nilai yang dipakai benar-benar berasal dari modul lain.

Menangkap impor yang keliru#

Kesalahan impor yang paling umum adalah menyebut nama yang tidak diekspor oleh modul yang diimpornya. Berkas laporan-salah.ts di bawah ini mengimpor median, padahal statistik.ts tidak pernah mengekspor nama tersebut. Kesalahan ini sengaja dipertahankan agar laporan compiler atas berkas itu dapat diperlihatkan.

ts laporan-salah.ts 
// tidak-dijalankan
import { median, rataRata } from "./statistik.ts";

console.log(median([80, 90, 100]), rataRata([80, 90, 100]));
bash 
# memeriksa berkas dengan impor yang keliru, tanpa tsconfig
tsc --noEmit --pretty false laporan-salah.ts
text Keluaran 
laporan-salah.ts(2,10): error TS2305: Module '"./statistik.ts"' has no exported member 'median'.
laporan-salah.ts(2,34): error TS5097: An import path can only end with a '.ts' extension when 'allowImportingTsExtensions' is enabled.

Pesan pertama berasal dari kontrak ekspor, yaitu median tidak ada di antara nilai yang diekspor oleh statistik.ts, sehingga pemanggilan median sesudahnya tidak ikut diperiksa. Pesan kedua muncul karena perintah ini dijalankan tanpa tsconfig.json, sehingga opsi allowImportingTsExtensions belum menyala dan specifier berakhiran .ts ditolak. Opsi tersebut dinyalakan pada proyek di bagian berikutnya, sehingga gaya penulisan specifier yang sama berhenti menimbulkan pesan.

Impor khusus tipe dengan import type#

Tidak semua nilai yang diekspor sebuah modul tersedia saat program berjalan. Interface dan alias tipe hanya ada saat pemeriksaan tipe, karena compiler membuangnya dari hasil kompilasi. Mengimpor interface atau alias tipe dengan import biasa membuat pernyataan impor tetap tertulis pada kode hasil build, padahal nama yang diimpornya tidak pernah ada di sana. Sintaks import type menandai impor yang isinya murni tipe, sehingga compiler tahu bahwa pernyataan tersebut boleh dibuang seluruhnya.

Proyek proyek/ memperlihatkan pola ini pada skala kecil. Konfigurasinya menyalakan strict, mode resolusi modul bundler, opsi allowImportingTsExtensions, dan opsi verbatimModuleSyntax. Berkas bentuk.ts mengekspor interface Bentuk beserta fungsi deskripsi, sedangkan aplikasi.ts mengambil keduanya melalui dua pernyataan impor dengan peruntukan berbeda.

json proyek/tsconfig.json 
{
  "compilerOptions": {
    "strict": true,
    "noEmit": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true
  }
}
ts proyek/bentuk.ts 
export interface Bentuk {
  nama: string;
}

export function deskripsi(b: Bentuk): string {
  return `Bentuk ${b.nama}`;
}
ts proyek/aplikasi.ts 
// tidak-dijalankan
import { deskripsi } from "./bentuk.ts";
import type { Bentuk } from "./bentuk.ts";

const b: Bentuk = { nama: "persegi" };
console.log(deskripsi(b));
bash 
# menjalankan aplikasi dari dalam folder proyeknya
( cd proyek && node --no-warnings aplikasi.ts )
text Keluaran 
Bentuk persegi

Pernyataan import type mengambil Bentuk untuk keperluan anotasi saja dan lenyap dari kode yang berjalan, sedangkan deskripsi tetap diimpor sebagai nilai karena dipanggil saat program berjalan. Pemisahan ini membuat maksud setiap pernyataan impor dapat dibaca tanpa membuka berkas sumbernya. Compiler memakai informasi yang sama untuk membuang dari berkas hasil build setiap pernyataan yang tidak memiliki bentuk saat program berjalan.

Pernyataan impor apa adanya dengan verbatimModuleSyntax#

Opsi verbatimModuleSyntax memerintahkan compiler mempertahankan pernyataan import dan export persis seperti yang ditulis pada hasil kompilasi, tanpa menghapus atau menulis ulang bentuknya secara otomatis. Konsekuensinya, setiap impor yang isinya hanya tipe wajib ditulis dengan import type atau modifier type, karena compiler tidak lagi menebak mana yang perlu dibuang. Berkas aplikasi-salah.ts melanggar aturan ini dengan mengimpor interface Bentuk sebagai nilai biasa.

ts proyek/aplikasi-salah.ts 
// tidak-dijalankan
import { Bentuk } from "./bentuk.ts";

const b: Bentuk = { nama: "persegi" };
console.log(b.nama);
bash 
# memeriksa seluruh isi proyek dengan verbatimModuleSyntax
tsc --project proyek --pretty false
text Keluaran 
proyek/aplikasi-salah.ts(2,10): error TS1484: 'Bentuk' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled.

Satu-satunya pesan menunjuk aplikasi-salah.ts, sedangkan aplikasi.ts yang memakai import type lolos tanpa keluhan. Pesan TS1484 muncul pada waktu kompilasi, jauh sebelum program sempat berjalan dan gagal mengimpor nama yang tidak ada pada kode hasil build. Aturan ini menjadikan pernyataan impor sebagai sumber kebenaran tunggal, sehingga alat bundler cukup membacanya apa adanya tanpa analisis tambahan.

Kesalahan umum#

Kesalahan berikut sering muncul saat menulis impor pada proyek TypeScript.

  • Menyebut nama ekspor yang tidak ada lalu mencurigai sistem resolusi berkas. Pesan TS2305 berarti kontrak ekspor modul yang diimpor tidak cocok, sehingga periksa dahulu daftar export pada berkas yang diimpor.
  • Mengimpor interface atau alias tipe tanpa import type lalu mengandalkan compiler untuk membersihkannya. Kebiasaan ini lolos pada konfigurasi longgar, tetapi merusak hasil build saat verbatimModuleSyntax menyala atau saat alat bundler membaca pernyataan impor apa adanya.
  • Memperlakukan pesan TS5097 sebagai larangan mutlak terhadap ekstensi .ts. Pesan itu hanya menyatakan bahwa allowImportingTsExtensions belum menyala pada konfigurasi yang sedang dipakai.
  • Mencampur ekspor bernama dan export default untuk nilai yang sama. Kode yang mengimpor modul menjadi bingung memilih gaya impor, sedangkan pemeriksaan nama otomatis pada editor bekerja paling baik dengan ekspor bernama.

Ringkasan#

  • export dan import membentuk kontrak antarberkas yang diperiksa compiler, dan impor yang menyebut nama yang tidak diekspor ditolak dengan pesan TS2305.
  • import type menandai impor yang isinya murni tipe, sehingga pernyataannya dibuang dari hasil build dan tidak muncul saat program berjalan.
  • Opsi verbatimModuleSyntax mempertahankan pernyataan impor apa adanya dan menegakkan penulisan import type melalui pesan TS1484.
  • Specifier berakhiran .ts memerlukan opsi allowImportingTsExtensions yang menyala bersama noEmit, dan seluruh contoh pada topik ini dijalankan dengan node.

Referensi#