pubspec.yaml — qu'est-ce que c'est, structure et configuration des dépendances dans Flutter

Qu'est-ce que pubspec.yaml

pubspec.yaml est un fichier manifeste au format YAML que le gestionnaire de paquets pub utilise pour gérer les projets Dart et Flutter. Il se trouve à la racine du projet et est traité à chaque commande flutter pub get. Contrairement à d'autres plates-formes où la configuration est répartie sur plusieurs fichiers, Flutter utilise un seul manifeste centralisé pour tous les besoins.

Le fichier contient des métadonnées : nom du projet, description, version, auteur. Ces données sont utilisées lors de la publication d'un paquet sur pub.dev et lors de la compilation de l'application pour l'App Store et Google Play. Le champ description s'affiche dans les résultats de recherche de paquets, il doit donc être informatif et contenir des mots-clés permettant à d'autres développeurs de trouver la bibliothèque.

Sans un pubspec.yaml correct, un projet Flutter ne peut pas être compilé. Les erreurs de syntaxe ou une indentation incorrecte entraînent un échec immédiat de la compilation avec un message Error on line X. YAML est sensible aux espaces blancs : un espace supplémentaire modifie la structure des données et les tabulations provoquent une erreur de syntaxe. Par conséquent, lors de l'édition manuelle de pubspec.yaml, il est important d'utiliser un éditeur avec surlignage de la syntaxe YAML, comme VS Code avec l'extension officielle Flutter.

Sections principales de pubspec.yaml

pubspec.yaml se compose de sections obligatoires et facultatives. Chaque section est responsable d'un aspect spécifique de la configuration du projet. L'ordre des sections n'a pas d'importance, mais par convention de la communauté, la hiérarchie suivante est respectée : métadonnées, environnement, dépendances, ressources, plates-formes.

name et description

Le champ name définit un identifiant unique du paquet au format snake_case, composé uniquement de lettres latines minuscules, de chiffres et de tirets bas. Le champ description est un bref résumé du projet de 180 caractères maximum, obligatoire pour la publication sur pub.dev. La description doit expliquer le but du paquet sans répéter le nom et contenir des mots-clés pour l'optimisation de la recherche du référentiel.

name: my_flutter_app
description: Application de gestion de tâches avec Flutter
publish_to: 'none'

version et environment

Le champ version utilise le versionnement sémantique major.minor.patch avec un numéro de build optionnel après le signe plus (1.0.0+1). La section environment définit les versions minimale et maximale du SDK Dart et Flutter pour garantir la compatibilité. Si une nouvelle version du SDK contient des modifications incompatibles avec le code du projet, la compilation s'interrompt avec un message d'erreur clair.

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

dependencies et dev_dependencies

La section dependencies répertorie les paquets nécessaires au fonctionnement de l'application lors de l'exécution. La section dev_dependencies contient des paquets pour les tests, la génération de code et le développement — ils ne sont pas inclus dans la version finale. La séparation des dépendances est essentielle pour les performances : chaque paquet dans dependencies augmente la taille de l'APK ou de l'IPA final, ainsi que le temps de démarrage de l'application en raison de l'initialisation de bibliothèques supplémentaires.

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

Configuration des assets et des polices

La section flutter contient des sous-sections pour configurer les ressources, les polices et les paramètres de plate-forme. Les ressources sont connectées via un tableau paths spécifiant des fichiers particuliers ou des répertoires entiers. Tous les chemins sont spécifiés par rapport à la racine du projet, pas par rapport à pubspec.yaml. C'est une nuance importante qui prête souvent à confusion chez les développeurs Flutter débutants.

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

La connexion des assets via pubspec.yaml rend les fichiers accessibles via AssetBundle lors de l'exécution. Cela fonctionne pour les images, JSON, fichiers texte et toute autre ressource. Flutter prend automatiquement en charge différentes résolutions d'écran : si vous ajoutez images/2x/ et images/3x/, Flutter sélectionnera la version d'image appropriée en fonction du rapport de pixels de l'appareil. Pour ce faire, il suffit de spécifier dans assets uniquement le dossier racine images/.

Les polices personnalisées sont ajoutées via la section fonts avec un nom de famille et une liste de styles. Après avoir modifié pubspec.yaml, vous devez exécuter flutter pub get pour appliquer les modifications. Les polices peuvent être utilisées à la fois globalement dans le thème MaterialApp et localement dans des widgets spécifiques. Pour chaque style, vous pouvez spécifier weight (100–900) et style (normal, italic), ce qui permet à Flutter de sélectionner correctement le fichier de police lors de l'utilisation de FontWeight et FontStyle dans le code.

