pubspec.yaml — co to je, struktura a konfigurace závislostí ve Flutter

Co je pubspec.yaml

pubspec.yaml — je manifestový soubor ve formátu YAML, který správce balíčků pub používá pro správu projektů Dart a Flutter. Nachází se v kořenu projektu a je zpracováván při každém příkazu flutter pub get. Na rozdíl od jiných platforem, kde je konfigurace rozptýlena po několika souborech, Flutter používá jeden centralizovaný manifest pro všechny potřeby.

Soubor obsahuje metadata: název projektu, popis, verzi, autora. Tato data se používají při publikování balíčku na pub.dev a při sestavování aplikace pro App Store a Google Play. Pole description se zobrazuje ve výsledcích vyhledávání balíčků, proto by mělo být informativní a obsahovat klíčová slova, podle kterých mohou ostatní vývojáři knihovnu najít.

Bez správného pubspec.yaml nelze projekt Flutter sestavit. Chyby syntaxe nebo nesprávná odsazení vedou k okamžitému selhání kompilace s chybovou zprávou Error on line X. YAML je citlivý na mezery: jedna mezera navíc změní strukturu dat a tabulátor způsobí syntaktickou chybu. Proto je při ruční úpravě pubspec.yaml důležité používat editor se zvýrazněním syntaxe YAML, například VS Code s oficiálním rozšířením pro Flutter.

Hlavní sekce pubspec.yaml

pubspec.yaml se skládá z povinných a volitelných sekcí. Každá sekce odpovídá za určitý aspekt konfigurace projektu. Pořadí sekcí není důležité, ale podle konvence komunity je dodržována hierarchie: metadata, prostředí, závislosti, zdroje, platformy.

name a description

Pole name nastavuje jedinečný identifikátor balíčku ve formátu snake_case, složený pouze z malých latinských písmen, číslic a podtržítek. Pole description — stručný popis projektu do 180 znaků, povinný pro publikaci na pub.dev. Popis by měl vysvětlit účel balíčku, aniž by opakoval název, a obsahovat klíčová slova pro optimalizaci vyhledávání repozitáře.

name: my_flutter_app
description: Aplikace pro správu úkolů s Flutter
publish_to: 'none'

version a environment

Pole version používá sémantické verzování major.minor.patch s volitelným číslem sestavení za znaménkem plus (1.0.0+1). Sekce environment nastavuje minimální a maximální verze Dart a Flutter SDK pro zajištění kompatibility. Pokud nová verze SDK obsahuje kritické změny nekompatibilní s kódem projektu, kompilace bude přerušena srozumitelnou chybovou zprávou.

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

dependencies a dev_dependencies

Sekce dependencies uvádí balíčky nezbytné pro chod aplikace za běhu. Sekce dev_dependencies obsahuje balíčky pro testování, generování kódu a vývoj — ty nevstupují do výsledného sestavení. Rozdělení závislostí je kritické pro výkon: každý balíček v dependencies zvětšuje velikost konečného APK nebo IPA a také prodlužuje dobu spouštění aplikace kvůli inicializaci dalších knihoven.

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

Konfigurace assets a písem

Sekce flutter obsahuje podsekce pro konfiguraci zdrojů, písem a parametrů platformy. Zdroje se připojují prostřednictvím pole paths s určením konkrétních souborů nebo celých adresářů. Všechny cesty se uvádějí relativně ke kořenu projektu, nikoli relativně k pubspec.yaml. To je důležitý detail, který často způsobuje zmatek u začínajících vývojářů 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

Připojení assets prostřednictvím pubspec.yaml zpřístupňuje soubory přes AssetBundle za běhu. To funguje pro obrázky, JSON, textové soubory a jakékoli další zdroje. Flutter automaticky podporuje různá rozlišení obrazovky: pokud umístíte images/2x/ a images/3x/, Flutter vybere odpovídající verzi obrázku na základě device pixel ratio zařízení. K tomu stačí v assets uvést pouze kořenovou složku images/.

Vlastní písma se přidávají prostřednictvím sekce fonts s určením family a seznamem typů písma. Po změně pubspec.yaml je třeba spustit flutter pub get pro aplikování nastavení. Písma lze použít jak globálně v tématu MaterialApp, tak lokálně v konkrétních widgetech. Pro každý typ písma lze určit weight (100-900) a style (normal, italic), což umožňuje Flutter správně vybrat soubor písma při použití FontWeight a FontStyle v kódu.

