pub: concepts clés, gestionnaire de paquets Dart et pubspec.yaml

Qu'est-ce que pub ?

pub (Package Universal Browser) — un gestionnaire de paquets intégré qui accompagne le Dart SDK. Il gère les bibliothèques externes, résout les conflits de versions, télécharge les dépendances transitives et met en cache les paquets localement. Dans l'écosystème Flutter, pub est utilisé comme outil principal pour connecter les plugins de navigation, les clients HTTP, les gestionnaires d'état et autres composants.

Les fonctions principales de pub incluent : l'installation de dépendances depuis le registre pub.dev, les chemins locaux (dépendances path) et les dépôts git ; la résolution de versions selon les règles du versionnement sémantique ; la mise en cache des paquets téléchargés dans un répertoire système ; la publication de vos propres paquets dans le registre public. Toutes ces opérations sont disponibles via la commande CLI dart pub ou son équivalent flutter pub.

L'architecture de pub est basée sur un graphe fermé de dépendances : le gestionnaire construit un arbre où chaque paquet apparaît exactement une fois. Si deux bibliothèques nécessitent des versions différentes du même paquet, pub essaie de trouver une plage compatible ou signale une erreur de conflit. Cela diffère de l'approche de npm, qui autorise plusieurs versions du même paquet dans différents nœuds de l'arbre.

Structure de pubspec.yaml

Le fichier pubspec.yaml — le fichier de configuration central de tout projet Dart ou Flutter. Il est écrit au format YAML et contient les métadonnées, les dépendances, la configuration de build et les contraintes SDK. Voici un exemple typique pour une application Flutter :

name: my_app
description: Exemple d'application 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/

Champs clés de pubspec.yaml : name — nom unique du paquet (latin, tiret bas, chiffres uniquement) ; description — brève description (obligatoire pour publier) ; version — version sémantique avec numéro de build optionnel après le signe plus ; environment — versions minimales de Dart SDK et Flutter SDK ; dependencies — dépendances principales de l'application ; dev_dependencies — dépendances uniquement pour le développement et les tests ; flutter — section de configuration Flutter (assets, polices, plugins).

Le champ publish_to contrôle la disponibilité de la publication : la valeur none interdit la publication (typique pour les applications), la valeur par défaut — https://pub.dev. Le champ dependency_overrides permet de forcer le remplacement d'une version de paquet en situation de conflit — à utiliser avec précaution, uniquement comme solution temporaire.

Dépendances et leurs types

pub prend en charge quatre types de dépendances, chacun spécifié avec sa propre syntaxe dans pubspec.yaml :

Hébergées (hosted)

Le type standard — le paquet est téléchargé depuis le registre pub.dev ou un autre registre compatible. On spécifie le nom du paquet et la version. Exemple : http: ^1.1.0 téléchargera la dernière version compatible de la plage >=1.1.0 et <2.0.0 selon les règles du caret versioning.

Dépendances SDK

Utilisées pour inclure Flutter SDK ou Dart SDK. Syntaxe : flutter: sdk: flutter. Le paquet est pris depuis l'installation locale de Flutter SDK, pas depuis le registre. Les dépendances SDK ne sont pas versionnées — leur version est déterminée par la version actuelle de Flutter installée.

Path

Pointent vers un répertoire local contenant un paquet. Utile lors du développement d'une bibliothèque et des tests sans publication. Syntaxe :

dependencies:
  my_local_lib:
    path: ../my_local_lib

Les dépendances path ne sont pas figées dans pubspec.lock — chaque mise à jour est résolue à nouveau depuis le chemin spécifié.

Git

Permettent d'inclure un paquet directement depuis un dépôt git. Les branches, tags et commits sont pris en charge :

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

Les dépendances git sont pratiques pour les forks, les correctifs non publiés ou le travail sur des Pull Requests. Il est recommandé de spécifier un tag ou un commit précis plutôt qu'une branche pour éviter des changements inattendus lors du build.

Versionnement et plages

pub suit strictement le Semantic Versioning 2.0 : format MAJOR.MINOR.PATCH, où MAJOR — changements incompatibles, MINOR — ajouts rétrocompatibles, PATCH — corrections rétrocompatibles. Sur la base de ce schéma, pub détermine la compatibilité des paquets et résout les conflits.

Trois opérateurs principaux sont utilisés pour spécifier les versions dans pubspec.yaml :

