pubspec.yaml — ce este, structura și configurarea dependențelor în Flutter

Ce este pubspec.yaml

pubspec.yaml — este un fișier manifest în format YAML pe care managerul de pachete pub îl folosește pentru gestionarea proiectelor Dart și Flutter. Se află în rădăcina proiectului și este procesat la fiecare comandă flutter pub get. Spre deosebire de alte platforme unde configurarea este distribuită în mai multe fișiere, Flutter folosește un manifest centralizat pentru toate necesitățile.

Fișierul conține metadate: numele proiectului, descrierea, versiunea, autorul. Aceste date sunt utilizate la publicarea pachetului pe pub.dev și la construirea aplicației pentru App Store și Google Play. Câmpul description este afișat în rezultatele căutării pachetelor, de aceea trebuie să fie informativ și să conțină cuvinte cheie după care alți dezvoltatori să poată găsi biblioteca.

Fără un pubspec.yaml corect, proiectul Flutter nu poate fi construit. Erorile de sintaxă sau indentările incorecte duc la eșecul imediat al compilării cu mesajul Error on line X. YAML este sensibil la spații: un spațiu în plus modifică structura datelor, iar tabulatorul cauzează o eroare de sintaxă. De aceea, la editarea manuală a pubspec.yaml este important să folosiți un editor cu evidențierea sintaxei YAML, de exemplu VS Code cu extensia oficială pentru Flutter.

Secțiunile principale ale pubspec.yaml

pubspec.yaml este format din secțiuni obligatorii și opționale. Fiecare secțiune este responsabilă pentru un aspect specific al configurării proiectului. Ordinea secțiunilor nu este importantă, dar conform convenției comunității se respectă ierarhia: metadate, mediu, dependențe, resurse, platforme.

name și description

Câmpul name stabilește identificatorul unic al pachetului în format snake_case, format doar din litere mici latine, cifre și underscore. Câmpul description — o descriere scurtă a proiectului de până la 180 de caractere, obligatorie pentru publicarea pe pub.dev. Descrierea trebuie să explice scopul pachetului, fără a repeta numele, și să conțină cuvinte cheie pentru optimizarea căutării în depozit.

name: my_flutter_app
description: Aplicație pentru gestionarea sarcinilor cu Flutter
publish_to: 'none'

version și environment

Câmpul version folosește versionarea semantică major.minor.patch cu un număr opțional de construire după semnul plus (1.0.0+1). Secțiunea environment stabilește versiunile minime și maxime ale Dart și Flutter SDK pentru garantarea compatibilității. Dacă o nouă versiune a SDK conține modificări critice incompatibile cu codul proiectului, compilarea se va întrerupe cu un mesaj de eroare clar.

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

dependencies și dev_dependencies

Secțiunea dependencies enumeră pachetele necesare pentru funcționarea aplicației în runtime. Secțiunea dev_dependencies conține pachete pentru testare, generare de cod și dezvoltare — ele nu intră în versiunea de producție. Împărțirea dependențelor este esențială pentru performanță: fiecare pachet din dependencies mărește dimensiunea APK sau IPA final, precum și timpul de pornire a aplicației din cauza inițializării bibliotecilor suplimentare.

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

Configurarea assets și fonturilor

Secțiunea flutter conține subsecțiuni pentru configurarea resurselor, fonturilor și parametrilor platformei. Resursele se conectează prin intermediul unui array paths cu specificarea fișierelor concrete sau a întregilor directoare. Toate căile sunt indicate relativ la rădăcina proiectului, nu relativ la pubspec.yaml. Aceasta este o nuanță importantă care provoacă adesea confuzie la dezvoltatorii începători Flutter.

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

Conectarea assets prin pubspec.yaml face fișierele accesibile prin AssetBundle în runtime. Acest lucru funcționează pentru imagini, JSON, fișiere text și orice alte resurse. Flutter suportă automat diferite rezoluții de ecran: dacă puneți images/2x/ și images/3x/, Flutter va selecta versiunea potrivită a imaginii pe baza device pixel ratio a dispozitivului. Pentru aceasta este suficient să indicați în assets doar directorul rădăcină images/.

Fonturile personalizate se adaugă prin secțiunea fonts cu specificarea family și lista de caractere tipografice. După modificarea pubspec.yaml este necesar să executați flutter pub get pentru aplicarea setărilor. Fonturile pot fi folosite atât global în tema MaterialApp, cât și local în widgeturi specifice. Pentru fiecare caracter tipografic se poate specifica weight (100-900) și style (normal, italic), ceea ce permite Flutter să selecteze corect fișierul fontului la utilizarea FontWeight și FontStyle în cod.

