pub: ключові поняття, менеджер пакетів Dart та pubspec.yaml

Що таке pub?

pub (Package Universal Browser) — вбудований менеджер пакетів, який постачається разом з Dart SDK. Він керує зовнішніми бібліотеками, вирішує конфлікти версій, завантажує транзитивні залежності та кешує пакети локально. В екосистемі Flutter pub використовується як основний інструмент для підключення плагінів навігації, HTTP-клієнтів, state-менеджерів та інших компонентів.

Основні функції pub включають: встановлення залежностей з реєстру pub.dev, локальних шляхів (path-залежності) та git-репозиторіїв; вирішення версій за правилами семантичного версіонування; кешування завантажених пакетів у системній директорії; публікацію власних пакетів у відкритий реєстр. Всі ці операції доступні через CLI-команду dart pub або еквівалентну flutter pub.

Архітектура pub заснована на замкненому графі залежностей: менеджер будує дерево, в якому кожен пакет присутній рівно один раз. Якщо дві бібліотеки вимагають різні версії одного пакета, pub намагається знайти сумісний діапазон або повідомляє про помилку конфлікту. Це відрізняється від підходу npm, де допускаються множинні версії одного пакета в різних вузлах дерева.

Структура pubspec.yaml

Файл pubspec.yaml — центральний конфігураційний файл будь-якого Dart- або Flutter-проекту. Він написаний у форматі YAML та містить метадані, залежності, конфігурацію збірки та обмеження SDK. Нижче наведено типовий приклад для Flutter-додатку:

name: my_app
description: Пример 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/

Ключові поля pubspec.yaml: name — унікальне ім'я пакета (тільки латиниця, нижнє підкреслення, цифри); description — короткий опис (обов'язково для публікації); version — семантична версія з опціональним build-номером після плюса; environment — мінімальні версії Dart SDK та Flutter SDK; dependencies — основні залежності додатку; dev_dependencies — залежності тільки для розробки та тестів; flutter — секція конфігурації Flutter (assets, fonts, plugins).

Поле publish_to керує доступністю публікації: значення none забороняє публікацію (типово для додатків), значення за замовчуванням — https://pub.dev. Поле dependency_overrides дозволяє примусово перевизначити версію пакета в конфліктній ситуації — використовувати з обережністю, тільки для тимчасового вирішення.

Залежності та їх види

pub підтримує чотири типи залежностей, кожен з яких вказується у своєму синтаксисі всередині pubspec.yaml:

Реєстрові (hosted)

Стандартний тип — пакет завантажується з реєстру pub.dev або іншого сумісного реєстру. Вказується ім'я пакета та версія. Приклад: http: ^1.1.0 завантажить останню сумісну версію з діапазону >=1.1.0 та <2.0.0 за правилами caret-версіонування.

SDK-залежності

Використовуються для підключення Flutter SDK або Dart SDK. Синтаксис: flutter: sdk: flutter. Пакет береться з локальної установки Flutter SDK, а не з реєстру. SDK-залежності не версіонуються — їх версія визначається поточною встановленою версією Flutter.

Шляхові (path)

Вказують на локальну директорію з пакетом. Корисні при розробці бібліотеки та тестуванні без публікації. Синтаксис:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Шляхові залежності не фіксуються в pubspec.lock — кожне оновлення заново вирішується із зазначеного шляху.

Git-залежності

Дозволяють підключати пакет безпосередньо з git-репозиторію. Підтримуються гілки, теги та коміти:

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

Git-залежності зручні для форків, неопублікованих виправлень або роботи над Pull Request. Рекомендується вказувати конкретний тег або коміт замість гілки, щоб уникнути несподіваних змін під час збірки.

Версіонування та діапазони

pub суворо дотримується Semantic Versioning 2.0: формат MAJOR.MINOR.PATCH, де MAJOR — несумісні зміни, MINOR — зворотно сумісні додавання, PATCH — зворотно сумісні виправлення. На основі цієї схеми pub визначає сумісність пакетів та вирішує конфлікти.

Для завдання версій використовуються три основних оператори в pubspec.yaml:

• Caret (^) — ^1.2.3 еквівалентно >=1.2.3 та <2.0.0. Найпоширеніший оператор, оскільки передбачає сумісність в межах мажорної версії. Для пакетів з мажорною версією 0 (нульова) — ^0.1.2 означає >=0.1.2 та <0.2.0, що відповідає правилам SemVer для нестабільних версій.
• Тильда (~) — ~1.2.3 еквівалентно >=1.2.3 та <1.3.0. Фіксує мінорну версію, дозволяючи лише patch-оновлення. Рідше використовується, в основному коли відома несумісність на рівні мінорної версії.
• Точний діапазон — >=1.2.0 <2.0.0 — явний запис, що дає повний контроль. Корисний для складних обмежень, наприклад при використанні декількох версій транзитивних залежностей.

Після виконання dart pub get pub генерує файл pubspec.lock, який фіксує точні версії всіх вирішених пакетів (прямих та транзитивних). Цей файл необхідно включати в систему контролю версій для забезпечення відтворюваних збірок на всіх машинах. При виконанні dart pub upgrade lock-файл оновлюється до останніх сумісних версій в межах заданих обмежень.

Помилка dependency conflict виникає, коли два пакети вимагають непересічні діапазони однієї залежності. pub повідомляє, які пакети вступили в конфлікт і з якої причини. Рішення: оновити один з конфліктуючих пакетів до сумісної версії, використати dependency_overrides (тимчасовий захід) або змінити пакет на альтернативу.

Основні команди pub

Всі операції pub виконуються через єдиний CLI-інтерфейс. У Dart SDK використовується команда dart pub, у Flutter SDK — еквівалентна flutter pub (додатково враховує Flutter SDK-залежності та плагіни). Нижче наведені ключові команди:

• dart pub get — завантажує всі залежності, зазначені в pubspec.yaml, вирішує версії та створює/оновлює pubspec.lock. Виконується при першому клонуванні проекту або після зміни залежностей.
• dart pub upgrade — оновлює всі залежності до останніх версій в межах обмежень pubspec.yaml та перезаписує pubspec.lock. Можна оновити окремий пакет: dart pub upgrade http.
• dart pub add <package> — додає нову залежність в pubspec.yaml і одразу виконує pub get. Приклад: dart pub add dio додасть останню версію пакета dio.
• dart pub remove <package> — видаляє залежність з pubspec.yaml та перезапускає вирішення графа.
• dart pub cache repair — перезавантажує всі кешовані пакети. Допомагає при пошкодженні локального кешу або помилках контрольних сум.
• dart pub deps — виводить дерево залежностей у зручному текстовому форматі. Корисно для аналізу транзитивних залежностей та пошуку дублювань.
• dart pub publish — публікує поточний пакет на pub.dev. Перед публікацією перевіряє коректність pubspec.yaml, ліцензію та опис.
• dart pub outdated — показує список застарілих залежностей із зазначенням поточної, бажаної та останньої доступної версії. Аналог npm outdated.

Всі команди доступні також у скороченій формі dart pub get як dart pub g (не всі скорочення). У Flutter-проектах перед командами pub додається префікс flutter: flutter pub get, flutter pub add і так далі. Flutter-версія додатково перевіряє сумісність плагінів з цільовою платформою.

Публікація на pub.dev

pub.dev — центральний реєстр пакетів екосистеми Dart та Flutter. На січень 2025 року там опубліковано понад 50 000 пакетів, сумарно завантажених понад 10 мільярдів разів. Кожен пакет має сторінку з описом, документацією, оцінками популярності (Popularity), балами Pub Points та версіями.

Pub Points — автоматична система оцінки якості пакета від 0 до 130 балів. Враховуються: наявність ліцензії, опис, приклади, сумісність з останньою стабільною версією Dart, відсутність вразливостей, покриття тестами, коректність форматування. Високий бал підвищує видимість пакета в пошуку та довіру користувачів.

Процес публікації включає кілька кроків:

1. Перевірити pubspec.yaml: наявність name, description, version, license (рекомендується вказувати SPDX-ідентифікатор, наприклад MIT).
2. Запустити dart pub publish --dry-run — імітація публікації без відправлення на сервер, відображає всі файли, які будуть включені в пакет, та можливі помилки.
3. Авторизуватися через Google-акаунт при першій публікації: dart pub publish відкриє браузер для OAuth-аутентифікації.
4. Підтвердити публікацію в терміналі. Після успішного відправлення пакет з'являється на pub.dev протягом кількох хвилин.

Важливі правила: публікувати можна тільки пакети з унікальним ім'ям; одного разу опубліковану версію не можна видалити (можна тільки приховати — dart pub unpublish — протягом 7 днів); для великих оновлень слід дотримуватися правил Semantic Versioning, не ламати публічний API без зміни мажорної версії.