Cómo usar paquetes

El ecosistema de Dart utiliza paquetes para gestionar software compartido, como bibliotecas y herramientas. Para obtener paquetes de Dart, utilizas el gestor de paquetes pub. Puedes encontrar paquetes disponibles públicamente en el sitio pub.dev, o puedes cargar paquetes desde el sistema de archivos local o desde otros lugares, como repositorios Git. Independientemente de dónde provengan tus paquetes, pub gestiona las dependencias de versiones, ayudándote a obtener versiones de paquetes que funcionen entre sí y con tu versión del SDK.

La mayoría de los IDE compatibles con Dart ofrecen soporte para usar pub que incluye la creación, descarga, actualización y publicación de paquetes. O puedes usar dart pub en la línea de comandos.

Como mínimo, un paquete de Dart es un directorio que contiene un archivo pubspec. El pubspec contiene metadatos sobre el paquete. Además, un paquete puede contener dependencias (enumeradas en el pubspec), bibliotecas de Dart, apps, recursos, pruebas, imágenes y ejemplos.

Para usar un paquete, haz lo siguiente:

• Crea un pubspec (un archivo llamado pubspec.yaml que enumera las dependencias del paquete e incluye otros metadatos, como un número de versión).
• Usa dart pub get para obtener las dependencias de tu paquete.
• Si tu código de Dart depende de una biblioteca del paquete, importa la biblioteca.

El pubspec es un archivo llamado pubspec.yaml que está en el directorio superior de tu aplicación. El pubspec más simple posible enumera solo el nombre del paquete:

name: my_app

Aquí hay un ejemplo de un pubspec que declara dependencias en dos paquetes (intl y path) que están alojados en el sitio pub.dev:

name: my_app
​
dependencies:
  intl: ^0.20.2
  path: ^1.9.1

Para actualizar el archivo pubspec.yaml, sin edición manual, puedes ejecutar el comando dart pub add. El siguiente ejemplo agrega una dependencia a vector_math.

$ dart pub add vector_math
Resolving dependencies...
+ vector_math 2.1.3
Downloading vector_math 2.1.3...
Changed 1 dependency!

Para obtener detalles sobre cómo crear un pubspec, consulta la documentación del pubspec y la documentación de los paquetes que deseas usar.

Una vez que tengas un pubspec, puedes ejecutar dart pub get desde el directorio superior de tu aplicación:

$ cd <path-to-my_app>
$ dart pub get

Este proceso se conoce como obtener las dependencias.

El comando dart pub get determina de qué paquetes depende tu app, y los coloca en una caché del sistemaCaché del sistema de PubUn directorio donde pub almacena los paquetes remotos descargados. Obtén más información central. Si tu app depende de un paquete publicado, pub descarga ese paquete del sitio pub.dev. Para una dependencia de Git, pub clona el repositorio Git. Las dependencias transitivas también se incluyen. Por ejemplo, si el paquete js depende del paquete test, pub obtiene tanto el paquete js como el paquete test.

Pub crea un archivo package_config.json (bajo el directorio .dart_tool/) que asigna cada nombre de paquete del que depende tu app al paquete correspondiente en la caché del sistema.

Para importar bibliotecas que se encuentran en los paquetes, usa el prefijo package::

import 'package:js/js.dart' as js;
import 'package:intl/intl.dart';

El entorno de ejecución de Dart toma todo lo que sigue a package: y lo busca dentro del archivo package_config.json de tu app.

También puedes usar este estilo para importar bibliotecas desde tu propio paquete. Supongamos que el paquete transmogrify está organizado de la siguiente manera:

El archivo parser_test.dart puede importar parser.dart de la siguiente manera:

import 'package:transmogrify/parser.dart';

La primera vez que obtienes una nueva dependencia para tu paquete, pub descarga la última versión del mismo que sea compatible con tus otras dependencias. Luego bloquea tu paquete para que use siempre esa versión mediante la creación de un archivo de bloqueo (lockfile). Este es un archivo llamado pubspec.lock que pub crea y almacena junto a tu pubspec. Enumera las versiones específicas de cada dependencia (inmediata y transitiva) que utiliza tu paquete.

Si tu paquete es un paquete de aplicación (application package)Paquete de aplicaciónUn paquete de Dart que contiene una aplicación ejecutable. Obtén más información debes registrar este archivo en el control de versiones. De esa manera, todos los que trabajan en tu app usarán las mismas versiones de todas sus dependencias. Registrar el archivo de bloqueo también garantiza que tu app desplegada use las mismas versiones de código.

