Konfigurasi TypeScript: Panduan Komprehensif tsconfig.json

TypeScript, superset dari JavaScript, membawa pengetikan statis ke dunia pengembangan web yang dinamis. File tsconfig.json yang dikonfigurasi dengan baik sangat penting untuk memanfaatkan kekuatan penuh TypeScript. Panduan ini memberikan gambaran komprehensif tentang tsconfig.json, mencakup opsi kompiler esensial, penyiapan proyek, dan konfigurasi tingkat lanjut.

Apa itu tsconfig.json?

File tsconfig.json adalah file konfigurasi yang menentukan opsi kompiler untuk sebuah proyek TypeScript. File ini memberitahu kompiler TypeScript cara mentranspilasi kode TypeScript menjadi JavaScript. File ini esensial untuk mendefinisikan struktur proyek, menetapkan aturan kompilasi, dan memastikan konsistensi di seluruh tim pengembangan, baik tim tersebut berada di satu kantor atau tersebar di berbagai benua.

Membuat File tsconfig.json

Untuk membuat file tsconfig.json, navigasikan ke direktori root proyek Anda di terminal dan jalankan perintah berikut:

            tsc --init
            

              
                Copy
              
            
          

Perintah ini menghasilkan file tsconfig.json dasar dengan opsi kompiler yang umum digunakan. Anda kemudian dapat menyesuaikan file tersebut agar sesuai dengan kebutuhan spesifik proyek Anda. tsconfig.json yang umum akan mencakup opsi seperti compilerOptions, include, dan exclude.

Opsi Kompiler Esensial

Bagian compilerOptions adalah inti dari file tsconfig.json. Bagian ini berisi berbagai macam opsi yang mengontrol perilaku kompiler TypeScript. Berikut adalah beberapa opsi kompiler yang paling penting:

target

Opsi target menentukan versi target ECMAScript untuk kode JavaScript yang dihasilkan. Nilai umum termasuk ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Memilih target yang tepat sangat penting untuk memastikan kompatibilitas dengan lingkungan runtime yang dituju, seperti peramban atau versi Node.js.

Contoh:

            {
  "compilerOptions": {
    "target": "ES2020"
  }
}
            

              
                Copy
              
            
          

module

Opsi module menentukan gaya pembuatan kode modul. Nilai umum termasuk CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020, dan ESNext. Pilihan sistem modul bergantung pada lingkungan target dan bundler modul yang digunakan (misalnya, Webpack, Rollup, Parcel). Untuk Node.js, CommonJS sering digunakan, sedangkan untuk aplikasi web modern, ES6 atau ESNext dengan bundler modul lebih disukai. Menggunakan ESNext memungkinkan pengembang memanfaatkan fitur dan optimisasi terbaru, sambil mengandalkan bundler untuk menangani format modul akhir.

Contoh:

            {
  "compilerOptions": {
    "module": "ESNext"
  }
}
            

              
                Copy
              
            
          

lib

Opsi lib menentukan daftar file pustaka yang akan disertakan dalam kompilasi. File-file pustaka ini menyediakan definisi tipe untuk API JavaScript bawaan dan API peramban. Nilai umum termasuk ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String, dan banyak lagi. Memilih pustaka yang sesuai memastikan bahwa kompiler TypeScript memiliki informasi tipe yang diperlukan untuk lingkungan target. Menggunakan pustaka DOM memungkinkan proyek untuk mengompilasi kode yang menggunakan API spesifik peramban tanpa kesalahan tipe.

Contoh:

            {
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}
            

              
                Copy
              
            
          

allowJs

Opsi allowJs memungkinkan kompiler TypeScript untuk mengompilasi file JavaScript bersama dengan file TypeScript. Ini berguna untuk memigrasikan proyek JavaScript yang ada ke TypeScript secara bertahap. Mengaturnya ke true memungkinkan kompiler untuk memproses file .js, memungkinkan adopsi bertahap TypeScript dalam sebuah proyek.

