Repositorios de paquetes personalizados

La herramienta dart pub admite repositorios de paquetes de terceros. Un repositorio de paquetes es un servidor que aloja paquetes de Dart para el consumo de la herramienta dart pub. El repositorio de paquetes predeterminado utilizado, pub.dev, es operado por el equipo de Dart para facilitar la publicación de paquetes de Dart para uso público. Un repositorio de paquetes se identifica mediante una hosted-url, como https://dart-packages.example.com/.

A veces, un repositorio de paquetes personalizado puede ser útil para alojar paquetes privados, incluidos algunos de los siguientes escenarios:

1. Compartir paquetes propietarios internos dentro de una organización.
2. Control estricto de las dependencias en entornos empresariales.
3. Entornos seguros sin acceso a internet público.

También es común usar git-dependencies para alojar paquetes privados, sin embargo, la herramienta dart pub no admite la resolución de versiones contra un repositorio git; solo obtiene una revisión específica del repositorio git. Por lo tanto, cuando muchas personas colaboran a menudo es preferible usar un repositorio de paquetes privado.

La mayoría de los repositorios de paquetes personalizados son repositorios de paquetes privados que requieren autenticación. Para autenticarse contra repositorios de paquetes personalizados, la herramienta dart pub adjunta un token secreto a las solicitudes.

Puedes obtener el token secreto de tu repositorio de paquetes personalizado y especificarlo manualmente o a través de una variable de entorno. Para especificar manualmente el token secreto, usa el comando dart pub token add el cual solicita el token:

$ dart pub token add https://dart-packages.example.com
Enter secret token: [enter secret token]
Requests to "https://dart-packages.example.com" will now be authenticated using the secret token.

También puedes indicarle a dart pub que lea el token de una variable de entorno, incluso en un entorno de CI, con la bandera --env-var:

$ dart pub token add https://dart-packages.example.com --env-var MY_SECRET_TOKEN
Requests to "https://dart-packages.example.com" will now be authenticated using the secret token stored in the environment variable "MY_SECRET_TOKEN".

Esto garantiza que dart pub no almacene realmente el token secreto en su configuración, sino que simplemente guarde el hecho de que debe leer el secreto de la variable de entorno $MY_SECRET_TOKEN. Esto reduce el riesgo de que los secretos se filtren accidentalmente si el entorno de ejecución se comparte entre trabajos de CI.

Para obtener un paquete de un repositorio de paquetes personalizado, debes especificar la hosted-url para el paquete en pubspec.yaml, utilizando la sintaxis para hosted packages. Por ejemplo:

dependencies:
  example_package:
    hosted: https://dart-packages.example.com
    version: ^1.4.0

En el ejemplo anterior, package:example_package se obtiene de https://dart-packages.example.com. Si este repositorio de paquetes requiere autenticación, consulta Autenticarse con un repositorio de paquetes personalizado para obtener más información sobre cómo autenticar tus solicitudes.

También puedes usar el comando dart pub add con la bandera --hosted para agregar una dependencia desde un repositorio de paquetes personalizado:

$ dart pub add example_package --hosted https://dart-packages.example.com

También puedes obtener diferentes dependencias de diferentes repositorios de paquetes, ya que se puede especificar la hosted-url para cada dependencia:

dependencies:
  # package retry is fetched from pub.dev (the default package repository)
  retry: ^3.0.0
  # package example_package is fetched from https://dart-packages.example.com
  example_package:
    hosted: https://dart-packages.example.com
    version: ^1.4.0

Esto te permite mantener paquetes privados en un repositorio de paquetes privado mientras usas los paquetes públicos más actualizados como dependencias.

Sin embargo, pueden surgir conflictos fácilmente si tus dependencias requieren un paquete con el mismo nombre de diferentes repositorios. Por ejemplo, si el paquete retry requiere meta de pub.dev, y example_package requiere meta de https://dart-packages.example.com. Por lo tanto, si se refleja algún paquete en un repositorio de paquetes privado, a menudo es necesario reflejar todas las dependencias y actualizar la sección dependencies de cada paquete, o anular el repositorio de paquetes predeterminado.

Para publicar un paquete en un repositorio de paquetes personalizado en lugar de pub.dev, especifica la propiedad publish_to en pubspec.yaml. Si la autenticación está habilitada, la publicación utiliza la misma autenticación por token que la obtención de paquetes.

Para preparar un paquete para su publicación en https://dart-packages.example.com, tu pubspec.yaml debe verse mínimamente como el siguiente:

name: example_package
version: 1.0.0
# Ensures the package is published to https://dart-packages.example.com
publish_to: https://dart-packages.example.com

Para luego publicar una nueva versión del paquete, usa dart pub publish:

$ dart pub publish
Publishing example_package 1.0.0 to https://dart-packages.example.com
|-- CHANGELOG.md
|-- LICENSE
|-- README.md
|-- lib
|   '-- example_package.dart
'-- pubspec.yaml
...

Por defecto, dart pub obtiene dependencias y publica paquetes en el sitio pub.dev a menos que se use la sintaxis de hosted-dependency para especificar un repositorio de paquetes personalizado. Sin embargo, puedes anular el repositorio de paquetes predeterminado utilizando la variable de entorno PUB_HOSTED_URL.

Este enfoque es particularmente útil al replicar (mirroring) todos los paquetes en un repositorio de paquetes privado o un subconjunto de pub.dev cuando se trabaja en un entorno de red restringido.

Puedes desarrollar un repositorio de paquetes personalizado implementando la API REST descrita en la Hosted Pub Repository Specification Version 2.

Los repositorios de paquetes personalizados también se ofrecen como un servicio compatible con la autenticación por token por parte de múltiples proveedores, lo que te libera de la sobrecarga de alojar y mantener tu propio repositorio de paquetes personalizado:

• Cloudsmith
• Inedo ProGet
• JFrog Artifactory
• OnePub Dart Repository
• GLPub.dev