Cuando estés listo para actualizar tus dependencias a las últimas versiones, usa el comando dart pub upgrade:

$ dart pub upgrade

El comando dart pub upgrade le indica a pub que regenere el archivo de bloqueo (lockfile), utilizando las versiones más recientes disponibles de las dependencias de tu paquete. Si deseas actualizar solo una dependencia, puedes especificar el paquete que deseas actualizar:

$ dart pub upgrade transmogrify

Ese comando actualiza transmogrify a la última versión pero deja todo lo demás igual.

El comando dart pub upgrade no siempre puede actualizar cada paquete a su última versión debido a restricciones de versión en conflicto en el pubspec. Para identificar paquetes desactualizados que requieran editar el pubspec, usa dart pub outdated.

En algunas situaciones, dart pub get no obtiene las versiones exactas de los paquetes bloqueadas en el archivo pubspec.lock:

• Si se agregan nuevas dependencias o se eliminan de pubspec.yaml después de la última actualización del archivo pubspec.lock.
• Si la versión bloqueada ya no existe en el repositorio de paquetes.
• Si cambiaste a una versión diferente del SDK de Dart y algunos paquetes ya no son compatibles con esa nueva versión.

En estos casos, dart pub get hará lo siguiente:

• Desbloqueará suficientes versiones de dependencias bloqueadas para que la resolución sea posible.
• Te notificará sobre cualquier cambio de dependencia en relación con el pubspec.lock existente.

Por ejemplo, después de agregar retry: ^3.0.0 a tus dependencias:

$ dart pub get
Resolving dependencies... (1.0s)
Downloading packages...
+ retry 3.1.2

Además, si el hash de contenidoHash de contenido de PubHashes SHA256 mantenidos por pub.dev para validar la integridad del paquete. Obtén más información de una versión de paquete publicada difiere del hash en el archivo pubspec.lock, pub te advertirá y actualizará el archivo de bloqueo para reflejar la versión publicada.

Por ejemplo, si cambias manualmente el hash de retry en pubspec.lock:

$ dart pub get
Resolving dependencies...
Downloading packages...
~ retry 3.1.2 (was 3.1.2)
The existing content-hash from pubspec.lock doesn't match contents for:
 * retry-3.1.2 from "https://pub.dev"

This indicates one of:
 * The content has changed on the server since you created the pubspec.lock.
 * The pubspec.lock has been corrupted.

The content-hashes in pubspec.lock has been updated.

For more information see:
https://dart.dev/go/content-hashes
Changed 1 dependency!

Al desplegar tu proyecto en producción, usa dart pub get --enforce-lockfile para obtener las dependencias.

Si las restricciones de dependencia de tu proyecto no se pueden satisfacer con las versiones exactas y los hashes de contenido en pubspec.lock, la obtención de paquetes y el comando fallarán. Esto ayuda a evitar el despliegue de dependencias y versiones de dependencias no probadas en producción.

$ dart pub get --enforce-lockfile
Resolving dependencies...
Downloading packages...
~ retry 3.1.2 (was 3.1.2)
The existing content-hash from pubspec.lock doesn't match contents for:
 * retry-3.1.2 from "https://pub.dev"

This indicates one of:
 * The content has changed on the server since you created the pubspec.lock.
 * The pubspec.lock has been corrupted.

For more information see:
https://dart.dev/go/content-hashes
Would change 1 dependency.
Unable to satisfy `pubspec.yaml` using `pubspec.lock`.

To update `pubspec.lock` run `dart pub get` without `--enforce-lockfile`.

Las siguientes páginas tienen más información sobre los paquetes y el gestor de paquetes pub.

• Creación de paquetes
• Publicación de paquetes
• Pub workspaces (soporte para monorepos)

• Dependencias de pub
• Variables de entorno de pub
• Convenciones de diseño de paquetes de pub
• Filosofía de versionamiento de pub
• Formato del pubspec
• Glosario con términos de pub

La herramienta dart pub proporciona los siguientes subcomandos:

• add
• cache
• deps
• downgrade
• get
• global
• outdated
• publish
• remove
• token
• unpack
• upgrade

Para obtener una visión general de todos los subcomandos de dart pub, consulta la documentación de la herramienta pub.

Solución de problemas de pub ofrece soluciones a los problemas con los que te podrías encontrar al usar pub.