Aggiungere un pacchetto da pub.dev al tuo progetto Flutter

Partiamo da un progetto pulito. Apri il terminale e crea una nuova app:

flutter create demo_pacchetti
cd demo_pacchetti

Nella radice del progetto trovi il file pubspec.yaml: è la "carta d'identità" dell'app. Qui si dichiarano nome, versione, asset, font e soprattutto le dipendenze, cioè i pacchetti esterni che vuoi usare.

Le due sezioni che ci interessano sono:

• dependencies: pacchetti che finiscono nell'app pubblicata (es. http, google_fonts).
• dev_dependencies: pacchetti usati solo in fase di sviluppo (es. flutter_lints, generatori di codice). Non vengono inclusi nell'app finale.

⚠️ Attenzione: YAML è sensibile all'indentazione. Si usano spazi (mai tab) e ogni dipendenza va rientrata di 2 spazi sotto dependencies:.

name: demo_pacchetti
description: "Progetto di esempio per imparare a usare i pacchetti."
publish_to: 'none'
version: 1.0.0+1

environment:
  sdk: ^3.5.0

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.8

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^4.0.0

flutter:
  uses-material-design: true

Vai su pub.dev e cerca google fonts. Prima di installare qualsiasi libreria, impara a valutarla: non tutti i pacchetti sono mantenuti bene.

Cosa guardare nella pagina del pacchetto:

1. Likes, Pub Points e Popularity: i Pub Points (max 160) misurano qualità formale (documentazione, analisi statica, null safety, supporto piattaforme).
2. Badge "Dart 3 compatible": indica che il pacchetto funziona con le versioni moderne di Dart.
3. Piattaforme supportate: Android, iOS, Web, Windows, macOS, Linux. Se sviluppi per il web e il pacchetto non lo supporta, cerca un'alternativa.
4. Data dell'ultima pubblicazione: un pacchetto fermo da 3 anni è un campanello d'allarme.
5. Tab "Installing": contiene il comando esatto e la riga da mettere nel pubspec.
6. Tab "Example" e "Readme": codice pronto da copiare per il primo test.
7. Publisher verificato (es. flutter.dev, google.dev, baseflow.com): grande garanzia di manutenzione.

💡 Suggerimento: se due pacchetti fanno la stessa cosa, scegli quello con più like e aggiornato di recente.

Il modo più semplice e sicuro per aggiungere una dipendenza è il comando flutter pub add: scrive da solo la riga corretta nel pubspec.yaml con la versione più recente e scarica il pacchetto.

Esegui nella cartella del progetto:

flutter pub add google_fonts

In alternativa puoi scrivere a mano la dipendenza nel pubspec.yaml e poi lanciare flutter pub get (in VS Code il download parte in automatico al salvataggio del file).

Per un pacchetto di sviluppo si usa invece:

flutter pub add dev:build_runner

Dopo l'installazione compare (o si aggiorna) il file pubspec.lock: registra le versioni esatte usate. Va committato su Git nelle applicazioni, così tutto il team compila con le stesse versioni.

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.8
  google_fonts: ^6.2.1

I pacchetti seguono il versionamento semantico: MAJOR.MINOR.PATCH (es. 6.2.1).

• MAJOR (6): cambia quando ci sono modifiche che rompono il codice esistente (breaking changes).
• MINOR (2): nuove funzionalità retrocompatibili.
• PATCH (1): correzioni di bug.

Il simbolo caret ^ è il vincolo consigliato: ^6.2.1 significa "da 6.2.1 incluso fino a 7.0.0 escluso". Accetti quindi bugfix e nuove feature, ma non aggiornamenti che potrebbero rompere l'app.

Comandi utili:

flutter pub outdated   # elenca i pacchetti con versioni più recenti disponibili
flutter pub upgrade    # aggiorna entro i vincoli del pubspec
flutter pub upgrade --major-versions  # alza anche i vincoli major (attenzione!)
flutter pub deps       # mostra l'albero delle dipendenze

⚠️ Evita di fissare versioni esatte (google_fonts: 6.2.1) senza motivo: rischi conflitti quando altri pacchetti richiedono versioni diverse.

dependencies:
  google_fonts: ^6.2.1        # >=6.2.1 <7.0.0  (consigliato)
  altro_pacchetto: 1.4.2      # versione esatta (sconsigliato)
  terzo_pacchetto: '>=2.0.0 <3.0.0'  # range esplicito
  quarto_pacchetto: any       # qualsiasi versione (da evitare)

Ora che il pacchetto è installato, va importato nel file Dart dove serve. La sintassi dell'import per i pacchetti esterni è sempre:

import 'package:nome_pacchetto/nome_file.dart';

Nel caso di google_fonts l'import è package:google_fonts/google_fonts.dart. Sostituisci il contenuto di lib/main.dart con il codice seguente: applichiamo il font Poppins a tutta l'app tramite il tema e un font diverso a un singolo Text.

💡 In VS Code, se scrivi il nome di una classe del pacchetto (es. GoogleFonts) e premi Ctrl+. / Cmd+., l'editor propone di aggiungere l'import automaticamente.

import 'package:flutter/material.dart';
import 'package:google_fonts/google_fonts.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Demo Pacchetti',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        colorSchemeSeed: Colors.indigo,
        useMaterial3: true,
        // Applica Poppins a tutti i testi dell'app
        textTheme: GoogleFonts.poppinsTextTheme(),
      ),
      home: const HomePage(),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Il mio primo pacchetto')),
      body: Padding(
        padding: const EdgeInsets.all(24),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(
              'Ciao, pub.dev!',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
            const SizedBox(height: 12),
            Text(
              'Questo testo usa il font Poppins ereditato dal tema.',
              style: Theme.of(context).textTheme.bodyLarge,
            ),
            const SizedBox(height: 24),
            Text(
              'Questo invece usa Lobster solo qui.',
              style: GoogleFonts.lobster(fontSize: 26),
            ),
          ],
        ),
      ),
    );
  }
}

Ecco i problemi tipici di chi installa un pacchetto per la prima volta e come uscirne.

1. Target of URI doesn't exist: 'package:...'
Il pacchetto non è stato scaricato o il nome è sbagliato. Esegui flutter pub get e controlla lo spelling nel pubspec.

2. Because ... depends on X >=2.0.0 version solving failed
Conflitto di versioni tra pacchetti. Prova flutter pub upgrade --major-versions, oppure allenta il vincolo del pacchetto "colpevole" o aggiorna gli altri.

3. Il pacchetto usa codice nativo (plugin) e l'app crasha dopo l'hot reload
I plugin con codice Android/iOS richiedono un restart completo dell'app (stop e flutter run), non basta l'hot reload.

4. MissingPluginException
Stessa causa: ferma l'app e riavviala. Se persiste, esegui flutter clean seguito da flutter pub get.

5. Errori di indentazione YAML
Error on line 12, column 3: Expected a key significa quasi sempre spazi sbagliati o un tab. Rientra ogni dipendenza di 2 spazi.

6. Rimuovere un pacchetto che non serve più
Usa flutter pub remove google_fonts: mantenere dipendenze inutili appesantisce il progetto e la build.

flutter clean
flutter pub get
flutter pub outdated
flutter pub remove google_fonts
flutter run