• Caret (^) — ^1.2.3 équivaut à >=1.2.3 et <2.0.0. L'opérateur le plus courant, car il implique une compatibilité dans la version majeure. Pour les paquets avec version majeure 0 (zéro) — ^0.1.2 signifie >=0.1.2 et <0.2.0, suivant les règles SemVer pour les versions instables.
• Tilde (~) — ~1.2.3 équivaut à >=1.2.3 et <1.3.0. Fige la version mineure, n'autorisant que les mises à jour patch. Moins utilisé, principalement quand une incompatibilité au niveau de la version mineure est connue.
• Plage exacte — >=1.2.0 <2.0.0 — notation explicite offrant un contrôle total. Utile pour des contraintes complexes, par exemple lors de l'utilisation de plusieurs versions de dépendances transitives.

Après avoir exécuté dart pub get, pub génère un fichier pubspec.lock qui fige les versions exactes de tous les paquets résolus (directs et transitifs). Ce fichier doit être inclus dans le contrôle de version pour garantir des builds reproductibles sur toutes les machines. Lors de l'exécution de dart pub upgrade, le fichier lock est mis à jour vers les dernières versions compatibles dans les contraintes spécifiées.

Une erreur de dependency conflict se produit lorsque deux paquets nécessitent des plages non chevauchantes de la même dépendance. pub signale quels paquets sont en conflit et pourquoi. Solution : mettre à jour l'un des paquets en conflit vers une version compatible, utiliser dependency_overrides (mesure temporaire) ou passer à un paquet alternatif.

Commandes principales de pub

Toutes les opérations de pub sont effectuées via une interface CLI unifiée. Dart SDK utilise la commande dart pub, Flutter SDK utilise l'équivalent flutter pub (prend en compte en plus les dépendances et plugins Flutter SDK). Voici les commandes clés :

• dart pub get — télécharge toutes les dépendances spécifiées dans pubspec.yaml, résout les versions et crée/met à jour pubspec.lock. Exécuter lors du premier clonage d'un projet ou après modification des dépendances.
• dart pub upgrade — met à jour toutes les dépendances vers les dernières versions dans les contraintes de pubspec.yaml et écrase pubspec.lock. Un paquet individuel peut être mis à jour : dart pub upgrade http.
• dart pub add <package> — ajoute une nouvelle dépendance à pubspec.yaml et exécute immédiatement pub get. Exemple : dart pub add dio ajoute la dernière version du paquet dio.
• dart pub remove <package> — supprime une dépendance de pubspec.yaml et relance la résolution du graphe.
• dart pub cache repair — recharge tous les paquets en cache. Utile en cas de corruption du cache local ou d'erreurs de somme de contrôle.
• dart pub deps — affiche l'arbre des dépendances dans un format texte pratique. Utile pour analyser les dépendances transitives et trouver les doublons.
• dart pub publish — publie le paquet actuel sur pub.dev. Avant la publication, valide le pubspec.yaml, la licence et la description.
• dart pub outdated — affiche une liste des dépendances obsolètes avec la version actuelle, souhaitée et la dernière disponible. Analogue à npm outdated.

Toutes les commandes sont également disponibles sous forme abrégée dart pub get en dart pub g (pas toutes les abréviations). Dans les projets Flutter, les commandes sont préfixées par flutter : flutter pub get, flutter pub add et ainsi de suite. La version Flutter vérifie en plus la compatibilité des plugins avec la plateforme cible.

Publication sur pub.dev

pub.dev — le registre central de paquets de l'écosystème Dart et Flutter. En janvier 2025, plus de 50 000 paquets y ont été publiés, avec plus de 10 milliards de téléchargements cumulés. Chaque paquet a une page avec description, documentation, scores de popularité, points Pub Points et versions.

Pub Points — un système automatisé d'évaluation de la qualité du paquet de 0 à 130 points. Il prend en compte : la présence d'une licence, la description, les exemples, la compatibilité avec la dernière version stable de Dart, l'absence de vulnérabilités, la couverture de tests, la correction du formatage. Un score élevé augmente la visibilité du paquet dans la recherche et la confiance des utilisateurs.

Le processus de publication comprend plusieurs étapes :

1. Vérifier pubspec.yaml : s'assurer que name, description, version, license sont présents (identifiant SPDX recommandé, par exemple MIT).
2. Exécuter dart pub publish --dry-run — une simulation sans envoi au serveur, affiche tous les fichiers qui seront inclus dans le paquet et les erreurs possibles.
3. S'authentifier via un compte Google lors de la première publication : dart pub publish ouvrira un navigateur pour l'authentification OAuth.
4. Confirmer la publication dans le terminal. Après un téléchargement réussi, le paquet apparaît sur pub.dev en quelques minutes.

Règles importantes : seuls les paquets avec un nom unique peuvent être publiés ; une version publiée ne peut pas être supprimée (uniquement masquée — dart pub unpublish — dans les 7 jours) ; pour les mises à jour majeures, suivre les règles du Semantic Versioning, ne pas casser l'API publique sans changer la version majeure.