Gestionarea dependențelor și versiunilor

pub suportă mai multe moduri de specificare a surselor dependențelor: pub.dev, depozite Git, căi locale și depozite private. Alegerea sursei depinde de etapa de dezvoltare: pentru versiunile stabile se folosește pub.dev, pentru fork-uri și modificări personalizate — Git, pentru bibliotecile dezvoltate în paralel — calea locală.

Operatorul ^version înseamnă versiune compatibilă: ^1.2.0 permite versiunile >=1.2.0 și <2.0.0. Acesta este analogul operatorului ~> în CocoaPods și al operatorului Caret în npm. pub rezolvă automat Dependency Hell prin algoritmul SAT-solver care găsește o combinație de versiuni care satisface toate restricțiile. Dacă o astfel de combinație nu există, pub afișează un mesaj detaliat cu indicarea pachetelor conflictuale.

Fișierul pubspec.lock fixează versiunile exacte ale dependențelor. Trebuie păstrat în sistemul de control al versiunilor pentru aplicații, pentru a asigura compilări reproductibile pe toate mașinile echipei. Pentru biblioteci pubspec.lock nu se include în depozit, deoarece utilizatorii bibliotecii trebuie să poată folosi aceasta cu diferite versiuni ale dependențelor. Comanda flutter pub upgrade actualizează toate dependențele conform restricțiilor din pubspec.yaml, iar flutter pub outdated arată ce pachete pot fi actualizate.

Configurarea construirii și publicării

Pentru publicarea aplicației pe pub.dev setările se specifică în secțiunea publish_to. Valoarea 'none' interzice publicarea accidentală a pachetului, ceea ce este important pentru proiecte interne sau ne publice. Dacă publish_to lipsește, pub încearcă să publice pachetul pe pub.dev implicit, ceea ce poate duce la scurgerea nedorită a codului.

Secțiunea flutter include parametrii platformelor: generate pentru generarea automată a fișierelor de platformă și deferred-components pentru încărcarea modulară a funcționalității. Parametrul generate: true face ca Flutter să creeze și să actualizeze automat proiectele de platformă (iOS, Android, Web) la adăugarea de noi platforme prin flutter create --platforms. Fără acest parametru, structura folderelor de platformă se poate desincroniza cu pubspec.yaml.

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

Secțiunea platforms stabilește platformele țintă pentru pachet. Pentru aplicații este determinată automat la adăugarea suportului pentru o platformă specifică prin flutter create. Platformele pot fi adăugate și eliminate manual prin editarea pubspec.yaml. Deferred Components permit încărcarea părților aplicației la cerere, reducând dimensiunea instalării — acest lucru este relevant în special pentru jocuri și aplicații cu mult conținut rar utilizat.

La publicarea pachetului, pub verifică toate câmpurile pubspec.yaml pentru conformitatea cu cerințele depozitului. Absența câmpurilor obligatorii name, version și description duce la respingerea publicării. În plus, se verifică corectitudinea licenței, existența README.md și CHANGELOG.md. Pachetele cu erori ale analizorului de cod (dart analyze) nu trec nici ele de validare. După publicarea cu succes, pachetul devine disponibil pe pub.dev în câteva minute.

Secțiunea dependency_overrides permite forțarea versiunii unui pachet, ignorând restricțiile din dependențele tranzitive. Acesta este un mecanism puternic, dar periculos: în caz de utilizare incorectă poate duce la incompatibilitatea bibliotecilor. Folosiți dependency_overrides doar temporar pentru rezolvarea conflictelor sau testarea versiunilor noi. După remedierea dependențelor principale, override trebuie eliminat pentru a nu perturba graful de dependențe al proiectului pe termen lung.

Secțiunea executables în pubspec.yaml permite specificarea scripturilor executabile pe care pub le instalează în PATH la activarea pachetului. Acest lucru este util pentru instrumente CLI scrise în Dart, de exemplu build_runner sau dart_code_metrics. Comanda dart pub global activează pachetul global, făcând scripturile specificate în executables disponibile din terminal. Pentru aplicații executables nu se folosesc de obicei, deoarece punctul de intrare este determinat prin main în lib/main.dart.