pubspec.yaml — apa itu, struktur dan konfigurasi dependensi di Flutter

Apa itu pubspec.yaml

pubspec.yaml — adalah file manifes dalam format YAML yang digunakan manajer paket pub untuk mengelola proyek Dart dan Flutter. File ini terletak di root proyek dan diproses pada setiap perintah flutter pub get. Tidak seperti platform lain di mana konfigurasi tersebar di beberapa file, Flutter menggunakan satu manifes terpusat untuk semua kebutuhan.

File ini berisi metadata: nama proyek, deskripsi, versi, penulis. Data ini digunakan saat mempublikasikan paket ke pub.dev dan saat membangun aplikasi untuk App Store dan Google Play. Bidang description ditampilkan di hasil pencarian paket, oleh karena itu harus informatif dan berisi kata kunci yang memungkinkan pengembang lain menemukan pustaka tersebut.

Tanpa pubspec.yaml yang benar, proyek Flutter tidak dapat dibangun. Kesalahan sintaks atau indentasi yang salah menyebabkan kegagalan kompilasi segera dengan pesan Error on line X. YAML sensitif terhadap spasi: satu spasi tambahan mengubah struktur data, dan tabulasi menyebabkan kesalahan sintaks. Oleh karena itu, saat mengedit pubspec.yaml secara manual, penting untuk menggunakan editor dengan penyorotan sintaks YAML, misalnya VS Code dengan ekstensi resmi untuk Flutter.

Bagian utama pubspec.yaml

pubspec.yaml terdiri dari bagian wajib dan opsional. Setiap bagian bertanggung jawab untuk aspek tertentu dari konfigurasi proyek. Urutan bagian tidak penting, tetapi menurut konvensi komunitas, hierarki dipatuhi: metadata, lingkungan, dependensi, sumber daya, platform.

name dan description

Bidang name menetapkan pengidentifikasi unik paket dalam format snake_case, hanya terdiri dari huruf Latin kecil, angka, dan garis bawah. Bidang description — deskripsi singkat proyek hingga 180 karakter, wajib untuk publikasi di pub.dev. Deskripsi harus menjelaskan tujuan paket, tanpa mengulangi nama, dan berisi kata kunci untuk optimasi pencarian repositori.

name: my_flutter_app
description: Aplikasi pengelolaan tugas dengan Flutter
publish_to: 'none'

version dan environment

Bidang version menggunakan versi semantik major.minor.patch dengan nomor build opsional setelah tanda plus (1.0.0+1). Bagian environment menetapkan versi minimum dan maksimum Dart dan Flutter SDK untuk menjamin kompatibilitas. Jika versi SDK baru berisi perubahan kritis yang tidak kompatibel dengan kode proyek, kompilasi akan dihentikan dengan pesan kesalahan yang jelas.

version: 1.0.0+1
environment:
  sdk: '>=3.2.0 <4.0.0'
  flutter: '>=3.16.0'

dependencies dan dev_dependencies

Bagian dependencies mencantumkan paket yang diperlukan untuk menjalankan aplikasi saat runtime. Bagian dev_dependencies berisi paket untuk pengujian, pembuatan kode, dan pengembangan — paket-paket ini tidak masuk ke dalam build rilis. Pembagian dependensi sangat penting untuk kinerja: setiap paket di dependencies meningkatkan ukuran APK atau IPA akhir, serta waktu startup aplikasi karena inisialisasi pustaka tambahan.

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0
  provider: ^6.1.0
  shared_preferences: ^2.2.0
  cached_network_image: ^3.3.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  mockito: ^5.4.0
  build_runner: ^2.4.0

Konfigurasi assets dan font

Bagian flutter berisi subbagian untuk konfigurasi sumber daya, font, dan parameter platform. Sumber daya dihubungkan melalui array paths dengan menentukan file tertentu atau seluruh direktori. Semua jalur ditentukan relatif terhadap root proyek, bukan relatif terhadap pubspec.yaml. Ini adalah nuansa penting yang sering menyebabkan kebingungan pada pengembang Flutter pemula.

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/icons/
    - assets/config.json
    - assets/data/translations/
  fonts:
    - family: RobotoMono
      fonts:
        - asset: fonts/RobotoMono-Regular.ttf
        - asset: fonts/RobotoMono-Bold.ttf
          weight: 700
        - asset: fonts/RobotoMono-Italic.ttf
          style: italic

Menghubungkan assets melalui pubspec.yaml membuat file dapat diakses melalui AssetBundle saat runtime. Ini berfungsi untuk gambar, JSON, file teks, dan sumber daya lainnya. Flutter secara otomatis mendukung resolusi layar yang berbeda: jika Anda menempatkan images/2x/ dan images/3x/, Flutter akan memilih versi gambar yang sesuai berdasarkan device pixel ratio perangkat. Untuk ini, cukup menentukan di assets hanya folder root images/.

