pub: konsep kunci, manajer paket Dart dan pubspec.yaml

Apa itu pub?

pub (Package Universal Browser) — manajer paket bawaan yang disertakan dengan Dart SDK. Ini mengelola pustaka eksternal, menyelesaikan konflik versi, mengunduh dependensi transitif, dan menyimpan cache paket secara lokal. Dalam ekosistem Flutter, pub digunakan sebagai alat utama untuk menghubungkan plugin navigasi, klien HTTP, manajer state, dan komponen lainnya.

Fungsi utama pub meliputi: instalasi dependensi dari register pub.dev, jalur lokal (dependensi path) dan repositori git; penyelesaian versi sesuai aturan versioning semantik; penyimpanan cache paket yang diunduh di direktori sistem; publikasi paket sendiri di register terbuka. Semua operasi ini tersedia melalui perintah CLI dart pub atau yang setara flutter pub.

Arsitektur pub didasarkan pada grafik dependensi tertutup: manajer membangun pohon di mana setiap paket muncul tepat satu kali. Jika dua pustaka memerlukan versi berbeda dari paket yang sama, pub mencoba menemukan rentang yang kompatibel atau melaporkan kesalahan konflik. Ini berbeda dengan pendekatan npm, di mana beberapa versi dari paket yang sama diperbolehkan di node pohon yang berbeda.

Struktur pubspec.yaml

File pubspec.yaml — file konfigurasi pusat dari setiap proyek Dart atau Flutter. Ditulis dalam format YAML dan berisi metadata, dependensi, konfigurasi build, dan batasan SDK. Di bawah ini adalah contoh tipikal untuk aplikasi Flutter:

name: my_app
description: Contoh aplikasi Flutter
version: 1.0.0+1
publish_to: none

environment:
  sdk: ">=3.0.0 <4.0.0"
  flutter: ">=3.10.0"

dependencies:
  flutter:
    sdk: flutter
  http: ^1.1.0
  provider: ^6.0.5
  shared_preferences: ^2.2.0
  path_provider: ^2.1.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0
  mockito: ^5.4.3

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/fonts/

Bidang kunci pubspec.yaml: name — nama unik paket (hanya huruf Latin, garis bawah, angka); description — deskripsi singkat (wajib untuk publikasi); version — versi semantik dengan nomor build opsional setelah tanda plus; environment — versi minimum Dart SDK dan Flutter SDK; dependencies — dependensi utama aplikasi; dev_dependencies — dependensi hanya untuk pengembangan dan pengujian; flutter — bagian konfigurasi Flutter (assets, fonts, plugins).

Bidang publish_to mengontrol ketersediaan publikasi: nilai none melarang publikasi (tipikal untuk aplikasi), nilai default — https://pub.dev. Bidang dependency_overrides memungkinkan mengganti versi paket secara paksa dalam situasi konflik — gunakan dengan hati-hati, hanya untuk solusi sementara.

Dependensi dan jenisnya

pub mendukung empat jenis dependensi, masing-masing ditentukan dengan sintaksnya sendiri di dalam pubspec.yaml:

Register (hosted)

Jenis standar — paket diunduh dari register pub.dev atau register kompatibel lainnya. Nama paket dan versi ditentukan. Contoh: http: ^1.1.0 akan mengunduh versi kompatibel terbaru dari rentang >=1.1.0 dan <2.0.0 sesuai aturan versioning caret.

Dependensi SDK

Digunakan untuk menghubungkan Flutter SDK atau Dart SDK. Sintaks: flutter: sdk: flutter. Paket diambil dari instalasi lokal Flutter SDK, bukan dari register. Dependensi SDK tidak memiliki versi — versinya ditentukan oleh versi Flutter yang terinstal saat ini.

Path (jalur)

Menunjuk ke direktori lokal yang berisi paket. Berguna saat mengembangkan pustaka dan menguji tanpa publikasi. Sintaks:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Dependensi path tidak dicatat dalam pubspec.lock — setiap pembaruan diselesaikan ulang dari jalur yang ditentukan.

Dependensi Git

Memungkinkan menghubungkan paket langsung dari repositori git. Cabang, tag, dan commit didukung:

dependencies:
  my_git_lib:
    git:
      url: https://github.com/user/my_git_lib.git
      ref: main

Dependensi Git berguna untuk fork, perbaikan yang tidak dipublikasikan, atau pekerjaan pada Pull Request. Disarankan untuk menentukan tag atau commit tertentu daripada cabang, untuk menghindari perubahan tak terduga saat build.

Versioning dan rentang

pub secara ketat mengikuti Semantic Versioning 2.0: format MAJOR.MINOR.PATCH, di mana MAJOR — perubahan yang tidak kompatibel, MINOR — penambahan yang kompatibel mundur, PATCH — perbaikan yang kompatibel mundur. Berdasarkan skema ini, pub menentukan kompatibilitas paket dan menyelesaikan konflik.

Untuk menentukan versi, tiga operator utama digunakan dalam pubspec.yaml:

• Caret (^) — ^1.2.3 setara dengan >=1.2.3 dan <2.0.0. Operator yang paling umum, karena mengasumsikan kompatibilitas dalam versi major. Untuk paket dengan versi major 0 (nol) — ^0.1.2 berarti >=0.1.2 dan <0.2.0, sesuai dengan aturan SemVer untuk versi tidak stabil.
• Tilde (~) — ~1.2.3 setara dengan >=1.2.3 dan <1.3.0. Menetapkan versi minor, hanya mengizinkan pembaruan patch. Lebih jarang digunakan, terutama ketika ketidakcocokan pada tingkat minor diketahui.
• Rentang tepat — >=1.2.0 <2.0.0 — notasi eksplisit yang memberikan kontrol penuh. Berguna untuk batasan kompleks, misalnya saat menggunakan beberapa versi dependensi transitif.

Setelah menjalankan dart pub get, pub menghasilkan file pubspec.lock, yang menetapkan versi pasti dari semua paket yang telah diselesaikan (langsung dan transitif). File ini harus disertakan dalam sistem kontrol versi untuk memastikan build yang dapat direproduksi di semua mesin. Saat menjalankan dart pub upgrade, file lock diperbarui ke versi kompatibel terbaru dalam batasan yang ditentukan.

Kesalahan dependency conflict terjadi ketika dua paket memerlukan rentang yang tidak tumpang tindih dari dependensi yang sama. pub melaporkan paket mana yang mengalami konflik dan alasannya. Solusi: perbarui salah satu paket yang bertikai ke versi yang kompatibel, gunakan dependency_overrides (tindakan sementara) atau ganti paket dengan alternatif.

Perintah dasar pub

Semua operasi pub dijalankan melalui antarmuka CLI terpadu. Di Dart SDK digunakan perintah dart pub, di Flutter SDK — yang setara flutter pub (juga mempertimbangkan dependensi Flutter SDK dan plugin). Berikut adalah perintah-perintah kunci:

• dart pub get — mengunduh semua dependensi yang ditentukan dalam pubspec.yaml, menyelesaikan versi dan membuat/memperbarui pubspec.lock. Dilakukan saat pertama kali mengkloning proyek atau setelah mengubah dependensi.
• dart pub upgrade — memperbarui semua dependensi ke versi terbaru dalam batasan pubspec.yaml dan menimpa pubspec.lock. Dapat memperbarui satu paket: dart pub upgrade http.
• dart pub add <package> — menambahkan dependensi baru ke pubspec.yaml dan segera menjalankan pub get. Contoh: dart pub add dio akan menambahkan versi terbaru dari paket dio.
• dart pub remove <package> — menghapus dependensi dari pubspec.yaml dan memulai ulang penyelesaian grafik.
• dart pub cache repair — memuat ulang semua paket yang di-cache. Membantu saat kerusakan cache lokal atau kesalahan checksum.
• dart pub deps — menampilkan pohon dependensi dalam format teks yang mudah dibaca. Berguna untuk menganalisis dependensi transitif dan menemukan duplikasi.
• dart pub publish — mempublikasikan paket saat ini ke pub.dev. Sebelum publikasi, memeriksa kebenaran pubspec.yaml, lisensi dan deskripsi.
• dart pub outdated — menampilkan daftar dependensi usang dengan versi saat ini, yang diinginkan, dan versi terbaru yang tersedia. Analog dengan npm outdated.

Semua perintah juga tersedia dalam bentuk singkatan: dart pub get sebagai dart pub g (tidak semua singkatan). Dalam proyek Flutter, awalan flutter ditambahkan ke perintah pub: flutter pub get, flutter pub add dan seterusnya. Versi Flutter juga memeriksa kompatibilitas plugin dengan platform target.

Publikasi di pub.dev

pub.dev — register paket pusat ekosistem Dart dan Flutter. Per Januari 2025, lebih dari 50.000 paket telah dipublikasikan di sana, dengan total unduhan lebih dari 10 miliar kali. Setiap paket memiliki halaman dengan deskripsi, dokumentasi, peringkat popularitas (Popularity), skor Pub Points dan versi.

Pub Points — sistem penilaian kualitas paket otomatis dari 0 hingga 130 poin. Dipertimbangkan: keberadaan lisensi, deskripsi, contoh, kompatibilitas dengan versi stabil Dart terbaru, tidak adanya kerentanan, cakupan tes, kebenaran pemformatan. Skor tinggi meningkatkan visibilitas paket dalam pencarian dan kepercayaan pengguna.

Proses publikasi mencakup beberapa langkah:

1. Periksa pubspec.yaml: keberadaan name, description, version, license (disarankan untuk menentukan pengenal SPDX, misalnya MIT).
2. Jalankan dart pub publish --dry-run — simulasi publikasi tanpa mengirim ke server, menampilkan semua file yang akan disertakan dalam paket dan kemungkinan kesalahan.
3. Otorisasi melalui akun Google pada publikasi pertama: dart pub publish akan membuka browser untuk otentikasi OAuth.
4. Konfirmasi publikasi di terminal. Setelah pengiriman berhasil, paket muncul di pub.dev dalam beberapa menit.

Aturan penting: hanya paket dengan nama unik yang dapat dipublikasikan; versi yang sudah dipublikasikan tidak dapat dihapus (hanya dapat disembunyikan — dart pub unpublish — dalam 7 hari); untuk pembaruan besar, aturan Semantic Versioning harus diikuti, jangan merusak API publik tanpa mengubah versi major.