pubspec.yaml — wat is het, structuur en configuratie van afhankelijkheden in Flutter

Wat is pubspec.yaml

pubspec.yaml — is een manifestbestand in YAML-formaat dat de pakketbeheerder pub gebruikt voor het beheren van Dart- en Flutter-projecten. Het bevindt zich in de hoofdmap van het project en wordt verwerkt bij elke flutter pub get-opdracht. In tegenstelling tot andere platforms waar configuratie over meerdere bestanden is verspreid, gebruikt Flutter één gecentraliseerd manifest voor alle behoeften.

Het bestand bevat metadata: projectnaam, beschrijving, versie, auteur. Deze gegevens worden gebruikt bij het publiceren van het pakket op pub.dev en bij het bouwen van de app voor App Store en Google Play. Het veld description wordt weergegeven in zoekresultaten van pakketten, dus het moet informatief zijn en zoekwoorden bevatten waarmee andere ontwikkelaars de bibliotheek kunnen vinden.

Zonder een correct pubspec.yaml kan een Flutter-project niet worden gebouwd. Syntaxisfouten of onjuiste inspringing leiden tot onmiddellijke compilatiefout met de melding Error on line X. YAML is gevoelig voor spaties: één extra spatie verandert de datastructuur en een tabblad veroorzaakt een syntaxisfout. Daarom is het bij handmatig bewerken van pubspec.yaml belangrijk een editor te gebruiken met YAML-syntaxishighlighting, zoals VS Code met de officiële extensie voor Flutter.

Belangrijkste secties van pubspec.yaml

pubspec.yaml bestaat uit verplichte en optionele secties. Elke sectie is verantwoordelijk voor een specifiek aspect van de configuratie van het project. De volgorde van secties is niet belangrijk, maar volgens de community-conventie wordt een hiërarchie aangehouden: metadata, omgeving, afhankelijkheden, bronnen, platforms.

name en description

Het veld name stelt de unieke identificatie van het pakket in snake_case-formaat in, bestaande uit alleen kleine Latijnse letters, cijfers en underscores. Het veld description — een korte beschrijving van het project tot 180 tekens, verplicht voor publicatie op pub.dev. De beschrijving moet het doel van het pakket uitleggen, zonder de naam te herhalen, en zoekwoorden bevatten voor zoekoptimalisatie van de repository.

name: my_flutter_app
description: Takenbeheer-app met Flutter
publish_to: 'none'

version en environment

Het veld version gebruikt semantische versiebeheer major.minor.patch met een optioneel buildnummer na het plusteken (1.0.0+1). De sectie environment stelt de minimale en maximale versies van Dart en Flutter SDK in voor compatibiliteitsgarantie. Als een nieuwe versie van de SDK kritieke wijzigingen bevat die incompatibel zijn met de projectcode, wordt de compilatie onderbroken met een duidelijke foutmelding.

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

dependencies en dev_dependencies

De sectie dependencies somt de pakketten op die nodig zijn voor de werking van de app in runtime. De sectie dev_dependencies bevat pakketten voor testen, codegeneratie en ontwikkeling — ze komen niet in de release-build. Het scheiden van afhankelijkheden is essentieel voor prestaties: elk pakket in dependencies vergroot de grootte van de uiteindelijke APK of IPA en verhoogt de opstarttijd van de app door initialisatie van extra bibliotheken.

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

Configuratie van assets en lettertypen

De sectie flutter bevat subsecties voor het configureren van bronnen, lettertypen en platformparameters. Bronnen worden gekoppeld via een array paths met specificatie van specifieke bestanden of hele mappen. Alle paden worden relatief ten opzichte van de projecthoofdmap opgegeven, niet ten opzichte van pubspec.yaml. Dit is een belangrijk detail dat vaak verwarring veroorzaakt bij beginnende Flutter-ontwikkelaars.

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

Het koppelen van assets via pubspec.yaml maakt bestanden toegankelijk via AssetBundle in runtime. Dit werkt voor afbeeldingen, JSON, tekstbestanden en alle andere bronnen. Flutter ondersteunt automatisch verschillende schermresoluties: als u images/2x/ en images/3x/ plaatst, selecteert Flutter de juiste versie van de afbeelding op basis van de device pixel ratio van het apparaat. Hiervoor volstaat het om in assets alleen de hoofdmap images/ op te geven.

Aangepaste lettertypen worden toegevoegd via de sectie fonts met opgave van family en een lijst van lettertypen. Na het wijzigen van pubspec.yaml moet flutter pub get worden uitgevoerd om de instellingen toe te passen. Lettertypen kunnen zowel globaal in het MaterialApp-thema als lokaal in specifieke widgets worden gebruikt. Voor elk lettertype kan weight (100-900) en style (normal, italic) worden opgegeven, waardoor Flutter het juiste lettertypebestand kan selecteren bij gebruik van FontWeight en FontStyle in de code.

