pubspec.yaml — qué es, estructura y configuración de dependencias en Flutter

Qué es pubspec.yaml

pubspec.yaml es un archivo de manifiesto en formato YAML que el gestor de paquetes pub utiliza para gestionar proyectos Dart y Flutter. Se encuentra en la raíz del proyecto y se procesa con cada comando flutter pub get. A diferencia de otras plataformas donde la configuración está dispersa en varios archivos, Flutter utiliza un único manifiesto centralizado para todas las necesidades.

El archivo contiene metadatos: nombre del proyecto, descripción, versión, autor. Estos datos se utilizan al publicar un paquete en pub.dev y al compilar la aplicación para App Store y Google Play. El campo description se muestra en los resultados de búsqueda de paquetes, por lo que debe ser informativo y contener palabras clave que otros desarrolladores puedan usar para encontrar la librería.

Sin un pubspec.yaml correcto, un proyecto Flutter no se puede compilar. Los errores de sintaxis o una sangría incorrecta provocan un fallo inmediato de compilación con un mensaje Error on line X. YAML es sensible a los espacios en blanco: un espacio adicional cambia la estructura de datos y las tabulaciones causan un error de sintaxis. Por lo tanto, al editar pubspec.yaml manualmente, es importante usar un editor con resaltado de sintaxis YAML, como VS Code con la extensión oficial de Flutter.

Secciones principales de pubspec.yaml

pubspec.yaml consta de secciones obligatorias y opcionales. Cada sección es responsable de un aspecto específico de la configuración del proyecto. El orden de las secciones no importa, pero por convención de la comunidad se sigue la jerarquía: metadatos, entorno, dependencias, recursos, plataformas.

name y description

El campo name establece un identificador único del paquete en formato snake_case, formado solo por letras latinas en minúscula, dígitos y guiones bajos. El campo description es un resumen breve del proyecto de hasta 180 caracteres, obligatorio para publicar en pub.dev. La descripción debe explicar el propósito del paquete sin repetir el nombre y contener palabras clave para la optimización en búsquedas del repositorio.

name: my_flutter_app
description: Aplicación para gestionar tareas con Flutter
publish_to: 'none'

version y environment

El campo version utiliza el versionado semántico major.minor.patch con un número de compilación opcional tras el signo más (1.0.0+1). La sección environment establece las versiones mínima y máxima del SDK de Dart y Flutter para garantizar la compatibilidad. Si una nueva versión del SDK contiene cambios incompatibles con el código del proyecto, la compilación se interrumpirá con un mensaje de error claro.

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

dependencies y dev_dependencies

La sección dependencies enumera los paquetes necesarios para que la aplicación funcione en tiempo de ejecución. La sección dev_dependencies contiene paquetes para pruebas, generación de código y desarrollo — no se incluyen en la compilación final. Separar las dependencias es fundamental para el rendimiento: cada paquete en dependencies aumenta el tamaño del APK o IPA final, así como el tiempo de inicio de la aplicación debido a la inicialización de librerías adicionales.

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

Configuración de assets y fuentes

La sección flutter contiene subsecciones para configurar recursos, fuentes y parámetros de plataforma. Los recursos se conectan mediante un array de paths que especifica archivos concretos o directorios completos. Todas las rutas se indican relativas a la raíz del proyecto, no relativas a pubspec.yaml. Este es un matiz importante que suele causar confusión entre los desarrolladores principiantes de Flutter.

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 a través de pubspec.yaml hace que los archivos sean accesibles mediante AssetBundle en tiempo de ejecución. Esto funciona para imágenes, JSON, archivos de texto y cualquier otro recurso. Flutter admite automáticamente diferentes resoluciones de pantalla: si añades images/2x/ y images/3x/, Flutter seleccionará la versión de imagen adecuada según el device pixel ratio. Para ello, basta con indicar en assets solo la carpeta raíz images/.

Las fuentes personalizadas se añaden mediante la sección fonts con un nombre de familia y una lista de estilos. Tras modificar pubspec.yaml, es necesario ejecutar flutter pub get para aplicar los cambios. Las fuentes pueden usarse tanto globalmente en el tema MaterialApp como localmente en widgets concretos. Para cada estilo se puede especificar weight (100–900) y style (normal, italic), lo que permite a Flutter seleccionar correctamente el archivo de fuente al usar FontWeight y FontStyle en el código.

