pub: conceitos-chave, gerenciador de pacotes Dart e pubspec.yaml

O que é pub?

pub (Package Universal Browser) — um gerenciador de pacotes integrado que vem com o Dart SDK. Ele gerencia bibliotecas externas, resolve conflitos de versões, baixa dependências transitivas e armazena pacotes em cache localmente. No ecossistema Flutter, o pub é usado como ferramenta principal para conectar plugins de navegação, clientes HTTP, gerenciadores de estado e outros componentes.

As funções principais do pub incluem: instalação de dependências do registro pub.dev, caminhos locais (dependências path) e repositórios git; resolução de versões de acordo com as regras de versionamento semântico; armazenamento em cache de pacotes baixados em um diretório do sistema; publicação de pacotes próprios no registro público. Todas essas operações estão disponíveis através do comando CLI dart pub ou seu equivalente flutter pub.

A arquitetura do pub é baseada em um grafo fechado de dependências: o gerenciador constrói uma árvore onde cada pacote aparece exatamente uma vez. Se duas bibliotecas exigirem versões diferentes do mesmo pacote, o pub tenta encontrar um intervalo compatível ou reporta um erro de conflito. Isso difere da abordagem do npm, que permite múltiplas versões do mesmo pacote em diferentes nós da árvore.

Estrutura do pubspec.yaml

O arquivo pubspec.yaml — o arquivo de configuração central de qualquer projeto Dart ou Flutter. Ele é escrito em formato YAML e contém metadados, dependências, configuração de compilação e restrições do SDK. Abaixo está um exemplo típico para uma aplicação Flutter:

name: my_app
description: Exemplo de aplicativo 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/

Campos-chave do pubspec.yaml: name — nome único do pacote (apenas latim, sublinhado, dígitos); description — descrição breve (obrigatória para publicação); version — versão semântica com número de compilação opcional após o sinal de mais; environment — versões mínimas do Dart SDK e Flutter SDK; dependencies — dependências principais da aplicação; dev_dependencies — dependências apenas para desenvolvimento e testes; flutter — seção de configuração do Flutter (assets, fontes, plugins).

O campo publish_to controla a disponibilidade de publicação: o valor none proíbe a publicação (típico para aplicações), o valor padrão — https://pub.dev. O campo dependency_overrides permite substituir forçosamente a versão de um pacote em situações de conflito — usar com cautela, apenas como solução temporária.

Dependências e seus tipos

O pub suporta quatro tipos de dependências, cada um especificado com sua própria sintaxe dentro do pubspec.yaml:

Hospedadas (hosted)

O tipo padrão — o pacote é baixado do registro pub.dev ou outro registro compatível. Especifica-se o nome do pacote e a versão. Exemplo: http: ^1.1.0 baixará a última versão compatível do intervalo >=1.1.0 e <2.0.0 de acordo com as regras de caret versioning.

Dependências SDK

Usadas para incluir o Flutter SDK ou Dart SDK. Sintaxe: flutter: sdk: flutter. O pacote é obtido da instalação local do Flutter SDK, não do registro. Dependências SDK não são versionadas — sua versão é determinada pela versão do Flutter atualmente instalada.

Path

Apontam para um diretório local contendo um pacote. Útil ao desenvolver uma biblioteca e testar sem publicar. Sintaxe:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Dependências path não são fixadas no pubspec.lock — cada atualização é resolvida novamente a partir do caminho especificado.

Git

Permitem incluir um pacote diretamente de um repositório git. Branches, tags e commits são suportados:

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

Dependências git são convenientes para forks, correções não publicadas ou trabalho em Pull Requests. Recomenda-se especificar uma tag ou commit específico em vez de um branch para evitar mudanças inesperadas durante a compilação.

Versionamento e intervalos

O pub segue estritamente o Semantic Versioning 2.0: formato MAJOR.MINOR.PATCH, onde MAJOR — mudanças incompatíveis, MINOR — adições compatíveis com versões anteriores, PATCH — correções compatíveis com versões anteriores. Com base neste esquema, o pub determina a compatibilidade dos pacotes e resolve conflitos.

Três operadores principais são usados para especificar versões no pubspec.yaml:

• Caret (^) — ^1.2.3 é equivalente a >=1.2.3 e <2.0.0. O operador mais comum, pois implica compatibilidade dentro da versão major. Para pacotes com versão major 0 (zero) — ^0.1.2 significa >=0.1.2 e <0.2.0, seguindo as regras SemVer para versões instáveis.
• Tilde (~) — ~1.2.3 é equivalente a >=1.2.3 e <1.3.0. Fixa a versão minor, permitindo apenas atualizações patch. Usado com menos frequência, principalmente quando se conhece uma incompatibilidade no nível da versão minor.
• Intervalo exato — >=1.2.0 <2.0.0 — notação explícita que dá controle total. Útil para restrições complexas, por exemplo ao usar múltiplas versões de dependências transitivas.