Contoh:

            {
  "compilerOptions": {
    "allowJs": true
  }
}
            

              
                Copy
              
            
          

jsx

Opsi jsx menentukan bagaimana sintaks JSX harus ditangani. Nilai umum termasuk preserve, react, react-native, dan react-jsx. preserve menjaga sintaks JSX dalam output, sementara react mengubah JSX menjadi panggilan React.createElement. react-jsx menggunakan transformasi JSX baru yang diperkenalkan di React 17, yang tidak memerlukan impor React. Memilih opsi JSX yang benar sangat penting untuk proyek yang menggunakan React atau pustaka berbasis JSX lainnya.

Contoh:

            {
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}
            

              
                Copy
              
            
          

declaration

Opsi declaration menghasilkan file deklarasi .d.ts yang sesuai untuk setiap file TypeScript. File deklarasi berisi informasi tipe dan digunakan oleh proyek TypeScript lain untuk mengonsumsi kode yang dikompilasi. Menghasilkan file deklarasi sangat penting untuk membuat pustaka dan modul yang dapat digunakan kembali. File-file ini memungkinkan proyek TypeScript lain untuk memahami tipe dan antarmuka yang diekspos oleh pustaka tanpa perlu mengompilasi kode sumber asli.

Contoh:

            {
  "compilerOptions": {
    "declaration": true
  }
}
            

              
                Copy
              
            
          

sourceMap

Opsi sourceMap menghasilkan file peta sumber, yang memetakan kode JavaScript yang dihasilkan kembali ke kode TypeScript asli. Peta sumber sangat penting untuk men-debug kode TypeScript di peramban dan lingkungan lainnya. Ketika terjadi kesalahan dalam kode JavaScript, peta sumber memungkinkan pengembang untuk melihat kode TypeScript yang sesuai di debugger, membuatnya lebih mudah untuk mengidentifikasi dan memperbaiki masalah.

Contoh:

            {
  "compilerOptions": {
    "sourceMap": true
  }
}
            

              
                Copy
              
            
          

outDir

Opsi outDir menentukan direktori output untuk file JavaScript yang dihasilkan. Opsi ini membantu mengatur output build proyek dengan memisahkan kode sumber dari kode yang dikompilasi. Menggunakan outDir membuatnya lebih mudah untuk mengelola proses build dan menerapkan aplikasi.

Contoh:

            {
  "compilerOptions": {
    "outDir": "dist"
  }
}
            

              
                Copy
              
            
          

rootDir

Opsi rootDir menentukan direktori root dari proyek TypeScript. Kompiler menggunakan direktori ini sebagai dasar untuk menyelesaikan nama modul. Opsi ini sangat penting untuk proyek dengan struktur direktori yang kompleks. Mengatur rootDir dengan benar memastikan bahwa kompiler dapat menemukan semua modul dan dependensi yang diperlukan.

Contoh:

            {
  "compilerOptions": {
    "rootDir": "src"
  }
}
            

              
                Copy
              
            
          

strict

Opsi strict mengaktifkan semua opsi pemeriksaan tipe yang ketat. Ini sangat disarankan untuk proyek TypeScript baru karena membantu menangkap potensi kesalahan di awal proses pengembangan. Mengaktifkan mode ketat memberlakukan aturan pemeriksaan tipe yang lebih ketat, menghasilkan kode yang lebih kuat dan mudah dipelihara. Merupakan praktik terbaik untuk mengaktifkan mode ketat di semua proyek TypeScript baru.

Contoh:

            {
  "compilerOptions": {
    "strict": true
  }
}
            

              
                Copy
              
            
          

esModuleInterop

