Opciones del pubspec de Flutter

Esta página está dirigida principalmente a personas que escriben apps de Flutter. Si escribes paquetes o plugins, (quizás quieras crear un plugin federado), deberías consultar la página Desarrollo de paquetes y plugins .

Cada proyecto de Flutter incluye un archivo pubspec.yaml, a menudo conocido como el pubspec. Un pubspec básico se genera cuando creas un nuevo proyecto de Flutter. Está ubicado en la raíz del árbol del proyecto y contiene metadatos sobre el proyecto que las herramientas de Dart y Flutter necesitan conocer. El pubspec está escrito en YAML, que es legible por humanos, pero ten en cuenta que el espacio en blanco (tabs vs espacios) importa.

El pubspec especifica las dependencias que requiere el proyecto, como:

• Paquetes particulares y sus versiones
• Fuentes
• Imágenes
• Paquetes para desarrolladores (como paquetes de testing o mocking)
• Restricciones particulares en la versión del Flutter SDK

Los campos comunes tanto para proyectos Dart como Flutter se describen en el archivo pubspec en dart.dev. Esta página enumera los campos y paquetes específicos de Flutter que solo son válidos para un proyecto de Flutter.

Cuando creas un nuevo proyecto con el comando flutter create (o usando el botón equivalente en tu IDE), se crea un pubspec para una app básica de Flutter.

La primera vez que construyes tu proyecto, también crea un archivo pubspec.lock que contiene versiones específicas de los paquetes incluidos. Esto garantiza que obtengas la misma versión la próxima vez que se construya el proyecto.

Aquí hay un ejemplo de un archivo pubspec para un proyecto Flutter. Los campos y paquetes exclusivos de Flutter están resaltados.

name: <project name>
description: A new Flutter project.
​
publish_to: none
version: 1.0.0+1
​
environment:
  sdk: ^3.12.0
​
dependencies:
  flutter:       # Required for every Flutter project
    sdk: flutter # Required for every Flutter project
  flutter_localizations: # Required to enable localization
    sdk: flutter         # Required to enable localization
​
  cupertino_icons: ^1.0.8 # Only required if you use Cupertino (iOS style) icons
​
dev_dependencies:
  flutter_test:
    sdk: flutter # Required for a Flutter project that includes tests
​
  flutter_lints: ^6.0.0 # Contains a set of recommended lints for Flutter code
​
flutter:
​
  uses-material-design: true # Required if you use the Material icon font
​
  generate: true # Enables generation of localized strings from arb files
​
  config: # App-specific configuration flags that mirror `flutter config`
    enable-swift-package-manager: true
​
  assets:  # Lists assets, such as image files
    - images/a_dot_burr.png
    - images/a_dot_ham.png
​
  licenses: # Lists additional license files to be bundled with the app
    - assets/my_license.txt
​
  fonts:              # Required if your app uses custom fonts
    - family: Schyler
      fonts:
        - asset: fonts/Schyler-Regular.ttf
        - asset: fonts/Schyler-Italic.ttf
          style: italic
    - family: Trajan Pro
      fonts:
        - asset: fonts/TrajanPro.ttf
        - asset: fonts/TrajanPro_Bold.ttf
          weight: 700

Se pueden agregar campos específicos de Flutter y específicos de Dart al pubspec de Flutter. Para obtener más información sobre los campos específicos de Flutter, consulta las siguientes secciones. Para obtener más información sobre los campos específicos de Dart, consulta Campos admitidos en el pubspec de Dart.

Una lista de rutas de assets que usa tu app. Estos assets se empaquetan con tu aplicación. Los tipos comunes de assets incluyen datos estáticos (por ejemplo, JSON), archivos de configuración, íconos e imágenes (JPEG, WebP, GIF, WebP/GIF animados, PNG, BMP y WBMP).

Además de listar las imágenes que se incluyen en el paquete de la app, un asset de imagen también puede referirse a una o más "variantes" de resolución específica. Para más información, consulta la sección resolution aware de la página Assets e imágenes. Para obtener información sobre cómo agregar assets desde dependencias de paquetes, consulta la sección imágenes de assets en dependencias de paquetes en la misma página.

El campo asset tiene esta estructura:

flutter:
  assets:
    - [ path_to_file | path_to_directory ]
      [ flavor_path_field | platform_path_field ]
    [...]

# path_to_file structure
- path/to/directory/file

# path_to_directory structure
- path/to/directory/

# flavor_path_field structure
- path: path/to/directory
  flavors:
  - flavor_name

# platform_path_field structure
- path: path/to/file
  platforms:
    - platform_name

Subcampos de assets:

• path_to_file: Un string que representa la ruta a un archivo.
• path_to_directory: Un string que representa la ruta a un directorio.
• flavor_path_field: Un campo de ruta y sus subcampos de flavor.
• platform_path_field: Un campo de ruta y sus subcampos de plataforma.
• path: La ruta a un archivo o directorio de asset.
• flavors: Una lista de flavors de flutter para usar con assets en una ruta específica. Para aprender más sobre flavors, consulta Configurar flavors para iOS y macOS y Configurar flavors para Android.
• platforms: Una lista de plataformas para usar con assets en una ruta específica. Los valores válidos son android, ios, web, linux, macos y windows.