Após executar dart pub get, o pub gera um arquivo pubspec.lock que fixa as versões exatas de todos os pacotes resolvidos (diretos e transitivos). Este arquivo deve ser incluído no controle de versão para garantir compilações reproduzíveis em todas as máquinas. Ao executar dart pub upgrade, o arquivo lock é atualizado para as últimas versões compatíveis dentro das restrições especificadas.

Um erro de dependency conflict ocorre quando dois pacotes exigem intervalos não sobrepostos da mesma dependência. O pub informa quais pacotes estão em conflito e por quê. Solução: atualizar um dos pacotes em conflito para uma versão compatível, usar dependency_overrides (medida temporária) ou mudar para um pacote alternativo.

Comandos principais do pub

Todas as operações do pub são realizadas através de uma interface CLI unificada. O Dart SDK usa o comando dart pub, o Flutter SDK usa o equivalente flutter pub (adicionalmente considera dependências e plugins do Flutter SDK). Abaixo estão os comandos-chave:

• dart pub get — baixa todas as dependências especificadas no pubspec.yaml, resolve versões e cria/atualiza o pubspec.lock. Execute ao clonar um projeto pela primeira vez ou após alterar dependências.
• dart pub upgrade — atualiza todas as dependências para as últimas versões dentro das restrições do pubspec.yaml e sobrescreve o pubspec.lock. Um pacote individual pode ser atualizado: dart pub upgrade http.
• dart pub add <package> — adiciona uma nova dependência ao pubspec.yaml e executa imediatamente o pub get. Exemplo: dart pub add dio adiciona a última versão do pacote dio.
• dart pub remove <package> — remove uma dependência do pubspec.yaml e reinicia a resolução do grafo.
• dart pub cache repair — recarrega todos os pacotes em cache. Ajuda quando o cache local está corrompido ou ocorrem erros de soma de verificação.
• dart pub deps — imprime a árvore de dependências em um formato de texto conveniente. Útil para analisar dependências transitivas e encontrar duplicatas.
• dart pub publish — publica o pacote atual no pub.dev. Antes de publicar, valida o pubspec.yaml, a licença e a descrição.
• dart pub outdated — mostra uma lista de dependências desatualizadas indicando a versão atual, desejada e a última disponível. Análogo ao npm outdated.

Todos os comandos também estão disponíveis na forma abreviada dart pub get como dart pub g (nem todas as abreviações). Em projetos Flutter, os comandos são prefixados com flutter: flutter pub get, flutter pub add e assim por diante. A versão Flutter adicionalmente verifica a compatibilidade dos plugins com a plataforma alvo.

Publicação no pub.dev

pub.dev — o registro central de pacotes do ecossistema Dart e Flutter. Em janeiro de 2025, mais de 50.000 pacotes foram publicados lá, com downloads totais superiores a 10 bilhões. Cada pacote tem uma página com descrição, documentação, pontuações de popularidade, pontuações Pub Points e versões.

Pub Points — um sistema automatizado de avaliação de qualidade do pacote de 0 a 130 pontos. Considera: presença de licença, descrição, exemplos, compatibilidade com a última versão estável do Dart, ausência de vulnerabilidades, cobertura de testes, correção da formatação. Uma pontuação alta aumenta a visibilidade do pacote na busca e a confiança dos usuários.

O processo de publicação inclui várias etapas:

1. Verificar o pubspec.yaml: garantir que name, description, version, license estejam presentes (recomenda-se identificador SPDX, por exemplo MIT).
2. Executar dart pub publish --dry-run — uma simulação sem enviar ao servidor, exibe todos os arquivos que serão incluídos no pacote e possíveis erros.
3. Autenticar-se via conta Google na primeira publicação: dart pub publish abrirá um navegador para autenticação OAuth.
4. Confirmar a publicação no terminal. Após o upload bem-sucedido, o pacote aparece no pub.dev em alguns minutos.

Regras importantes: apenas pacotes com nome único podem ser publicados; uma vez publicada, uma versão não pode ser excluída (apenas ocultada — dart pub unpublish — dentro de 7 dias); para atualizações importantes, siga as regras do Semantic Versioning, não quebre a API pública sem alterar a versão major.