pubspec.yaml — o que é, estrutura e configuração de dependências no Flutter

O que é pubspec.yaml

O pubspec.yaml é um arquivo de manifesto no formato YAML que o gerenciador de pacotes pub utiliza para gerenciar projetos Dart e Flutter. Ele está localizado na raiz do projeto e é processado a cada comando flutter pub get. Diferente de outras plataformas onde a configuração está espalhada por vários arquivos, o Flutter usa um único manifesto centralizado para todas as necessidades.

O arquivo contém metadados: nome do projeto, descrição, versão, autor. Estes dados são usados ao publicar um pacote no pub.dev e ao compilar a aplicação para App Store e Google Play. O campo description é exibido nos resultados de pesquisa de pacotes, portanto deve ser informativo e conter palavras-chave que outros desenvolvedores possam usar para encontrar a biblioteca.

Sem um pubspec.yaml correto, um projeto Flutter não pode ser compilado. Erros de sintaxe ou indentação incorreta causam uma falha imediata de compilação com uma mensagem Error on line X. O YAML é sensível a espaços em branco: um espaço extra altera a estrutura de dados e tabulações causam um erro de sintaxe. Portanto, ao editar o pubspec.yaml manualmente, é importante usar um editor com realce de sintaxe YAML, como o VS Code com a extensão oficial do Flutter.

Seções principais do pubspec.yaml

O pubspec.yaml consiste em seções obrigatórias e opcionais. Cada seção é responsável por um aspecto específico da configuração do projeto. A ordem das seções não importa, mas por convenção da comunidade segue-se a hierarquia: metadados, ambiente, dependências, recursos, plataformas.

name e description

O campo name define um identificador único do pacote no formato snake_case, composto apenas por letras latinas minúsculas, dígitos e underscores. O campo description é um resumo breve do projeto de até 180 caracteres, obrigatório para publicação no pub.dev. A descrição deve explicar o propósito do pacote sem repetir o nome e conter palavras-chave para otimização de busca do repositório.

name: my_flutter_app
description: Aplicativo de gerenciamento de tarefas com Flutter
publish_to: 'none'

version e environment

O campo version usa versionamento semântico major.minor.patch com um número de compilação opcional após o sinal de mais (1.0.0+1). A seção environment define as versões mínima e máxima do SDK Dart e Flutter para garantir compatibilidade. Se uma nova versão do SDK contiver mudanças incompatíveis com o código do projeto, a compilação será interrompida com uma mensagem de erro clara.

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

dependencies e dev_dependencies

A seção dependencies lista os pacotes necessários para a aplicação funcionar em tempo de execução. A seção dev_dependencies contém pacotes para teste, geração de código e desenvolvimento — eles não são incluídos na versão de lançamento. Separar as dependências é fundamental para o desempenho: cada pacote em dependencies aumenta o tamanho final do APK ou IPA, bem como o tempo de inicialização da aplicação devido à inicialização de bibliotecas adicionais.

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

Configuração de assets e fontes

A seção flutter contém subseções para configurar recursos, fontes e parâmetros de plataforma. Os recursos são conectados através de um array paths que especifica arquivos específicos ou diretórios inteiros. Todos os caminhos são especificados relativos à raiz do projeto, não relativos ao pubspec.yaml. Esta é uma nuance importante que frequentemente causa confusão em desenvolvedores Flutter iniciantes.

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

Conectar assets através do pubspec.yaml torna os arquivos acessíveis via AssetBundle em tempo de execução. Isso funciona para imagens, JSON, arquivos de texto e quaisquer outros recursos. O Flutter suporta automaticamente diferentes resoluções de tela: se você adicionar images/2x/ e images/3x/, o Flutter selecionará a versão de imagem apropriada com base no device pixel ratio. Para isso, basta especificar em assets apenas a pasta raiz images/.

Fontes personalizadas são adicionadas através da seção fonts com um nome de família e uma lista de estilos. Após modificar o pubspec.yaml, é necessário executar flutter pub get para aplicar as alterações. As fontes podem ser usadas tanto globalmente no tema MaterialApp quanto localmente em widgets específicos. Para cada estilo, você pode especificar weight (100–900) e style (normal, italic), o que permite ao Flutter selecionar corretamente o arquivo de fonte ao usar FontWeight e FontStyle no código.

