pubspec.yaml — cos'è, struttura e configurazione delle dipendenze in Flutter

Cos'è pubspec.yaml

pubspec.yaml è un file manifest in formato YAML che il gestore di pacchetti pub utilizza per gestire i progetti Dart e Flutter. Si trova nella radice del progetto e viene elaborato a ogni comando flutter pub get. A differenza di altre piattaforme dove la configurazione è sparsa su più file, Flutter utilizza un unico manifest centralizzato per tutte le esigenze.

Il file contiene metadati: nome del progetto, descrizione, versione, autore. Questi dati vengono utilizzati durante la pubblicazione di un pacchetto su pub.dev e durante la compilazione dell'applicazione per App Store e Google Play. Il campo description viene visualizzato nei risultati di ricerca dei pacchetti, quindi deve essere informativo e contenere parole chiave con cui altri sviluppatori possano trovare la libreria.

Senza un pubspec.yaml corretto, un progetto Flutter non può essere compilato. Errori di sintassi o un'indentazione errata causano un immediato fallimento della compilazione con un messaggio Error on line X. YAML è sensibile agli spazi bianchi: uno spazio extra modifica la struttura dei dati e le tabulazioni causano un errore di sintassi. Pertanto, durante la modifica manuale di pubspec.yaml, è importante utilizzare un editor con evidenziazione della sintassi YAML, come VS Code con l'estensione ufficiale Flutter.

Sezioni principali di pubspec.yaml

pubspec.yaml è composto da sezioni obbligatorie e opzionali. Ogni sezione è responsabile di un aspetto specifico della configurazione del progetto. L'ordine delle sezioni non è importante, ma per convenzione della comunità si segue la gerarchia: metadati, ambiente, dipendenze, risorse, piattaforme.

name e description

Il campo name imposta un identificatore unico del pacchetto in formato snake_case, composto solo da lettere latine minuscole, cifre e trattini bassi. Il campo description è un breve riepilogo del progetto fino a 180 caratteri, obbligatorio per la pubblicazione su pub.dev. La descrizione deve spiegare lo scopo del pacchetto senza ripetere il nome e contenere parole chiave per l'ottimizzazione della ricerca del repository.

name: my_flutter_app
description: App per la gestione delle attività con Flutter
publish_to: 'none'

version e environment

Il campo version utilizza il versionamento semantico major.minor.patch con un numero di build opzionale dopo il segno più (1.0.0+1). La sezione environment imposta le versioni minima e massima dell'SDK Dart e Flutter per garantire la compatibilità. Se una nuova versione dell'SDK contiene modifiche incompatibili con il codice del progetto, la compilazione si interrompe con un messaggio di errore chiaro.

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

dependencies e dev_dependencies

La sezione dependencies elenca i pacchetti necessari per il funzionamento dell'applicazione in fase di esecuzione. La sezione dev_dependencies contiene pacchetti per test, generazione di codice e sviluppo — non vengono inclusi nella build di rilascio. Separare le dipendenze è fondamentale per le prestazioni: ogni pacchetto in dependencies aumenta la dimensione finale dell'APK o IPA, così come il tempo di avvio dell'applicazione a causa dell'inizializzazione di librerie aggiuntive.

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

Configurazione di asset e font

La sezione flutter contiene sottosezioni per configurare risorse, font e parametri della piattaforma. Le risorse vengono collegate tramite un array paths che specifica file particolari o intere directory. Tutti i percorsi sono specificati relativamente alla radice del progetto, non relativamente a pubspec.yaml. Questa è una sfumatura importante che spesso crea confusione tra gli sviluppatori Flutter principianti.

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

Collegare gli asset tramite pubspec.yaml rende i file accessibili tramite AssetBundle in fase di esecuzione. Questo funziona per immagini, JSON, file di testo e qualsiasi altra risorsa. Flutter supporta automaticamente diverse risoluzioni dello schermo: se si aggiungono images/2x/ e images/3x/, Flutter selezionerà la versione appropriata dell'immagine in base al rapporto pixel del dispositivo. Per farlo, è sufficiente specificare in assets solo la cartella radice images/.

I font personalizzati vengono aggiunti tramite la sezione fonts con un nome di famiglia e un elenco di stili. Dopo aver modificato pubspec.yaml, è necessario eseguire flutter pub get per applicare le modifiche. I font possono essere utilizzati sia globalmente nel tema MaterialApp che localmente in widget specifici. Per ogni stile, è possibile specificare weight (100–900) e style (normal, italic), consentendo a Flutter di selezionare correttamente il file del font quando si utilizzano FontWeight e FontStyle nel codice.

