El archivo pubspec

Cada paquete de pub necesita algunos metadatos para poder especificar sus dependenciasDependenciaUn paquete de Dart del que depende un paquete. Obtén más información. Los paquetes de pub que se comparten con otros también necesitan proporcionar otra información para que los usuarios puedan descubrirlos. Todos estos metadatos van en el pubspec del paquete: un archivo llamado pubspec.yaml escrito en el lenguaje YAML.

Un pubspec puede tener los siguientes campos:

name

Requerido para cada paquete. Obtén más información.

version

Requerido para paquetes que se alojan en el sitio pub.dev. Obtén más información.

description

Requerido para paquetes que se alojan en el sitio pub.dev. Obtén más información.

homepage

Opcional. URL que apunta a la página de inicio del paquete (o al repositorio de código fuente). Obtén más información.

repository

Opcional. URL que apunta al repositorio de código fuente del paquete. Obtén más información.

issue_tracker

Opcional. URL que apunta a un rastreador de problemas (issue tracker) para el paquete. Obtén más información.

documentation

Opcional. URL que apunta a la documentación del paquete. Obtén más información.

dependencies

Se puede omitir si tu paquete no tiene dependencias. Obtén más información.

dev_dependencies

Se puede omitir si tu paquete no tiene dependencias de desarrollo (dev). Obtén más información.

dependency_overrides

Se puede omitir si no necesitas anular ninguna dependencia. Obtén más información.

environment

Requerido a partir de Dart 2. Obtén más información.

executables

Opcional. Se utiliza para colocar los ejecutables de un paquete en tu PATH. Obtén más información.

platforms

Opcional. Se utiliza para declarar explícitamente las plataformas compatibles en el sitio pub.dev. Obtén más información.

publish_to

Opcional. Especifica dónde publicar un paquete. Obtén más información.

funding

Opcional. Lista de URLs donde los usuarios pueden patrocinar el desarrollo del paquete. Obtén más información.

false_secrets

Opcional. Especifica los archivos que se deben ignorar al realizar una búsqueda previa a la publicación de posibles filtraciones de secretos. Obtén más información.

screenshots

Opcional. Especifica una lista de archivos de captura de pantalla para mostrar en el sitio pub.dev. Obtén más información.

topics

Opcional. Lista de temas (topics) para el paquete. Obtén más información.

ignored_advisories

Opcional. Lista de avisos de seguridad ignorados. Obtén más información.

hooks

Opcional. Configura ganchos (hooks) específicos del paquete, como ganchos de compilación o enlace nativos. Obtén más información.

Pub ignora todos los demás campos.

Si agregas un campo personalizado, dale un nombre único que no entre en conflicto con futuros campos del pubspec. Por ejemplo, en lugar de agregar bugs, podrías agregar un campo llamado my_pkg_bugs.

Un pubspec simple pero completo se ve algo así como lo siguiente:

name: newtify
description: >-
  Have you been turned into a newt?  Would you like to be?
  This package can help. It has all of the
  newt-transmogrification functionality you have been looking
  for.
version: 1.2.3
homepage: https://example-pet-store.com/newtify
documentation: https://example-pet-store.com/newtify/docs
​
environment:
  sdk: '^3.2.0'
​
dependencies:
  efts: ^2.0.4
  transmogrify: ^0.4.0
​
dev_dependencies:
  test: '>=1.15.0 <2.0.0'

Esta sección tiene más información sobre cada uno de los campos del pubspec.

Cada paquete necesita un nombre. Es la forma en que otros paquetes se refieren al tuyo y cómo aparece ante el mundo, en caso de que lo publiques.

El nombre debe estar en minúsculas, con guiones bajos para separar las palabras, como_este_ejemplo. Utiliza únicamente letras del alfabeto latino básico y dígitos arábigos: [a-z0-9_]. Además, asegúrate de que el nombre sea un identificador de Dart válido: que no comience con dígitos y no sea una palabra reservada.