Gestión de dependencias y versiones

pub admite varias formas de especificar fuentes de dependencias: pub.dev, repositorios Git, rutas locales y repositorios privados. La elección de la fuente depende de la etapa de desarrollo: para versiones estables se usa pub.dev, para forks y modificaciones personalizadas — Git, para librerías que se desarrollan en paralelo — ruta local.

El operador ^version indica una versión compatible: ^1.2.0 permite versiones >=1.2.0 y <2.0.0. Es análogo al operador ~> en CocoaPods y al operador Caret en npm. pub resuelve automáticamente el Dependency Hell mediante un algoritmo SAT solver que encuentra una combinación de versiones que satisface todas las restricciones. Si no existe tal combinación, pub muestra un mensaje detallado indicando los paquetes en conflicto.

El archivo pubspec.lock fija las versiones exactas de las dependencias. Debe almacenarse en el control de versiones para las aplicaciones, garantizando compilaciones reproducibles en todas las máquinas del equipo. Para las librerías, pubspec.lock no se incluye en el repositorio, ya que los usuarios de la librería deben poder usarla con diferentes versiones de dependencias. El comando flutter pub upgrade actualiza todas las dependencias según las restricciones de pubspec.yaml, mientras que flutter pub outdated muestra qué paquetes se pueden actualizar.

Configuración de compilación y publicación

Para publicar una aplicación en pub.dev, la configuración se especifica en la sección publish_to. El valor 'none' evita la publicación accidental del paquete, lo que es importante para proyectos internos o no públicos. Si falta publish_to, pub intenta publicar el paquete en pub.dev por defecto, lo que podría provocar fugas de código no deseadas.

La sección flutter incluye parámetros de plataforma: generate para la generación automática de archivos de plataforma, y deferred-components para la carga modular de funcionalidades. El parámetro generate: true obliga a Flutter a crear y actualizar automáticamente los proyectos de plataforma (iOS, Android, Web) al añadir nuevas plataformas mediante flutter create --platforms. Sin este parámetro, la estructura de carpetas de la plataforma puede desincronizarse con pubspec.yaml.

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

La sección platforms establece las plataformas objetivo del paquete. Para las aplicaciones, se determina automáticamente al añadir soporte para una plataforma específica mediante flutter create. Las plataformas se pueden añadir y eliminar manualmente editando pubspec.yaml. Deferred Components permite cargar partes de la aplicación bajo demanda, reduciendo el tamaño de instalación — esto es especialmente relevante para juegos y aplicaciones con gran cantidad de contenido usado con poca frecuencia.

Al publicar un paquete, pub comprueba que todos los campos de pubspec.yaml cumplen los requisitos del repositorio. La falta de los campos obligatorios name, version y description provoca el rechazo de la publicación. Además, se verifica la corrección de la licencia y la presencia de README.md y CHANGELOG.md. Los paquetes con errores del analizador de código (dart analyze) también fallan la validación. Tras una publicación exitosa, el paquete está disponible en pub.dev en cuestión de minutos.

La sección dependency_overrides permite forzar una versión específica de un paquete, ignorando las restricciones de las dependencias transitivas. Es un mecanismo potente pero peligroso: si se usa incorrectamente, puede provocar incompatibilidades entre librerías. Usa dependency_overrides solo temporalmente para resolver conflictos o probar nuevas versiones. Tras corregir las dependencias principales, la sobreescritura debe eliminarse para no romper el grafo de dependencias del proyecto a largo plazo.

La sección executables en pubspec.yaml permite especificar scripts ejecutables que pub instala en PATH al activar un paquete. Esto es útil para herramientas CLI escritas en Dart, como build_runner o dart_code_metrics. El comando dart pub global activate instala el paquete globalmente, haciendo accesibles los scripts indicados en executables desde el terminal. Para las aplicaciones, executables no suele usarse, ya que el punto de entrada se define mediante main en lib/main.dart.