Gestion des dépendances et des versions

pub prend en charge plusieurs façons de spécifier les sources des dépendances : pub.dev, les référentiels Git, les chemins locaux et les référentiels privés. Le choix de la source dépend de l'étape de développement : pour les versions stables, on utilise pub.dev, pour les forks et les modifications personnalisées — Git, pour les bibliothèques développées en parallèle — le chemin local.

L'opérateur ^version indique une version compatible : ^1.2.0 autorise les versions >=1.2.0 et <2.0.0. C'est analogue à l'opérateur ~> dans CocoaPods et à l'opérateur Caret dans npm. pub résout automatiquement l'enfer des dépendances via un algorithme SAT solver qui trouve une combinaison de versions satisfaisant toutes les contraintes. Si une telle combinaison n'existe pas, pub affiche un message détaillé indiquant les paquets en conflit.

Le fichier pubspec.lock fige les versions exactes des dépendances. Il doit être stocké dans le système de contrôle de version pour les applications, garantissant des builds reproductibles sur toutes les machines de l'équipe. Pour les bibliothèques, pubspec.lock n'est pas inclus dans le référentiel, car les utilisateurs de la bibliothèque doivent pouvoir l'utiliser avec différentes versions de dépendances. La commande flutter pub upgrade met à jour toutes les dépendances selon les contraintes de pubspec.yaml, tandis que flutter pub outdated affiche les paquets pouvant être mis à jour.

Configuration de la compilation et de la publication

Pour publier une application sur pub.dev, les paramètres sont spécifiés dans la section publish_to. La valeur 'none' empêche la publication accidentelle du paquet, ce qui est important pour les projets internes ou non publics. Si publish_to est absent, pub tente de publier le paquet sur pub.dev par défaut, ce qui peut entraîner une fuite de code indésirable.

La section flutter inclut des paramètres de plate-forme : generate pour la génération automatique de fichiers de plate-forme, et deferred-components pour le chargement modulaire de fonctionnalités. Le paramètre generate: true force Flutter à créer et mettre à jour automatiquement les projets de plate-forme (iOS, Android, Web) lors de l'ajout de nouvelles plates-formes via flutter create --platforms. Sans ce paramètre, la structure des dossiers de la plate-forme peut se désynchroniser de pubspec.yaml.

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

La section platforms définit les plates-formes cibles du paquet. Pour les applications, elle est déterminée automatiquement lors de l'ajout de prise en charge d'une plate-forme spécifique via flutter create. Les plates-formes peuvent être ajoutées et supprimées manuellement en modifiant pubspec.yaml. Les Deferred Components permettent de charger des parties de l'application à la demande, réduisant ainsi la taille d'installation — cela est particulièrement pertinent pour les jeux et les applications avec une grande quantité de contenu rarement utilisé.

Lors de la publication d'un paquet, pub vérifie que tous les champs de pubspec.yaml respectent les exigences du référentiel. L'absence des champs obligatoires name, version et description entraîne le rejet de la publication. De plus, l'exactitude de la licence et la présence de README.md et CHANGELOG.md sont vérifiées. Les paquets avec des erreurs de l'analyseur de code (dart analyze) échouent également à la validation. Après une publication réussie, le paquet est disponible sur pub.dev en quelques minutes.

La section dependency_overrides permet de forcer une version spécifique d'un paquet, en ignorant les contraintes des dépendances transitives. C'est un mécanisme puissant mais dangereux : s'il est utilisé incorrectement, il peut entraîner des incompatibilités entre bibliothèques. Utilisez dependency_overrides uniquement temporairement pour résoudre des conflits ou tester de nouvelles versions. Après avoir corrigé les dépendances principales, la substitution doit être supprimée pour ne pas casser le graphe de dépendances du projet à long terme.

La section executables dans pubspec.yaml permet de spécifier des scripts exécutables que pub installe dans le PATH lors de l'activation d'un paquet. Cela est utile pour les outils CLI écrits en Dart, comme build_runner ou dart_code_metrics. La commande dart pub global activate installe le paquet globalement, rendant les scripts spécifiés dans executables accessibles depuis le terminal. Pour les applications, executables n'est généralement pas utilisé, car le point d'entrée est défini via main dans lib/main.dart.