pub: conceptos clave, gestor de paquetes Dart y pubspec.yaml

¿Qué es pub?

pub (Package Universal Browser) — un gestor de paquetes integrado que viene con Dart SDK. Gestiona bibliotecas externas, resuelve conflictos de versiones, descarga dependencias transitivas y almacena paquetes en caché localmente. En el ecosistema Flutter, pub se utiliza como herramienta principal para conectar plugins de navegación, clientes HTTP, gestores de estado y otros componentes.

Las funciones principales de pub incluyen: instalación de dependencias desde el registro pub.dev, rutas locales (dependencias path) y repositorios git; resolución de versiones según las reglas de versionado semántico; almacenamiento en caché de paquetes descargados en un directorio del sistema; publicación de paquetes propios en el registro público. Todas estas operaciones están disponibles a través del comando CLI dart pub o su equivalente flutter pub.

La arquitectura de pub se basa en un grafo cerrado de dependencias: el gestor construye un árbol donde cada paquete aparece exactamente una vez. Si dos bibliotecas requieren versiones diferentes del mismo paquete, pub intenta encontrar un rango compatible o informa de un error de conflicto. Esto difiere del enfoque de npm, que permite múltiples versiones del mismo paquete en diferentes nodos del árbol.

Estructura de pubspec.yaml

El archivo pubspec.yaml — el archivo de configuración central de cualquier proyecto Dart o Flutter. Está escrito en formato YAML y contiene metadatos, dependencias, configuración de compilación y restricciones del SDK. A continuación se muestra un ejemplo típico para una aplicación Flutter:

name: my_app
description: Ejemplo de aplicación 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 clave de pubspec.yaml: name — nombre único del paquete (solo latín, guión bajo, dígitos); description — descripción breve (obligatoria para publicar); version — versión semántica con número de compilación opcional después del signo más; environment — versiones mínimas de Dart SDK y Flutter SDK; dependencies — dependencias principales de la aplicación; dev_dependencies — dependencias solo para desarrollo y pruebas; flutter — sección de configuración de Flutter (assets, fuentes, plugins).

El campo publish_to controla la disponibilidad de publicación: el valor none prohíbe la publicación (típico para aplicaciones), el valor predeterminado es https://pub.dev. El campo dependency_overrides permite anular forzosamente la versión de un paquete en situaciones de conflicto — usar con precaución, solo como solución temporal.

Dependencias y sus tipos

pub admite cuatro tipos de dependencias, cada uno especificado con su propia sintaxis dentro de pubspec.yaml:

Alojadas (hosted)

El tipo estándar — el paquete se descarga del registro pub.dev u otro registro compatible. Se especifica el nombre del paquete y la versión. Ejemplo: http: ^1.1.0 descargará la última versión compatible del rango >=1.1.0 y <2.0.0 según las reglas de caret versioning.

Dependencias SDK

Se utilizan para incluir Flutter SDK o Dart SDK. Sintaxis: flutter: sdk: flutter. El paquete se toma de la instalación local de Flutter SDK, no del registro. Las dependencias SDK no tienen versionado — su versión está determinada por la versión de Flutter instalada actualmente.

De ruta (path)

Apuntan a un directorio local que contiene un paquete. Útil al desarrollar una biblioteca y probar sin publicar. Sintaxis:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Las dependencias path no se fijan en pubspec.lock — cada actualización se resuelve nuevamente desde la ruta especificada.

Git

Permiten incluir un paquete directamente desde un repositorio git. Se admiten ramas, etiquetas y commits:

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

Las dependencias git son convenientes para forks, correcciones no publicadas o trabajo en Pull Requests. Se recomienda especificar una etiqueta o commit concreto en lugar de una rama para evitar cambios inesperados durante la compilación.

Versionado y rangos

pub sigue estrictamente Semantic Versioning 2.0: formato MAJOR.MINOR.PATCH, donde MAJOR — cambios incompatibles, MINOR — adiciones compatibles hacia atrás, PATCH — correcciones compatibles hacia atrás. Basándose en este esquema, pub determina la compatibilidad de los paquetes y resuelve conflictos.

Se utilizan tres operadores principales para especificar versiones en pubspec.yaml:

• Caret (^) — ^1.2.3 equivale a >=1.2.3 y <2.0.0. El operador más común, ya que implica compatibilidad dentro de la versión major. Para paquetes con versión major 0 (cero) — ^0.1.2 significa >=0.1.2 y <0.2.0, siguiendo las reglas de SemVer para versiones inestables.
• Tilde (~) — ~1.2.3 equivale a >=1.2.3 y <1.3.0. Fija la versión minor, permitiendo solo actualizaciones patch. Se usa con menos frecuencia, principalmente cuando se conoce una incompatibilidad a nivel de versión minor.
• Rango exacto — >=1.2.0 <2.0.0 — notación explícita que brinda control total. Útil para restricciones complejas, por ejemplo al usar múltiples versiones de dependencias transitivas.