Beheer van afhankelijkheden en versies

pub ondersteunt verschillende manieren om bronnen van afhankelijkheden op te geven: pub.dev, Git-repository's, lokale paden en privé-repository's. De keuze van de bron hangt af van de ontwikkelingsfase: voor stabiele versies wordt pub.dev gebruikt, voor forks en aangepaste wijzigingen — Git, voor parallel ontwikkelde bibliotheken — een lokaal pad.

De operator ^version betekent een compatibele versie: ^1.2.0 staat versies >=1.2.0 en <2.0.0 toe. Dit is analoog aan de operator ~> in CocoaPods en de Caret-operator in npm. pub lost automatisch Dependency Hell op via een SAT-solver-algoritme dat een combinatie van versies vindt die aan alle beperkingen voldoet. Als een dergelijke combinatie niet bestaat, geeft pub een gedetailleerde melding met de conflicterende pakketten.

Het bestand pubspec.lock legt de exacte versies van afhankelijkheden vast. Het moet in het versiebeheersysteem worden bewaard voor apps om reproduceerbare builds op alle machines van het team te garanderen. Voor bibliotheken wordt pubspec.lock niet in de repository opgenomen, zodat bibliotheekgebruikers deze met verschillende versies van afhankelijkheden kunnen gebruiken. De opdracht flutter pub upgrade werkt alle afhankelijkheden bij volgens de beperkingen van pubspec.yaml, en flutter pub outdated laat zien welke pakketten kunnen worden bijgewerkt.

Configuratie van build en publicatie

Voor publicatie van de app op pub.dev worden instellingen opgegeven in de sectie publish_to. De waarde 'none' voorkomt onbedoelde publicatie van het pakket, wat belangrijk is voor interne of niet-openbare projecten. Als publish_to ontbreekt, probeert pub het pakket op de standaard pub.dev te publiceren, wat kan leiden tot ongewenste codelekkage.

De sectie flutter bevat platformparameters: generate voor automatische generatie van platformbestanden en deferred-components voor modulair laden van functionaliteit. De parameter generate: true zorgt ervoor dat Flutter automatisch platformprojecten (iOS, Android, Web) aanmaakt en bijwerkt bij het toevoegen van nieuwe platforms via flutter create --platforms. Zonder deze parameter kan de structuur van platformmappen desynchroniseren met pubspec.yaml.

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

De sectie platforms stelt de doelplatforms voor het pakket in. Voor apps wordt deze automatisch bepaald bij het toevoegen van ondersteuning voor een specifiek platform via flutter create. Platforms kunnen handmatig worden toegevoegd en verwijderd via bewerking van pubspec.yaml. Deferred Components maken het mogelijk delen van de app op aanvraag te laden, waardoor de installatiegrootte afneemt — dit is vooral relevant voor games en apps met veel zelden gebruikte inhoud.

Bij publicatie van een pakket controleert pub alle velden van pubspec.yaml op conformiteit met de vereisten van de repository. Het ontbreken van verplichte velden name, version en description leidt tot afwijzing van publicatie. Daarnaast wordt de geldigheid van de licentie, de aanwezigheid van README.md en CHANGELOG.md gecontroleerd. Pakketten met fouten van de codeanalysator (dart analyze) doorstaan de validatie ook niet. Na succesvolle publicatie wordt het pakket binnen enkele minuten beschikbaar op pub.dev.

De sectie dependency_overrides maakt het mogelijk de versie van een pakket te forceren, waarbij beperkingen uit transitieve afhankelijkheden worden genegeerd. Dit is een krachtig maar gevaarlijk mechanisme: bij verkeerd gebruik kan het leiden tot incompatibiliteit van bibliotheken. Gebruik dependency_overrides alleen tijdelijk voor het oplossen van conflicten of testen van nieuwe versies. Nadat de belangrijkste afhankelijkheden zijn hersteld, moet de override worden verwijderd om de afhankelijkheidsgraaf van het project op lange termijn niet te verstoren.

De sectie executables in pubspec.yaml maakt het mogelijk uitvoerbare scripts op te geven die pub installeert in PATH bij activatie van het pakket. Dit is handig voor CLI-tools geschreven in Dart, zoals build_runner of dart_code_metrics. De opdracht dart pub global activeert het pakket globaal, waardoor de in executables opgegeven scripts beschikbaar worden vanuit de terminal. Voor apps worden executables meestal niet gebruikt, omdat het toegangspunt wordt bepaald via main in lib/main.dart.