Správa závislostí a verzí

pub podporuje několik způsobů určení zdrojů závislostí: pub.dev, repozitáře Git, lokální cesty a soukromé repozitáře. Volba zdroje závisí na fázi vývoje: pro stabilní verze se používá pub.dev, pro forky a vlastní úpravy — Git, pro paralelně vyvíjené knihovny — lokální cesta.

Operátor ^version znamená kompatibilní verzi: ^1.2.0 povoluje verze >=1.2.0 a <2.0.0. To je obdoba operátoru ~> v CocoaPods a operátoru Caret v npm. pub automaticky řeší Dependency Hell pomocí algoritmu SAT-solver, který najde kombinaci verzí splňující všechna omezení. Pokud taková kombinace neexistuje, pub zobrazí podrobnou zprávu s uvedením konfliktních balíčků.

Soubor pubspec.lock fixuje přesné verze závislostí. Měl by být uchováván v systému správy verzí pro aplikace, aby byly zajištěny reprodukovatelná sestavení na všech počítačích týmu. Pro knihovny se pubspec.lock do repozitáře nezahrnuje, protože uživatelé knihovny by měli mít možnost ji používat s různými verzemi závislostí. Příkaz flutter pub upgrade aktualizuje všechny závislosti podle omezení pubspec.yaml a flutter pub outdated ukazuje, které balíčky lze aktualizovat.

Konfigurace sestavení a publikace

Pro publikaci aplikace na pub.dev se nastavení uvádějí v sekci publish_to. Hodnota 'none' zakazuje náhodnou publikaci balíčku, což je důležité pro interní nebo neveřejné projekty. Pokud publish_to chybí, pub se pokusí publikovat balíček na výchozím pub.dev, což může vést k nežádoucímu úniku kódu.

Sekce flutter obsahuje parametry platforem: generate pro automatické generování souborů platformy a deferred-components pro modulární načítání funkcionality. Parametr generate: true způsobí, že Flutter automaticky vytváří a aktualizuje projekty platforem (iOS, Android, Web) při přidávání nových platforem pomocí flutter create --platforms. Bez tohoto parametru může struktura složek platforem ztratit synchronizaci s pubspec.yaml.

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

Sekce platforms nastavuje cílové platformy pro balíček. Pro aplikace je automaticky určena při přidání podpory pro konkrétní platformu pomocí flutter create. Platformy lze přidávat a odebírat ručně úpravou pubspec.yaml. Deferred Components umožňují načítání částí aplikace na vyžádání, čímž se zmenšuje velikost instalace — to je důležité zejména pro hry a aplikace s velkým množstvím zřídka používaného obsahu.

Při publikaci balíčku pub kontroluje všechna pole pubspec.yaml na soulad s požadavky repozitáře. Absence povinných polí name, version a description vede k odmítnutí publikace. Dále se kontroluje správnost licence, existence README.md a CHANGELOG.md. Balíčky s chybami analyzátoru kódu (dart analyze) také neprocházejí validací. Po úspěšné publikaci je balíček k dispozici na pub.dev během několika minut.

Sekce dependency_overrides umožňuje vynutit verzi balíčku ignorováním omezení z tranzitivních závislostí. To je mocný, ale nebezpečný mechanismus: při nesprávném použití může vést k nekompatibilitě knihoven. Používejte dependency_overrides pouze dočasně pro řešení konfliktů nebo testování nových verzí. Po opravě hlavních závislostí by měl být override odstraněn, aby dlouhodobě nenarušoval graf závislostí projektu.

Sekce executables v pubspec.yaml umožňuje uvádět spustitelné skripty, které pub instaluje do PATH při aktivaci balíčku. To je užitečné pro CLI nástroje napsané v Dart, například build_runner nebo dart_code_metrics. Příkaz dart pub global activate nainstaluje balíček globálně a zpřístupní skripty uvedené v executables z terminálu. Pro aplikace se executables obvykle nepoužívají, protože vstupní bod je určen přes main v lib/main.dart.