Intenta elegir un nombre que sea claro, breve y que no esté en uso. Se recomienda realizar una búsqueda rápida de paquetes en el sitio pub.dev para asegurarse de que nadie más esté usando tu nombre.

Cada paquete tiene una versión. Se requiere un número de versión para alojar tu paquete en el sitio pub.dev, pero se puede omitir para paquetes locales únicamente. Si lo omites, tu paquete se versiona implícitamente como 0.0.0.

El versionamiento es necesario para reutilizar el código y permitir que evolucione rápidamente. Un número de versión consta de tres números separados por puntos, como 0.2.43. Opcionalmente, también puede tener un sufijo de compilación (+1, +2, +hotfix.oopsie) o preliminar (prerelease) (-dev.4, -alpha.12, -beta.7, -rc.5).

Cada vez que publicas tu paquete, lo haces en una versión específica. Una vez hecho esto, considéralo sellado herméticamente: ya no puedes tocarlo más. Para realizar más cambios, necesitarás una nueva versión.

Cuando selecciones una versión, sigue el versionamiento semántico.

Esto es opcional para tus propios paquetes personales, pero si tienes la intención de publicar tu paquete, debes proporcionar una descripción, la cual debe estar en inglés. La descripción debe ser relativamente corta (de 60 a 180 caracteres) y contarle a un lector casual lo que podría querer saber sobre tu paquete.

Piensa en la descripción como el argumento de venta para tu paquete. Los usuarios la ven cuando buscan paquetes. La descripción es texto plano: sin markdown ni HTML.

Esto debe ser una URL que apunte al sitio web de tu paquete. Para los paquetes alojados (hosted), esta URL está enlazada desde la página del paquete. Aunque proporcionar una página de inicio (homepage) es opcional, por favor proporciónala o el repositorio (o ambos). Ayuda a los usuarios a entender de dónde proviene tu paquete.

El campo opcional repository debe contener la URL del repositorio de código fuente de tu paquete; por ejemplo, https://github.com/<user>/<repository>. Si publicas tu paquete en el sitio pub.dev, la página de tu paquete mostrará la URL del repositorio. Aunque proporcionar un repositorio es opcional, por favor proporciónalo o la página de inicio (homepage) (o ambos). Ayuda a los usuarios a entender de dónde proviene tu paquete.