Opsi esModuleInterop memungkinkan interoperabilitas antara modul CommonJS dan ES. Ini penting untuk proyek yang menggunakan kedua jenis modul tersebut. Ketika esModuleInterop diaktifkan, TypeScript akan secara otomatis menangani perbedaan antara modul CommonJS dan ES, membuatnya lebih mudah untuk mengimpor dan mengekspor modul di antara kedua sistem. Opsi ini sangat berguna saat bekerja dengan pustaka pihak ketiga yang mungkin menggunakan sistem modul yang berbeda.

Contoh:

            {
  "compilerOptions": {
    "esModuleInterop": true
  }
}
            

              
                Copy
              
            
          

moduleResolution

Opsi moduleResolution menentukan bagaimana TypeScript menyelesaikan impor modul. Nilai umum termasuk Node dan Classic. Strategi resolusi modul Node adalah default dan didasarkan pada algoritma resolusi modul Node.js. Strategi resolusi modul Classic lebih tua dan lebih jarang digunakan. Menggunakan strategi resolusi modul Node memastikan bahwa TypeScript dapat dengan benar menyelesaikan impor modul di lingkungan Node.js.

Contoh:

            {
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}
            

              
                Copy
              
            
          

baseUrl dan paths

Opsi baseUrl dan paths digunakan untuk mengonfigurasi resolusi modul untuk impor modul non-relatif. Opsi baseUrl menentukan direktori dasar untuk menyelesaikan nama modul non-relatif. Opsi paths memungkinkan Anda memetakan nama modul ke lokasi spesifik di sistem file. Opsi-opsi ini sangat berguna untuk proyek dengan struktur direktori yang kompleks dan untuk menyederhanakan impor modul. Menggunakan baseUrl dan paths dapat membuat kode lebih mudah dibaca dan dipelihara.

Contoh:

            {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}
            

              
                Copy
              
            
          

Opsi Include dan Exclude

Opsi include dan exclude menentukan file mana yang harus disertakan dalam kompilasi dan file mana yang harus dikecualikan. Opsi ini menggunakan pola glob untuk mencocokkan nama file. Menggunakan include dan exclude memungkinkan Anda mengontrol file mana yang diproses oleh kompiler TypeScript, meningkatkan kinerja build dan mengurangi kesalahan. Merupakan praktik terbaik untuk secara eksplisit menentukan file yang akan disertakan dalam kompilasi.

