pub: concetti chiave, gestore di pacchetti Dart e pubspec.yaml

Cos'è pub?

pub (Package Universal Browser) — un gestore di pacchetti integrato fornito con Dart SDK. Gestisce librerie esterne, risolve conflitti di versione, scarica dipendenze transitive e memorizza nella cache i pacchetti localmente. Nell'ecosistema Flutter, pub è utilizzato come strumento principale per collegare plugin di navigazione, client HTTP, gestori di stato e altri componenti.

Le funzioni principali di pub includono: installazione delle dipendenze dal registro pub.dev, percorsi locali (dipendenze path) e repository git; risoluzione delle versioni secondo le regole del versionamento semantico; memorizzazione nella cache dei pacchetti scaricati in una directory di sistema; pubblicazione di pacchetti propri nel registro pubblico. Tutte queste operazioni sono disponibili tramite il comando CLI dart pub o il suo equivalente flutter pub.

L'architettura di pub si basa su un grafo chiuso di dipendenze: il gestore costruisce un albero in cui ogni pacchetto appare esattamente una volta. Se due librerie richiedono versioni diverse dello stesso pacchetto, pub cerca di trovare un intervallo compatibile o segnala un errore di conflitto. Questo differisce dall'approccio di npm, che consente più versioni dello stesso pacchetto in diversi nodi dell'albero.

Struttura di pubspec.yaml

Il file pubspec.yaml — il file di configurazione centrale di qualsiasi progetto Dart o Flutter. È scritto in formato YAML e contiene metadati, dipendenze, configurazione di build e vincoli SDK. Di seguito un esempio tipico per un'applicazione Flutter:

name: my_app
description: Esempio di app 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/

Campi chiave di pubspec.yaml: name — nome univoco del pacchetto (solo latino, trattino basso, cifre); description — breve descrizione (obbligatoria per la pubblicazione); version — versione semantica con numero di build opzionale dopo il segno più; environment — versioni minime di Dart SDK e Flutter SDK; dependencies — dipendenze principali dell'applicazione; dev_dependencies — dipendenze solo per sviluppo e test; flutter — sezione di configurazione Flutter (asset, font, plugin).

Il campo publish_to controlla la disponibilità di pubblicazione: il valore none proibisce la pubblicazione (tipico per applicazioni), il valore predefinito — https://pub.dev. Il campo dependency_overrides consente di sovrascrivere forzatamente la versione di un pacchetto in situazioni di conflitto — usare con cautela, solo come soluzione temporanea.

Dipendenze e loro tipi

pub supporta quattro tipi di dipendenze, ciascuno specificato con una propria sintassi all'interno di pubspec.yaml:

Ospitate (hosted)

Il tipo standard — il pacchetto viene scaricato dal registro pub.dev o da un altro registro compatibile. Si specifica il nome del pacchetto e la versione. Esempio: http: ^1.1.0 scaricherà l'ultima versione compatibile dall'intervallo >=1.1.0 e <2.0.0 secondo le regole del caret versioning.

Dipendenze SDK

Utilizzate per includere Flutter SDK o Dart SDK. Sintassi: flutter: sdk: flutter. Il pacchetto viene prelevato dall'installazione locale di Flutter SDK, non dal registro. Le dipendenze SDK non sono versionate — la loro versione è determinata dalla versione di Flutter attualmente installata.

Path

Puntano a una directory locale contenente un pacchetto. Utile durante lo sviluppo di una libreria e i test senza pubblicazione. Sintassi:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Le dipendenze path non vengono fissate in pubspec.lock — ogni aggiornamento viene risolto nuovamente dal percorso specificato.

Git

Consentono di includere un pacchetto direttamente da un repository git. Branch, tag e commit sono supportati:

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

Le dipendenze git sono comode per fork, correzioni non pubblicate o lavoro su Pull Request. Si consiglia di specificare un tag o commit specifico invece di un branch per evitare modifiche impreviste durante la build.

Versionamento e intervalli

pub segue rigorosamente il Semantic Versioning 2.0: formato MAJOR.MINOR.PATCH, dove MAJOR — modifiche incompatibili, MINOR — aggiunte retrocompatibili, PATCH — correzioni retrocompatibili. Basandosi su questo schema, pub determina la compatibilità dei pacchetti e risolve i conflitti.

Tre operatori principali vengono utilizzati per specificare le versioni in pubspec.yaml:

• Caret (^) — ^1.2.3 equivale a >=1.2.3 e <2.0.0. L'operatore più comune, poiché implica compatibilità all'interno della versione major. Per pacchetti con versione major 0 (zero) — ^0.1.2 significa >=0.1.2 e <0.2.0, seguendo le regole SemVer per versioni instabili.
• Tilde (~) — ~1.2.3 equivale a >=1.2.3 e <1.3.0. Fissa la versione minor, consentendo solo aggiornamenti patch. Usato meno frequentemente, principalmente quando è nota un'incompatibilità a livello di versione minor.
• Intervallo esatto — >=1.2.0 <2.0.0 — notazione esplicita che offre controllo completo. Utile per vincoli complessi, ad esempio quando si utilizzano più versioni di dipendenze transitive.