Después de ejecutar dart pub get, pub genera un archivo pubspec.lock que fija las versiones exactas de todos los paquetes resueltos (directos y transitivos). Este archivo debe incluirse en el control de versiones para garantizar compilaciones reproducibles en todas las máquinas. Al ejecutar dart pub upgrade, el archivo lock se actualiza a las últimas versiones compatibles dentro de las restricciones especificadas.

Un error de dependency conflict ocurre cuando dos paquetes requieren rangos no superpuestos de la misma dependencia. pub informa qué paquetes están en conflicto y por qué. Solución: actualizar uno de los paquetes en conflicto a una versión compatible, usar dependency_overrides (medida temporal) o cambiar a un paquete alternativo.

Comandos principales de pub

Todas las operaciones de pub se realizan a través de una interfaz CLI unificada. Dart SDK usa el comando dart pub, Flutter SDK usa el equivalente flutter pub (además considera las dependencias y plugins de Flutter SDK). A continuación se presentan los comandos clave:

• dart pub get — descarga todas las dependencias especificadas en pubspec.yaml, resuelve versiones y crea/actualiza pubspec.lock. Se ejecuta al clonar un proyecto por primera vez o después de cambiar dependencias.
• dart pub upgrade — actualiza todas las dependencias a las últimas versiones dentro de las restricciones de pubspec.yaml y sobrescribe pubspec.lock. Se puede actualizar un paquete individual: dart pub upgrade http.
• dart pub add <package> — añade una nueva dependencia a pubspec.yaml y ejecuta inmediatamente pub get. Ejemplo: dart pub add dio añade la última versión del paquete dio.
• dart pub remove <package> — elimina una dependencia de pubspec.yaml y reinicia la resolución del grafo.
• dart pub cache repair — recarga todos los paquetes en caché. Ayuda cuando la caché local está dañada o ocurren errores de suma de verificación.
• dart pub deps — imprime el árbol de dependencias en un formato de texto conveniente. Útil para analizar dependencias transitivas y encontrar duplicados.
• dart pub publish — publica el paquete actual en pub.dev. Antes de publicar, valida el pubspec.yaml, la licencia y la descripción.
• dart pub outdated — muestra una lista de dependencias obsoletas indicando la versión actual, deseada y la última disponible. Análogo a npm outdated.

Todos los comandos también están disponibles en forma abreviada dart pub get como dart pub g (no todas las abreviaturas). En proyectos Flutter, los comandos llevan el prefijo flutter: flutter pub get, flutter pub add y así sucesivamente. La versión Flutter además verifica la compatibilidad de los plugins con la plataforma de destino.

Publicación en pub.dev

pub.dev — el registro central de paquetes del ecosistema Dart y Flutter. En enero de 2025, se han publicado allí más de 50 000 paquetes, con descargas totales que superan los 10 mil millones. Cada paquete tiene una página con descripción, documentación, puntuaciones de popularidad, puntuaciones Pub Points y versiones.

Pub Points — un sistema automatizado de evaluación de calidad del paquete de 0 a 130 puntos. Considera: presencia de licencia, descripción, ejemplos, compatibilidad con la última versión estable de Dart, ausencia de vulnerabilidades, cobertura de pruebas, corrección del formato. Una puntuación alta aumenta la visibilidad del paquete en la búsqueda y la confianza de los usuarios.

El proceso de publicación incluye varios pasos:

1. Verificar pubspec.yaml: asegurar que name, description, version, license estén presentes (se recomienda identificador SPDX, por ejemplo MIT).
2. Ejecutar dart pub publish --dry-run — una simulación sin enviar al servidor, muestra todos los archivos que se incluirán en el paquete y posibles errores.
3. Autenticarse mediante cuenta de Google en la primera publicación: dart pub publish abrirá un navegador para la autenticación OAuth.
4. Confirmar la publicación en la terminal. Después de una carga exitosa, el paquete aparece en pub.dev en unos minutos.

Reglas importantes: solo se pueden publicar paquetes con un nombre único; una vez publicada, una versión no se puede eliminar (solo ocultar — dart pub unpublish — dentro de 7 días); para actualizaciones importantes, seguir las reglas de Semantic Versioning, no romper la API pública sin cambiar la versión major.