Contoh:

            {
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
            

              
                Copy
              
            
          

Opsi Extends

Opsi extends memungkinkan Anda mewarisi opsi kompiler dari file tsconfig.json lain. Ini berguna untuk berbagi pengaturan konfigurasi umum antara beberapa proyek atau untuk membuat konfigurasi dasar. Menggunakan opsi extends mempromosikan penggunaan kembali kode dan mengurangi duplikasi. Merupakan praktik terbaik untuk membuat konfigurasi dasar dan mengembangkannya di proyek-proyek individual.

Contoh:

            {
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}
            

              
                Copy
              
            
          

Konfigurasi Tingkat Lanjut

Selain opsi kompiler esensial, tsconfig.json mendukung konfigurasi tingkat lanjut untuk skenario khusus.

Kompilasi Inkremental

Untuk proyek besar, kompilasi inkremental dapat secara signifikan meningkatkan waktu build. TypeScript dapat menyimpan cache hasil kompilasi sebelumnya dan hanya mengompilasi ulang file yang telah berubah. Mengaktifkan kompilasi inkremental dapat secara dramatis mengurangi waktu build untuk proyek besar. Ini sangat penting untuk proyek dengan jumlah file dan dependensi yang besar.

            {
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}
            

              
                Copy
              
            
          

Referensi Proyek

Referensi proyek memungkinkan Anda untuk menyusun proyek TypeScript yang besar menjadi modul-modul yang lebih kecil dan independen. Ini dapat meningkatkan waktu build dan organisasi kode. Menggunakan referensi proyek dapat membuat proyek besar lebih mudah dikelola dan dipelihara. Merupakan praktik terbaik untuk menggunakan referensi proyek untuk proyek besar dan kompleks.

            {
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}
            

              
                Copy
              
            
          

Definisi Tipe Kustom

Terkadang, Anda mungkin perlu menyediakan definisi tipe untuk pustaka JavaScript yang tidak memilikinya. Anda dapat membuat file .d.ts kustom untuk mendefinisikan tipe untuk pustaka ini. Membuat definisi tipe kustom memungkinkan Anda menggunakan pustaka JavaScript dalam kode TypeScript Anda tanpa mengorbankan keamanan tipe. Ini sangat berguna saat bekerja dengan kode JavaScript lawas atau pustaka yang tidak menyediakan definisi tipe mereka sendiri.

            // custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}
            

              
                Copy
              
            
          

Praktik Terbaik

• Gunakan Mode Strict: Aktifkan opsi strict untuk pemeriksaan tipe yang lebih baik.
• Tentukan Target: Pilih versi target yang sesuai untuk lingkungan runtime Anda.
• Atur Output: Gunakan outDir untuk memisahkan kode sumber dari kode yang dikompilasi.
• Kelola Dependensi: Gunakan include dan exclude untuk mengontrol file mana yang dikompilasi.
• Manfaatkan Extends: Bagikan pengaturan konfigurasi umum dengan opsi extends.
• Masukkan Konfigurasi ke Kontrol Versi: Lakukan commit tsconfig.json ke git untuk menjaga konsistensi di seluruh lingkungan pengembang dan pipeline CI/CD.

Pemecahan Masalah Umum

Mengonfigurasi tsconfig.json terkadang bisa menjadi tantangan. Berikut adalah beberapa masalah umum dan solusinya:

Masalah Resolusi Modul

Jika Anda mengalami kesalahan resolusi modul, pastikan bahwa opsi moduleResolution dikonfigurasi dengan benar dan bahwa opsi baseUrl dan paths diatur dengan benar. Periksa kembali path yang ditentukan dalam opsi paths untuk memastikan mereka benar. Verifikasi bahwa semua modul yang diperlukan diinstal di direktori node_modules.

Kesalahan Tipe

Kesalahan tipe dapat terjadi jika definisi tipe salah atau hilang. Pastikan Anda memiliki definisi tipe yang benar terinstal untuk semua pustaka yang Anda gunakan. Jika Anda menggunakan pustaka JavaScript yang tidak memiliki definisi tipe, pertimbangkan untuk membuat definisi tipe kustom.

Kesalahan Kompilasi

Kesalahan kompilasi dapat terjadi jika ada kesalahan sintaks atau kesalahan tipe dalam kode TypeScript Anda. Tinjau pesan kesalahan dengan cermat dan perbaiki kesalahan sintaks atau kesalahan tipe apa pun. Pastikan kode Anda mengikuti konvensi pengodean TypeScript.

Kesimpulan

File tsconfig.json yang dikonfigurasi dengan baik sangat penting untuk proyek TypeScript yang sukses. Dengan memahami opsi kompiler esensial dan konfigurasi tingkat lanjut, Anda dapat mengoptimalkan alur kerja pengembangan, meningkatkan kualitas kode, dan memastikan kompatibilitas dengan lingkungan target. Menginvestasikan waktu untuk mengonfigurasi tsconfig.json dengan benar akan terbayar dalam jangka panjang dengan mengurangi kesalahan, meningkatkan keterpeliharaan, dan menyederhanakan proses build. Ini menghasilkan pengembangan perangkat lunak yang lebih efisien dan andal. Informasi yang disediakan di sini dirancang agar dapat diterapkan secara universal, dan seharusnya memberikan landasan yang kokoh untuk memulai proyek baru dengan TypeScript.

Ingatlah untuk merujuk pada dokumentasi resmi TypeScript untuk informasi terbaru dan penjelasan terperinci tentang semua opsi kompiler yang tersedia. Dokumentasi TypeScript adalah sumber daya berharga untuk memahami seluk-beluk konfigurasi TypeScript.