Puedes pasar la ruta a un archivo:

flutter:
  assets:
    - assets/images/my_image_a.png
    - assets/images/my_image_b.png

Puedes pasar la ruta a un directorio:

flutter:
  assets:
    - assets/images/
    - assets/icons/

Puedes pasar la ruta a un directorio para flavors específicos:

flutter:
  assets:
    - path: assets/flavor_a_and_b/images
      flavors:
      - flavor_a
      - flavor_b
    - path: assets/flavor_c/images
      flavors:
      - flavor_c

Puedes pasar la ruta a un archivo para plataformas específicas:

flutter:
  assets:
    - path: assets/web_worker.js
      platforms:
        - web
    - path: assets/desktop_icon.png
      platforms:
        - windows
        - linux
        - macos

Un mapa de claves a flags (true o false) que influye en cómo se ejecuta la flutter CLI.

NOTA: Esta función solo está disponible a partir del #167953 en el canal main .

Las claves disponibles reflejan las disponibles en flutter config --list.

flutter:
  config:
    cli-animations: false
    enable-swift-package-manager: true

Usa flutter config --help para obtener una descripción de cada flag.

Las flags solo se leen del paquete de la aplicación actual, y no tienen efecto en el contexto de un paquete o dependencia.

Asigna un flavor de Flutter por defecto para una app. Cuando se usa, no necesitas incluir el nombre de este flavor en el comando de lanzamiento de Flutter.

flutter:
  default-flavor: flavor_name

En el siguiente ejemplo, una app de Flutter para Android tiene un flavor llamado staging y production. El flavor production es el flavor por defecto. Cuando se ejecuta ese flavor, no necesitas incluirlo en el comando de lanzamiento.

flutter:
  default-flavor: production

// Use this command to run the default flavor (production).
flutter run

// Use this command to run non-default flavors (staging).
flutter run --flavor staging

Para aprender cómo crear flavors en Flutter, consulta Configurar flavors de Flutter para Android y Configurar flavors de Flutter para iOS y macOS.

Difiere el tamaño de descarga inicial de una app de Android. Se usa más a menudo con aplicaciones grandes, aplicaciones modularizadas, y aplicaciones con funciones a bajo demanda.

El campo deferred-components tiene esta estructura:

flutter:
  deferred-components:
    name: component_name
      libraries:
        - string_expression
        [...]
      assets:
        - string_expression
        [...]
    [...]

Subcampos de componentes diferidos:

• name: El identificador único para un componente diferido específico.
• libraries: Una lista de librerías Dart que forman parte del componente diferido.
• assets: Una lista de rutas de assets que están asociados con el componente diferido.

Ejemplo:

flutter:
  deferred-components:
    - name: box_component
      libraries:
        - package:testdeferredcomponents/box.dart
    - name: gallery_feature
      libraries:
        - package:testdeferredcomponents/gallery_feature.dart
      assets:
        - assets/gallery_images/gallery_feature.png

Para obtener más información sobre cómo puedes usar componentes diferidos con una app de Flutter para Android, consulta Componentes diferidos para Android.

Deshabilita el uso de Swift Package Manager (SPM) para que ya no gestione dependencias en tus proyectos de Flutter para iOS y macOS.

flutter:
  disable-swift-package-manager: true

NOTA: A partir del #168433 en el canal main, esta propiedad se movió a la sección config :

pubspec.yaml

yaml

flutter:
  config:
    enable-swift-package-manager: false

content_copy

Un campo que contiene configuraciones específicas de Flutter para tu app.

flutter:
  [flutter_field]
  [...]

Configura e incluye fuentes personalizadas en tu aplicación Flutter.

Para ver ejemplos del uso de fuentes, consulta las recetas Usar una fuente personalizada y Exportar fuentes desde un paquete en el cookbook de Flutter.

El campo fonts tiene esta estructura:

flutter:
  fonts:
    -  { font_family_field | font_asset_field }
    [...]

# font_family_field structure
- family: font_name
      fonts:
        - font_asset_field
        [...]

# font_asset_field structure
- asset: path/to/directory/font_name
  weight: int_expression # Optional
  style: string_expression # Optional

Subcampos de fonts:

• family: Opcional. El nombre de la familia de fuentes. Puede tener múltiples assets de fuentes.
• asset: La fuente a utilizar.
• weight: Opcional. El grosor (weight) de la fuente. Este puede ser 100, 200, 300, 400, 500, 600, 700, 800 o 900.
• style: Opcional. El estilo de la fuente. Este puede ser italic.

Usar una fuente que no forma parte de una familia de fuentes:

flutter:
  fonts:
    - asset: fonts/Roboto-Regular.ttf
      weight: 900 # Optional
      style: italic # Optional

Usar una familia de fuentes:

flutter:
  fonts:
  - family: Roboto # Optional
        fonts:
          - asset: fonts/Roboto-Regular.ttf
          - asset: fonts/Roboto-Bold.ttf
            weight: 700 # Optional
            style: italic # Optional