Dopo aver eseguito dart pub get, pub genera un file pubspec.lock che fissa le versioni esatte di tutti i pacchetti risolti (diretti e transitivi). Questo file deve essere incluso nel controllo versione per garantire build riproducibili su tutte le macchine. Quando si esegue dart pub upgrade, il file lock viene aggiornato alle ultime versioni compatibili entro i vincoli specificati.

Un errore di conflitto di dipendenza si verifica quando due pacchetti richiedono intervalli non sovrapposti della stessa dipendenza. pub segnala quali pacchetti sono in conflitto e perché. Soluzione: aggiornare uno dei pacchetti in conflitto a una versione compatibile, utilizzare dependency_overrides (misura temporanea) o passare a un pacchetto alternativo.

Comandi principali di pub

Tutte le operazioni di pub vengono eseguite tramite un'interfaccia CLI unificata. Dart SDK utilizza il comando dart pub, Flutter SDK utilizza l'equivalente flutter pub (tiene conto inoltre delle dipendenze e dei plugin Flutter SDK). Di seguito i comandi chiave:

• dart pub get — scarica tutte le dipendenze specificate in pubspec.yaml, risolve le versioni e crea/aggiorna pubspec.lock. Eseguire al primo clone di un progetto o dopo aver modificato le dipendenze.
• dart pub upgrade — aggiorna tutte le dipendenze alle ultime versioni entro i vincoli di pubspec.yaml e sovrascrive pubspec.lock. È possibile aggiornare un singolo pacchetto: dart pub upgrade http.
• dart pub add <package> — aggiunge una nuova dipendenza a pubspec.yaml ed esegue immediatamente pub get. Esempio: dart pub add dio aggiunge l'ultima versione del pacchetto dio.
• dart pub remove <package> — rimuove una dipendenza da pubspec.yaml e riavvia la risoluzione del grafo.
• dart pub cache repair — ricarica tutti i pacchetti in cache. Aiuta quando la cache locale è danneggiata o si verificano errori di checksum.
• dart pub deps — stampa l'albero delle dipendenze in un formato di testo comodo. Utile per analizzare dipendenze transitive e trovare duplicati.
• dart pub publish — pubblica il pacchetto corrente su pub.dev. Prima della pubblicazione, convalida pubspec.yaml, la licenza e la descrizione.
• dart pub outdated — mostra un elenco di dipendenze obsolete indicando la versione corrente, desiderata e l'ultima disponibile. Analogo a npm outdated.

Tutti i comandi sono disponibili anche in forma abbreviata dart pub get come dart pub g (non tutte le abbreviazioni). Nei progetti Flutter, i comandi sono preceduti da flutter: flutter pub get, flutter pub add e così via. La versione Flutter verifica inoltre la compatibilità dei plugin con la piattaforma di destinazione.

Pubblicazione su pub.dev

pub.dev — il registro centrale dei pacchetti dell'ecosistema Dart e Flutter. A gennaio 2025, oltre 50.000 pacchetti sono stati pubblicati lì, con oltre 10 miliardi di download totali. Ogni pacchetto ha una pagina con descrizione, documentazione, punteggi di popolarità, punteggi Pub Points e versioni.

Pub Points — un sistema automatizzato di valutazione della qualità del pacchetto da 0 a 130 punti. Considera: presenza di licenza, descrizione, esempi, compatibilità con l'ultima versione stabile di Dart, assenza di vulnerabilità, copertura dei test, correttezza della formattazione. Un punteggio alto aumenta la visibilità del pacchetto nella ricerca e la fiducia degli utenti.

Il processo di pubblicazione include diversi passaggi:

1. Verificare pubspec.yaml: assicurarsi che name, description, version, license siano presenti (si consiglia identificatore SPDX, ad esempio MIT).
2. Eseguire dart pub publish --dry-run — una simulazione senza invio al server, mostra tutti i file che saranno inclusi nel pacchetto e gli eventuali errori.
3. Autenticarsi tramite account Google alla prima pubblicazione: dart pub publish aprirà un browser per l'autenticazione OAuth.
4. Confermare la pubblicazione nel terminale. Dopo il caricamento riuscito, il pacchetto appare su pub.dev entro pochi minuti.

Regole importanti: solo i pacchetti con nome univoco possono essere pubblicati; una versione pubblicata non può essere eliminata (solo nascosta — dart pub unpublish — entro 7 giorni); per aggiornamenti importanti, seguire le regole del Semantic Versioning, non rompere l'API pubblica senza cambiare la versione major.