Gerenciamento de dependências e versões

O pub suporta várias formas de especificar fontes de dependências: pub.dev, repositórios Git, caminhos locais e repositórios privados. A escolha da fonte depende do estágio de desenvolvimento: para versões estáveis usa-se pub.dev, para forks e modificações personalizadas — Git, para bibliotecas sendo desenvolvidas em paralelo — caminho local.

O operador ^version indica uma versão compatível: ^1.2.0 permite versões >=1.2.0 e <2.0.0. Isso é análogo ao operador ~> no CocoaPods e ao operador Caret no npm. O pub resolve automaticamente o Dependency Hell através de um algoritmo SAT solver que encontra uma combinação de versões que satisfaz todas as restrições. Se tal combinação não existir, o pub exibe uma mensagem detalhada indicando os pacotes conflitantes.

O arquivo pubspec.lock fixa as versões exatas das dependências. Ele deve ser armazenado no controle de versão para aplicações, garantindo compilações reproduzíveis em todas as máquinas da equipe. Para bibliotecas, o pubspec.lock não é incluído no repositório, pois os usuários da biblioteca devem poder usá-la com diferentes versões de dependências. O comando flutter pub upgrade atualiza todas as dependências de acordo com as restrições do pubspec.yaml, enquanto flutter pub outdated mostra quais pacotes podem ser atualizados.

Configuração de compilação e publicação

Para publicar uma aplicação no pub.dev, as configurações são especificadas na seção publish_to. O valor 'none' impede a publicação acidental do pacote, o que é importante para projetos internos ou não públicos. Se publish_to estiver ausente, o pub tenta publicar o pacote no pub.dev padrão, o que pode levar a vazamentos indesejados de código.

A seção flutter inclui parâmetros de plataforma: generate para geração automática de arquivos de plataforma, e deferred-components para carregamento modular de funcionalidades. O parâmetro generate: true força o Flutter a criar e atualizar automaticamente os projetos de plataforma (iOS, Android, Web) ao adicionar novas plataformas através de flutter create --platforms. Sem este parâmetro, a estrutura de pastas da plataforma pode ficar dessincronizada com o pubspec.yaml.

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

A seção platforms define as plataformas alvo do pacote. Para aplicações, ela é determinada automaticamente ao adicionar suporte a uma plataforma específica através de flutter create. As plataformas podem ser adicionadas e removidas manualmente editando o pubspec.yaml. Os Deferred Components permitem carregar partes da aplicação sob demanda, reduzindo o tamanho da instalação — isso é especialmente relevante para jogos e aplicações com grande quantidade de conteúdo raramente usado.

Ao publicar um pacote, o pub verifica se todos os campos do pubspec.yaml atendem aos requisitos do repositório. A ausência dos campos obrigatórios name, version e description leva à rejeição da publicação. Além disso, verifica-se a correção da licença e a presença de README.md e CHANGELOG.md. Pacotes com erros do analisador de código (dart analyze) também falham na validação. Após a publicação bem-sucedida, o pacote fica disponível no pub.dev em poucos minutos.

A seção dependency_overrides permite forçar uma versão específica de um pacote, ignorando as restrições das dependências transitivas. Este é um mecanismo poderoso mas perigoso: se usado incorretamente, pode levar a incompatibilidades entre bibliotecas. Use dependency_overrides apenas temporariamente para resolver conflitos ou testar novas versões. Após corrigir as dependências principais, a sobreposição deve ser removida para não quebrar o grafo de dependências do projeto a longo prazo.

A seção executables no pubspec.yaml permite especificar scripts executáveis que o pub instala no PATH ao ativar um pacote. Isso é útil para ferramentas CLI escritas em Dart, como build_runner ou dart_code_metrics. O comando dart pub global activate instala o pacote globalmente, tornando os scripts especificados em executables acessíveis a partir do terminal. Para aplicações, executables geralmente não são usados, pois o ponto de entrada é definido através de main em lib/main.dart.