Alternativamente, si tienes una fuente que no requiere requisitos de familia, grosor o estilo, puedes declararla como un asset simple:

flutter:
  assets:
    - fonts/Roboto-Regular.ttf

Maneja tareas de localización. Este campo puede aparecer como un subcampo de flutter y material.

Habilitar localización general:

flutter:
  generate: true

Una lista de rutas de archivos de licencia adicionales que deben empaquetarse con tu aplicación. Estos archivos se encuentran típicamente dentro del directorio assets de tu proyecto.

El campo licenses tiene esta estructura:

flutter:
  licenses:
    - [path_to_file]

Configura ajustes específicamente para plugins de Flutter.

El campo plugin tiene esta estructura:

flutter:
  plugin:
    platforms:
      android: # Optional
        package: com.example.my_plugin
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
      ios: # Optional
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
        sharedDarwinSource: true
      macos: # Optional
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
        sharedDarwinSource: true
      windows: # Optional
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
      linux: # Optional
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
      web: # Optional
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
    implements: # Optional
      - example_platform_interface

Subcampos de plugin:

• platforms: Una lista de plataformas que tendrán ajustes de configuración.
• package: El nombre del paquete de Android del plugin. Esto se puede usar con la plataforma Android y es obligatorio.
• pluginClass: El nombre de la clase del plugin. Opcional si se usa dartPluginClass para la misma plataforma. Esto se puede usar con las plataformas Android, iOS, Linux, macOS y Windows.
• default_package: Opcional. El paquete que se debe usar como la implementación por defecto de una interfaz de plataforma. Solo aplicable a plugins federados, donde la implementación del plugin está dividida en múltiples paquetes específicos para cada plataforma.
• dartPluginClass: Opcional. La clase Dart que sirve como punto de entrada para un plugin de Flutter. Esto se puede usar con las plataformas Android, iOS, Linux, macOS y Windows.
• sharedDarwinSource: Opcional. Indica que el plugin comparte código nativo entre iOS y macOS. Esto se puede usar con las plataformas iOS y macOS.
• fileName: Opcional. El archivo que contiene la clase del plugin.
• ffiPlugin: Opcional. True si el plugin usa una Foreign Function Interface (FFI).
• implements: Opcional. Las interfaces de plataforma que implementa un plugin de Flutter.

Para aprender más sobre plugins, consulta Desarrollo de paquetes y plugins.

Los GLSL Shaders con la extensión FRAG deben declararse en la sección shaders del archivo pubspec.yaml de tu proyecto. La herramienta de línea de comandos de Flutter compila el shader a su formato de backend adecuado, y genera los metadatos de runtime necesarios. El shader compilado se incluye luego en la aplicación al igual que un asset.

El campo shaders tiene esta estructura:

flutter:
  shaders:
    -  { path_to_file | path_to_directory }
    [...]

# path_to_file structure
- assets/shaders/file

# path_to_directory structure
- assets/shaders/

Agregar shaders específicos:

flutter:
  shaders:
    - assets/shaders/shader_a.frag
    - assets/shaders/shader_b.frag

Agregar un directorio de shaders:

flutter:
  shaders:
    - assets/shaders/

Alternativamente, puedes agregar tu directorio de shaders al campo assets:

flutter:
  assets:
    - assets/shaders/my_shader.frag

Usa componentes de Material Design en tu app Flutter.

flutter:
  uses-material-design: true

Los siguientes paquetes específicos de Flutter se pueden agregar al pubspec. Si agregas un paquete, ejecuta flutter pub get en tu terminal para instalar el paquete.

Un paquete que representa el propio Flutter SDK y se puede agregar al campo dependencies. Usa esto si tu proyecto depende del Flutter SDK, no de un paquete regular de pub.dev.

dependencies:
  flutter:
    sdk: flutter

Un paquete que representa el propio Flutter SDK y se puede agregar al campo dependencies. Usa esto para habilitar la localización de archivos ARB. A menudo usado con el paquete intl.

dependencies:
  flutter_localizations:
    sdk: flutter
  intl: any

Un paquete que representa el propio Flutter SDK y se puede agregar al campo dependencies. Usa esto si tienes pruebas unitarias, de Widgets o de integración para tu app de Flutter.

dependencies:
  flutter_test:
    sdk: flutter

Un paquete que proporciona un conjunto de lints recomendados para proyectos de Flutter. Este paquete se puede agregar al campo dev_dependency en el pubspec.

dev_dependencies:
  flutter_lints: ^6.0.0

Un paquete que proporciona un conjunto de íconos Cupertino de Apple para su uso en aplicaciones Flutter. Este paquete se puede agregar al campo dependency en el pubspec.

dependencies:
  cupertino_icons: ^1.0.0

Para obtener más información sobre paquetes, plugins y archivos pubspec, consulta lo siguiente:

• Creación de paquetes en dart.dev
• Glosario de términos de paquetes en dart.dev
• Dependencias de paquetes en dart.dev
• Usar paquetes
• Qué no hacer commit en dart.dev