Font kustom ditambahkan melalui bagian fonts dengan menentukan family dan daftar jenis huruf. Setelah mengubah pubspec.yaml, flutter pub get harus dijalankan untuk menerapkan pengaturan. Font dapat digunakan secara global dalam tema MaterialApp maupun secara lokal di widget tertentu. Untuk setiap jenis huruf, weight (100-900) dan style (normal, italic) dapat ditentukan, memungkinkan Flutter memilih file font yang tepat saat menggunakan FontWeight dan FontStyle dalam kode.

Manajemen dependensi dan versi

pub mendukung beberapa cara untuk menentukan sumber dependensi: pub.dev, repositori Git, jalur lokal, dan repositori privat. Pemilihan sumber tergantung pada tahap pengembangan: untuk versi stabil digunakan pub.dev, untuk fork dan modifikasi kustom — Git, untuk pustaka yang dikembangkan secara paralel — jalur lokal.

Operator ^version berarti versi yang kompatibel: ^1.2.0 mengizinkan versi >=1.2.0 dan <2.0.0. Ini analog dengan operator ~> di CocoaPods dan operator Caret di npm. pub secara otomatis menyelesaikan Dependency Hell melalui algoritma SAT-solver yang menemukan kombinasi versi yang memenuhi semua batasan. Jika kombinasi semacam itu tidak ada, pub menampilkan pesan terperinci dengan menunjukkan paket yang konflik.

File pubspec.lock menetapkan versi pasti dependensi. File ini harus disimpan dalam sistem kontrol versi untuk aplikasi guna memastikan build yang dapat direproduksi di semua mesin tim. Untuk pustaka, pubspec.lock tidak disertakan dalam repositori, karena pengguna pustaka harus dapat menggunakannya dengan berbagai versi dependensi. Perintah flutter pub upgrade memperbarui semua dependensi sesuai batasan pubspec.yaml, dan flutter pub outdated menunjukkan paket mana yang dapat diperbarui.

Konfigurasi pembangunan dan publikasi

Untuk mempublikasikan aplikasi ke pub.dev, pengaturan ditentukan di bagian publish_to. Nilai 'none' melarang publikasi paket yang tidak disengaja, yang penting untuk proyek internal atau non-publik. Jika publish_to tidak ada, pub mencoba mempublikasikan paket ke pub.dev default, yang dapat menyebabkan kebocoran kode yang tidak diinginkan.

Bagian flutter berisi parameter platform: generate untuk pembuatan otomatis file platform dan deferred-components untuk pemuatan fungsionalitas modular. Parameter generate: true menyebabkan Flutter secara otomatis membuat dan memperbarui proyek platform (iOS, Android, Web) saat menambahkan platform baru melalui flutter create --platforms. Tanpa parameter ini, struktur folder platform dapat tidak sinkron dengan pubspec.yaml.

flutter:
  generate: true
  deferred-components:
    - name: photoEditor
      libraries:
        - package:photo_editor/library.dart

Bagian platforms menetapkan platform target untuk paket. Untuk aplikasi, ini ditentukan secara otomatis saat menambahkan dukungan untuk platform tertentu melalui flutter create. Platform dapat ditambahkan dan dihapus secara manual melalui pengeditan pubspec.yaml. Deferred Components memungkinkan memuat bagian aplikasi sesuai permintaan, mengurangi ukuran instalasi — ini sangat relevan untuk game dan aplikasi dengan banyak konten yang jarang digunakan.

Saat mempublikasikan paket, pub memeriksa semua bidang pubspec.yaml untuk kesesuaian dengan persyaratan repositori. Tidak adanya bidang wajib name, version, dan description menyebabkan penolakan publikasi. Selain itu, validitas lisensi, keberadaan README.md dan CHANGELOG.md diperiksa. Paket dengan kesalahan penganalisis kode (dart analyze) juga tidak lulus validasi. Setelah publikasi berhasil, paket tersedia di pub.dev dalam beberapa menit.

Bagian dependency_overrides memungkinkan memaksa versi paket, mengabaikan batasan dari dependensi transitif. Ini adalah mekanisme yang kuat namun berbahaya: jika digunakan secara tidak benar, dapat menyebabkan ketidakcocokan pustaka. Gunakan dependency_overrides hanya sementara untuk menyelesaikan konflik atau menguji versi baru. Setelah memperbaiki dependensi utama, override harus dihapus agar tidak mengganggu grafik dependensi proyek dalam jangka panjang.

Bagian executables di pubspec.yaml memungkinkan menentukan skrip yang dapat dieksekusi yang dipasang pub di PATH saat mengaktifkan paket. Ini berguna untuk alat CLI yang ditulis dalam Dart, misalnya build_runner atau dart_code_metrics. Perintah dart pub global activate memasang paket secara global, membuat skrip yang ditentukan di executables tersedia dari terminal. Untuk aplikasi, executables biasanya tidak digunakan, karena titik masuk ditentukan melalui main di lib/main.dart.