El campo opcional issue_tracker debe contener una URL para el rastreador de problemas (issue tracker) del paquete, donde se puedan ver los errores existentes y reportar nuevos errores. El sitio pub.dev intenta mostrar un enlace al rastreador de problemas de cada paquete utilizando el valor de este campo. Si falta issue_tracker pero repository está presente y apunta a GitHub, el sitio pub.dev utiliza el rastreador de problemas predeterminado (https://github.com/<user>/<repository>/issues).

Algunos paquetes tienen un sitio que aloja documentación, separado de la página de inicio principal y de la referencia de la API generada por pub. Si tu paquete cuenta con documentación adicional, agrega un campo documentation: con esa URL; pub muestra un enlace a esta documentación en la página de tu paquete.

Las dependenciasDependenciaUn paquete de Dart del que depende un paquete. Obtén más información son la razón de ser (raison d'être) del pubspec. En esta sección enumeras cada paquete que tu paquete necesita para funcionar.

Las dependencias se dividen en uno de dos tipos. Las dependencias regulares se enumeran bajo dependencies:; estos son paquetes que cualquiera que use tu paquete también necesitará. Las dependencias que solo se necesitan en la fase de desarrollo del propio paquete se enumeran bajo dev_dependencies.

Durante el proceso de desarrollo, es posible que necesites anular temporalmente una dependencia. Puedes hacerlo utilizando dependency_overrides.

Para obtener más información, consulta Dependencias de paquetes.

Un paquete puede exponer uno o más de sus scripts como ejecutables que se pueden ejecutar directamente desde la línea de comandos. Para que un script esté disponible públicamente, enuméralo bajo el campo executables. Las entradas se enumeran como pares clave/valor:

<name-of-executable>: <Dart-script-from-bin>

Por ejemplo, la siguiente entrada de pubspec enumera dos scripts:

executables:
  slidy: main
  fvm:

Una vez que el paquete se activa mediante dart pub global activate, al escribir slidy se ejecuta bin/main.dart. Al escribir fvm se ejecuta bin/fvm.dart. Si no especificas el valor, este se infiere a partir de la clave.

For more information, see pub global.

Cuando publicas un paquete, pub.dev detecta automáticamente las plataformas que admite el paquete. Si esta lista de plataformas compatibles es incorrecta, utiliza platforms para declarar explícitamente qué plataformas admite tu paquete.

Por ejemplo, la siguiente entrada platforms hace que pub.dev enumere el paquete como compatible con Android, iOS, Linux, macOS, Web y Windows:

# This package supports all platforms listed below.
platforms:
  android:
  ios:
  linux:
  macos:
  web:
  windows:

Aquí hay un ejemplo de declaración de que el paquete admite únicamente Linux y macOS (y no, por ejemplo, Windows):

# This package supports only Linux and macOS.
platforms:
  linux:
  macos:

El valor predeterminado utiliza el sitio pub.dev. Especifica none para evitar que se publique un paquete. Esta configuración se puede utilizar para especificar un servidor de paquetes pub personalizado para publicar.

publish_to: none

Los autores de paquetes pueden usar la propiedad funding para especificar una lista de URLs que proporcionen información sobre cómo los usuarios pueden ayudar a financiar el desarrollo del paquete. Por ejemplo:

funding:
 - https://www.buymeacoffee.com/example_user
 - https://www.patreon.com/some-account

Si se publica en pub.dev, los enlaces se muestran en la página del paquete. Esto tiene como objetivo ayudar a los usuarios a financiar el desarrollo de sus dependencias.

Cuando intentas publicar un paquete, pub realiza una búsqueda de posibles filtraciones de credenciales secretas, claves API o claves criptográficas. Si pub Hospital detecta una posible filtración en un archivo que se publicaría, te advierte y se niega a publicar el paquete.

La detección de filtraciones no es perfecta. Para evitar falsos positivos, puedes indicarle a pub que no busque filtraciones en ciertos archivos creando una lista de permitidos mediante patrones de gitignore bajo false_secrets en el pubspec.

Por ejemplo, la siguiente entrada hace que pub no busque filtraciones en el archivo lib/src/hardcoded_api_key.dart y en todos los archivos .pem del directorio test/localhost_certificates/:

false_secrets:
 - /lib/src/hardcoded_api_key.dart
 - /test/localhost_certificates/*.pem

Comenzar un patrón de gitignore con una barra diagonal (/) garantiza que el patrón se considere relativo al directorio raíz del paquete.

Los paquetes pueden exhibir sus widgets u otros elementos visuales utilizando capturas de pantalla que se muestran en su página de pub.dev. Para especificar las capturas de pantalla que debe mostrar el paquete, utiliza el campo screenshots.

Un paquete puede enumerar hasta 10 capturas de pantalla bajo el campo screenshots. No incluyas logotipos ni otras imágenes de marca en esta sección. Cada captura de pantalla incluye una descripción y una ruta (path). La descripción explica lo que representa la captura de pantalla en no más de 160 caracteres. Por ejemplo:

screenshots:
  - description: 'This screenshot shows the transformation of a number of bytes
  to a human-readable expression.'
    path: path/to/image/in/package/500x500.webp
  - description: 'This screenshot shows a stack trace returning a human-readable
  representation.'
    path: path/to/image/in/package.png

Pub.dev limita las capturas de pantalla a las siguientes especificaciones:

• Tamaño de archivo: máx. 4 MB por imagen.
• Tipos de archivo: png, jpg, gif o webp.
• Se admiten tanto imágenes estáticas como animadas.

Mantén pequeños los archivos de las capturas de pantalla. Cada descarga del paquete incluye todos los archivos de capturas de pantalla.

Pub.dev genera la imagen de miniatura del paquete a partir de la primera captura de pantalla. Si esta captura de pantalla utiliza animación, pub.dev utiliza su primer fotograma (frame).

Los autores de paquetes pueden usar el campo topics para categorizar su paquete. Los temas se pueden utilizar para facilitar la visibilidad durante las búsquedas con filtros en pub.dev. Pub.dev muestra los temas en la página del paquete, así como en los resultados de búsqueda.

El campo consiste en una lista de nombres. Por ejemplo:

topics:
  - network
  - http

Pub.dev requiere que los temas (topics) sigan estas especificaciones:

• Etiqueta cada paquete con un máximo de 5 temas.
• Write the topic name following these requirements:
  • Usa entre 2 y 32 caracteres.
  • Usa únicamente caracteres alfanuméricos en minúscula o guiones (a-z, 0-9, -).
  • No utilices dos guiones consecutivos (--).
  • Comienza el nombre con caracteres alfabéticos en minúscula (a-z).
  • Termina con caracteres alfanuméricos (a-z o 0-9).

Al elegir los temas, considera si los temas existentes son relevantes. Etiquetar con temas existentes ayuda a los usuarios a descubrir tu paquete.

Si un paquete tiene una dependencia afectada por un aviso de seguridad, pub advierte sobre el aviso durante la resolución de dependencias. Los autores de paquetes pueden usar el campo ignored_advisories como una lista de permitidos de avisos activados que no son relevantes para el paquete.

Para suprimir la advertencia sobre un aviso, agrega el identificador del aviso a la lista ignored_advisories. Por ejemplo:

name: myapp
dependencies:
  foo: ^1.0.0
ignored_advisories:
 - GHSA-4rgh-jx4f-qfcq

Para obtener más información, consulta Avisos de seguridad.

Para configurar ganchos (hooks) específicos del paquete, como ganchos de compilación o enlace nativos, utiliza el campo hooks. Bajo el campo hooks, configura los parámetros que personalizan cómo se ejecutan los ganchos.

Por ejemplo:

hooks:
  user_defines:
    my_package:
      enable_experimental: true

Para obtener más información sobre la configuración de ganchos, consulta Configuración de ganchos (Hook configuration).

Un paquete puede indicar qué versiones de sus dependencias admite, pero los paquetes tienen otra dependencia implícita: la propia plataforma Dart. La plataforma Dart evoluciona con el tiempo y es posible que un paquete solo funcione con ciertas versiones de la plataforma.

Un paquete puede especificar esas versiones mediante una restricción de SDK. Esta restricción va dentro de un campo environment separado de nivel superior en el pubspec y utiliza la misma sintaxis de restricción de versión que las dependencias.

Por ejemplo, la siguiente restricción indica que este paquete funciona con cualquier SDK de Dart que sea de la versión 3.0.0 o superior:

environment:
  sdk: ^3.0.0

Pub intenta encontrar la última versión de un paquete cuya restricción de SDK funcione con la versión del SDK de Dart que tienes instalada.

Omitir la restricción del SDK es un error. Cuando el pubspec no tiene ninguna restricción de SDK, dart pub get falla con un mensaje como el siguiente:

pubspec.yaml has no lower-bound SDK constraint.
You should edit pubspec.yaml to contain an SDK constraint:

environment:
  sdk: '^3.2.0'

See https://dart.dev/go/sdk-constraint

Pub admite especificar restricciones del SDK de Flutter bajo el campo environment::

environment:
  sdk: ^3.2.0
  flutter: '>=3.22.0'

Una restricción del SDK de Flutter se satisface únicamente si pub se está ejecutando en el contexto del ejecutable flutter, y el archivo de versión del SDK de Flutter cumple con el límite inferior de la restricción de versión. De lo contrario, el paquete no será seleccionado.

Para publicar un paquete con una restricción del SDK de Flutter, debes especificar una restricción del SDK de Dart con una versión mínima de al menos 1.19.0, para garantizar que las versiones anteriores de pub no instalen accidentalmente paquetes que necesiten Flutter.