Gestione delle dipendenze e delle versioni

pub supporta diversi modi per specificare le fonti delle dipendenze: pub.dev, repository Git, percorsi locali e repository privati. La scelta della fonte dipende dalla fase di sviluppo: per le versioni stabili si usa pub.dev, per fork e modifiche personalizzate — Git, per librerie in sviluppo parallelo — il percorso locale.

L'operatore ^version indica una versione compatibile: ^1.2.0 consente versioni >=1.2.0 e <2.0.0. Questo è analogo all'operatore ~> in CocoaPods e all'operatore Caret in npm. pub risolve automaticamente il Dependency Hell attraverso un algoritmo SAT solver che trova una combinazione di versioni che soddisfa tutti i vincoli. Se tale combinazione non esiste, pub visualizza un messaggio dettagliato indicando i pacchetti in conflitto.

Il file pubspec.lock fissa le versioni esatte delle dipendenze. Deve essere memorizzato nel sistema di controllo versione per le applicazioni, garantendo build riproducibili su tutte le macchine del team. Per le librerie, pubspec.lock non viene incluso nel repository, poiché gli utenti della libreria devono poterla utilizzare con diverse versioni delle dipendenze. Il comando flutter pub upgrade aggiorna tutte le dipendenze secondo i vincoli di pubspec.yaml, mentre flutter pub outdated mostra quali pacchetti possono essere aggiornati.

Configurazione di compilazione e pubblicazione

Per pubblicare un'applicazione su pub.dev, le impostazioni vengono specificate nella sezione publish_to. Il valore 'none' impedisce la pubblicazione accidentale del pacchetto, importante per progetti interni o non pubblici. Se publish_to è assente, pub tenta di pubblicare il pacchetto su pub.dev predefinito, il che può portare a fughe di codice indesiderate.

La sezione flutter include parametri della piattaforma: generate per la generazione automatica di file della piattaforma, e deferred-components per il caricamento modulare delle funzionalità. Il parametro generate: true forza Flutter a creare e aggiornare automaticamente i progetti della piattaforma (iOS, Android, Web) quando si aggiungono nuove piattaforme tramite flutter create --platforms. Senza questo parametro, la struttura delle cartelle della piattaforma potrebbe desincronizzarsi da pubspec.yaml.

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

La sezione platforms imposta le piattaforme target per il pacchetto. Per le applicazioni, viene determinata automaticamente quando si aggiunge il supporto per una piattaforma specifica tramite flutter create. Le piattaforme possono essere aggiunte e rimosse manualmente modificando pubspec.yaml. I Deferred Components consentono di caricare parti dell'applicazione su richiesta, riducendo le dimensioni di installazione — questo è particolarmente rilevante per giochi e applicazioni con grandi quantità di contenuti usati raramente.

Durante la pubblicazione di un pacchetto, pub controlla che tutti i campi di pubspec.yaml siano conformi ai requisiti del repository. L'assenza dei campi obbligatori name, version e description porta al rifiuto della pubblicazione. Inoltre, vengono verificati la correttezza della licenza e la presenza di README.md e CHANGELOG.md. I pacchetti con errori dell'analizzatore di codice (dart analyze) falliscono anche la validazione. Dopo la pubblicazione riuscita, il pacchetto diventa disponibile su pub.dev entro pochi minuti.

La sezione dependency_overrides consente di forzare una versione specifica di un pacchetto, ignorando i vincoli delle dipendenze transitive. Questo è un meccanismo potente ma pericoloso: se usato in modo errato, può portare a incompatibilità tra librerie. Utilizza dependency_overrides solo temporaneamente per risolvere conflitti o testare nuove versioni. Dopo aver corretto le dipendenze principali, l'override dovrebbe essere rimosso per non rompere il grafo delle dipendenze del progetto a lungo termine.

La sezione executables in pubspec.yaml consente di specificare script eseguibili che pub installa in PATH durante l'attivazione di un pacchetto. Questo è utile per strumenti CLI scritti in Dart, come build_runner o dart_code_metrics. Il comando dart pub global activate installa il pacchetto globalmente, rendendo gli script specificati in executables accessibili dal terminale. Per le applicazioni, executables di solito non viene utilizzato, poiché il punto di ingresso è definito tramite main in lib/main.dart.