pub: kernbegrippen, Dart-pakketbeheerder en pubspec.yaml

Wat is pub?

pub (Package Universal Browser) — de ingebouwde pakketbeheerder die bij Dart SDK wordt geleverd. Het beheert externe bibliotheken, lost versieconflicten op, downloadt transitieve afhankelijkheden en cacht pakketten lokaal. In het Flutter-ecosysteem wordt pub gebruikt als het belangrijkste hulpmiddel voor het aansluiten van navigatie-plugins, HTTP-clients, state-managers en andere componenten.

De belangrijkste functies van pub zijn: installeren van afhankelijkheden vanuit het pub.dev-register, lokale paden (path-afhankelijkheden) en git-repository's; versies oplossen volgens de regels van semantische versiebeheer; cachen van gedownloade pakketten in de systeemmap; publiceren van eigen pakketten in het openbare register. Al deze bewerkingen zijn beschikbaar via het CLI-commando dart pub of het equivalente flutter pub.

De architectuur van pub is gebaseerd op een gesloten afhankelijkheidsgraaf: de beheerder bouwt een boom waarin elk pakket precies één keer voorkomt. Als twee bibliotheken verschillende versies van hetzelfde pakket nodig hebben, probeert pub een compatibel bereik te vinden of meldt een conflictfout. Dit verschilt van de aanpak van npm, waar meerdere versies van hetzelfde pakket in verschillende knooppunten van de boom zijn toegestaan.

Structuur van pubspec.yaml

Het bestand pubspec.yaml — het centrale configuratiebestand van elk Dart- of Flutter-project. Het is geschreven in YAML-formaat en bevat metadata, afhankelijkheden, buildconfiguratie en SDK-beperkingen. Hieronder staat een typisch voorbeeld voor een Flutter-applicatie:

name: my_app
description: Voorbeeld van een Flutter-app
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/

Belangrijke velden van pubspec.yaml: name — unieke naam van het pakket (alleen Latijnse letters, underscore, cijfers); description — korte beschrijving (verplicht voor publicatie); version — semantische versie met optioneel buildnummer na een plusteken; environment — minimale versies van Dart SDK en Flutter SDK; dependencies — de belangrijkste afhankelijkheden van de applicatie; dev_dependencies — afhankelijkheden alleen voor ontwikkeling en tests; flutter — configuratiesectie voor Flutter (assets, fonts, plugins).

Het veld publish_to regelt de beschikbaarheid van publicatie: de waarde none verbiedt publicatie (typisch voor applicaties), de standaardwaarde is https://pub.dev. Het veld dependency_overrides maakt het mogelijk om de versie van een pakket in conflictsituaties geforceerd te overschrijven — met voorzichtigheid gebruiken, alleen als tijdelijke oplossing.

Afhankelijkheden en hun types

pub ondersteunt vier soorten afhankelijkheden, elk met hun eigen syntaxis in pubspec.yaml:

Register (hosted)

Standaardtype — het pakket wordt gedownload uit het register pub.dev of een ander compatibel register. De pakketnaam en versie worden opgegeven. Voorbeeld: http: ^1.1.0 downloadt de nieuwste compatibele versie uit het bereik >=1.1.0 en <2.0.0 volgens de regels van caret-versiebeheer.

SDK-afhankelijkheden

Worden gebruikt om Flutter SDK of Dart SDK aan te sluiten. Syntaxis: flutter: sdk: flutter. Het pakket wordt uit de lokale installatie van Flutter SDK gehaald, niet uit het register. SDK-afhankelijkheden worden niet van versies voorzien — hun versie wordt bepaald door de huidig geïnstalleerde Flutter-versie.

Pad (path)

Verwijst naar een lokale map met het pakket. Handig bij het ontwikkelen van een bibliotheek en testen zonder publicatie. Syntaxis:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Pad-afhankelijkheden worden niet vastgelegd in pubspec.lock — elke update wordt opnieuw opgelost vanaf het opgegeven pad.

Git-afhankelijkheden

Maakt het mogelijk om een pakket rechtstreeks vanuit een git-repository aan te sluiten. Takken, tags en commits worden ondersteund:

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

Git-afhankelijkheden zijn handig voor forks, niet-gepubliceerde correcties of werk aan Pull Requests. Het wordt aanbevolen om een specifieke tag of commit op te geven in plaats van een tak, om onverwachte wijzigingen bij het bouwen te voorkomen.

Versiebeheer en bereiken

pub volgt strikt Semantic Versioning 2.0: het formaat MAJOR.MINOR.PATCH, waarbij MAJOR — incompatibele wijzigingen, MINOR — achterwaarts compatibele toevoegingen, PATCH — achterwaarts compatibele correcties. Op basis van dit schema bepaalt pub de compatibiliteit van pakketten en lost conflicten op.

Voor het specificeren van versies worden drie belangrijke operatoren gebruikt in pubspec.yaml:

• Caret (^) — ^1.2.3 is equivalent aan >=1.2.3 en <2.0.0. De meest gebruikte operator, omdat het compatibiliteit binnen de major-versie veronderstelt. Voor pakketten met major-versie 0 (nul) — ^0.1.2 betekent >=0.1.2 en <0.2.0, wat overeenkomt met SemVer-regels voor onstabiele versies.
• Tilde (~) — ~1.2.3 is equivalent aan >=1.2.3 en <1.3.0. Fixeert de minor-versie en staat alleen patch-updates toe. Minder gebruikt, vooral wanneer incompatibiliteit op minor-niveau bekend is.
• Exact bereik — >=1.2.0 <2.0.0 — expliciete notatie die volledige controle geeft. Handig voor complexe beperkingen, bijvoorbeeld bij het gebruik van meerdere versies van transitieve afhankelijkheden.

Na het uitvoeren van dart pub get genereert pub het bestand pubspec.lock, dat de exacte versies van alle opgeloste pakketten (direct en transitief) vastlegt. Dit bestand moet in het versiebeheersysteem worden opgenomen om reproduceerbare builds op alle machines te garanderen. Bij het uitvoeren van dart pub upgrade wordt het lock-bestand bijgewerkt naar de nieuwste compatibele versies binnen de gestelde beperkingen.

De fout dependency conflict treedt op wanneer twee pakketten niet-overlappende bereiken van dezelfde afhankelijkheid vereisen. pub meldt welke pakketten in conflict zijn en om welke reden. Oplossing: werk een van de conflicterende pakketten bij naar een compatibele versie, gebruik dependency_overrides (tijdelijke maatregel) of vervang het pakket door een alternatief.

Basiscommando's van pub

Alle pub-bewerkingen worden uitgevoerd via een uniforme CLI-interface. In Dart SDK wordt het commando dart pub gebruikt, in Flutter SDK — het equivalente flutter pub (houdt ook rekening met Flutter SDK-afhankelijkheden en plugins). Hieronder staan de belangrijkste commando's:

• dart pub get — downloadt alle afhankelijkheden die in pubspec.yaml zijn gespecificeerd, lost versies op en maakt/werkt pubspec.lock bij. Wordt uitgevoerd bij het eerste klonen van het project of na het wijzigen van afhankelijkheden.
• dart pub upgrade — werkt alle afhankelijkheden bij naar de nieuwste versies binnen de beperkingen van pubspec.yaml en overschrijft pubspec.lock. Kan een afzonderlijk pakket bijwerken: dart pub upgrade http.
• dart pub add <package> — voegt een nieuwe afhankelijkheid toe aan pubspec.yaml en voert onmiddellijk pub get uit. Voorbeeld: dart pub add dio voegt de nieuwste versie van pakket dio toe.
• dart pub remove <package> — verwijdert de afhankelijkheid uit pubspec.yaml en herstart het oplossen van de graaf.
• dart pub cache repair — laadt alle gecachte pakketten opnieuw. Helpt bij beschadiging van de lokale cache of fouten in controlesommen.
• dart pub deps — toont de afhankelijkheidsboom in een leesbaar tekstformaat. Handig voor analyse van transitieve afhankelijkheden en het vinden van duplicaties.
• dart pub publish — publiceert het huidige pakket op pub.dev. Controleert voor publicatie de juistheid van pubspec.yaml, licentie en beschrijving.
• dart pub outdated — toont een lijst van verouderde afhankelijkheden met de huidige, gewenste en laatst beschikbare versie. Analoog aan npm outdated.

Alle commando's zijn ook beschikbaar in verkorte vorm: dart pub get als dart pub g (niet alle verkortingen). In Flutter-projecten wordt het voorvoegsel flutter aan pub-commando's toegevoegd: flutter pub get, flutter pub add enzovoort. De Flutter-versie controleert ook de compatibiliteit van plugins met het doelplatform.

Publiceren op pub.dev

pub.dev — het centrale pakketregister van het Dart- en Flutter-ecosysteem. In januari 2025 waren daar meer dan 50.000 pakketten gepubliceerd, in totaal meer dan 10 miljard keer gedownload. Elk pakket heeft een pagina met beschrijving, documentatie, populariteitsbeoordelingen (Popularity), Pub Points-scores en versies.

Pub Points — een automatisch systeem voor het beoordelen van de pakketkwaliteit van 0 tot 130 punten. Er wordt rekening gehouden met: aanwezigheid van licentie, beschrijving, voorbeelden, compatibiliteit met de laatste stabiele Dart-versie, afwezigheid van kwetsbaarheden, testdekking, correctheid van opmaak. Een hoge score verhoogt de zichtbaarheid van het pakket in zoekresultaten en het vertrouwen van gebruikers.

Het publicatieproces omvat verschillende stappen:

1. Controleer pubspec.yaml: aanwezigheid van name, description, version, license (aanbevolen om een SPDX-identificatie op te geven, bijv. MIT).
2. Voer dart pub publish --dry-run uit — simulatie van publicatie zonder verzending naar de server, toont alle bestanden die in het pakket worden opgenomen en mogelijke fouten.
3. Autoriseer via een Google-account bij de eerste publicatie: dart pub publish opent de browser voor OAuth-authenticatie.
4. Bevestig de publicatie in de terminal. Na succesvolle verzending verschijnt het pakket binnen enkele minuten op pub.dev.

Belangrijke regels: alleen pakketten met een unieke naam kunnen worden gepubliceerd; een eenmaal gepubliceerde versie kan niet worden verwijderd (alleen verborgen — dart pub unpublish — binnen 7 dagen); voor grote updates moeten de regels van Semantic Versioning worden gevolgd, de openbare API mag niet worden verbroken zonder wijziging van de major-versie.