Publicación de paquetes

El gestor de paquetes pub no es solo para usar los paquetes de otras personas. También te permite compartir tus paquetes con el mundo. Si tienes un proyecto útil y deseas que otros puedan usarlo, utiliza el comando dart pub publish.

Mira el siguiente video para obtener una visión general sobre cómo compilar y publicar paquetes.

Ver en YouTube en una pestaña nueva: "Cómo crear un paquete en Dart"

Ten en cuenta que un paquete publicado dura para siempre. Tan pronto como publicas tu paquete, los usuarios pueden depender de él. Una vez que comienzan a depender de él, eliminar el paquete rompería los suyos. Para evitar eso, la política de pub.dev no permite despublicar paquetes, excepto en muy pocos casos.

Siempre puedes cargar nuevas versiones de tu paquete, pero las antiguas seguirán estando disponibles para los usuarios que aún no puedan actualizar.

Para los paquetes publicados que han perdido relevancia o carecen de mantenimiento, márcalos como descontinuados.

Al publicar un paquete, sigue las convenciones que se encuentran en el formato de pubspec y en la estructura de diseño del paquete (package layout). Para simplificar el uso de tu paquete, Dart requiere estas convenciones. Estas convenciones contienen algunas excepciones que se indican en las guías enlazadas. Cuando se invoca, pub señala qué cambios puedes realizar para que tu paquete funcione mejor dentro del ecosistema de Dart.

Más allá de estas convenciones, debes cumplir con estos requisitos:

• Incluye un archivo LICENSE en tu paquete. Recomendamos la licencia BSD de 3 cláusulas, que los equipos de Dart y Flutter suelen utilizar. Sin embargo, puedes usar cualquier licencia adecuada para tu paquete.

• Verifica que tienes el derecho legal de redistribuir cualquier cosa que cargues como parte de tu paquete.

• Mantén el tamaño del paquete dentro de los límites. Recomendamos menos de 100 MB después de la compresión gzip y menos de 256 MB sin comprimir.

  Si tu paquete es demasiado grande, considera dividirlo en múltiples paquetes, usar un archivo .pubignore para eliminar el contenido innecesario o reducir la cantidad de recursos o ejemplos incluidos.

• Haz que tu paquete dependa únicamente de dependencias alojadas (hosted) del servidor de paquetes pub predeterminado y de dependencias del SDK (sdk: flutter). Estas restricciones garantizan que las dependencias de tus paquetes se puedan encontrar y acceder en el futuro.

• Tener una cuenta de Google. Pub utiliza una cuenta de Google para gestionar los permisos de carga de paquetes. Tu cuenta de Google puede estar asociada con una dirección de Gmail o cualquier otra dirección de correo electrónico.

Pub utiliza el contenido de unos pocos archivos para crear una página para tu paquete en pub.dev/packages/<your_package>. Los siguientes archivos afectan el contenido de la página web de tu paquete.

README.md

Este archivo contiene el contenido principal que se presenta en la página web de tu paquete. El contenido del archivo debe estar formateado con Markdown. Para aprender a escribir un excelente README, consulta Cómo escribir páginas de paquetes (Writing package pages).

CHANGELOG.md

Si se encuentra, este archivo completa su propia pestaña en la página web de tu paquete. Los desarrolladores pueden leer tus cambios directamente desde pub.dev. El contenido del archivo debe estar formateado con Markdown.

pubspec.yaml

Este archivo completa los detalles sobre tu paquete en el lado derecho de la página web de tu paquete. El contenido del archivo debe seguir las convenciones de YAML. Estos detalles incluyen la descripción, la página de inicio (homepage) y similares.

Puedes publicar paquetes utilizando un editor verificado (recomendado) o una cuenta de Google independiente. El uso de un editor verificado tiene las siguientes ventajas:

• Los consumidores de tu paquete saben que el dominio del editor ha sido verificado.
• Puedes evitar que pub.dev muestre tu dirección de correo electrónico personal. En su lugar, pub.dev muestra el dominio del editor y la dirección de contacto.
• El sitio pub.dev muestra una insignia de editor verificado junto al nombre de tu paquete en las páginas de búsqueda y en las páginas de paquetes individuales.

Para crear un editor verificado, sigue estos pasos:

1. Ve a pub.dev.

2. Inicia sesión en pub.dev usando una cuenta de Google.

3. En el menú de usuario de la esquina superior derecha, selecciona Crear editor (Create Publisher).

4. Introduce el nombre de dominio que deseas asociar con tu editor (por ejemplo, dart.dev).

5. Haz clic en Crear editor (Create Publisher).

6. En el cuadro de diálogo de confirmación, selecciona Aceptar (OK).

7. Si se te solicita, completa el flujo de verificación. Esto abre la Google Search Console.

   • Al agregar registros DNS, es posible que pasen algunas horas antes de que la Search Console refleje los cambios.
   • Cuando se complete el flujo de verificación, regresa al paso 4.

Usa el comando dart pub publish para publicar tu paquete por primera vez o para actualizarlo a una nueva versión.

El paquete publicado incluye todos los archivos del directorio raíz del paquete, con las siguientes excepciones:

• Cualquier archivo o directorio oculto. Estos tienen nombres que comienzan con un punto (.).
• Los archivos y directorios enumerados para ser ignorados en un archivo .pubignore o .gitignore

Para usar diferentes reglas de exclusión para git y dart pub publish, crea un archivo .pubignore para anular el archivo .gitignore en un directorio determinado. Si un directorio contiene tanto un archivo .pubignore como un archivo .gitignore, entonces dart pub publish ignora el archivo .gitignore de ese directorio. Los archivos .pubignore siguen el mismo formato que el archivo .gitignore.

Para evitar publicar archivos no deseados, sigue estas prácticas:

• Elimina cualquier archivo que no desees incluir o agrégalo a un archivo .pubignore o .gitignore.
• Al cargar tu paquete, examina la lista de archivos que muestra dart pub publish --dry-run que se publicarán. Cancela la carga si aparece algún archivo no deseado en esa lista.

Para probar cómo funcionará dart pub publish, puedes realizar una simulación (dry run):

$ dart pub publish --dry-run

Con este comando, dart pub realiza las siguientes tareas:

1. Verifica que tu paquete siga el formato de pubspec y las convenciones de diseño de paquetes (package layout).

2. Muestra todos los archivos que tiene la intención de publicar.

El siguiente ejemplo muestra la prueba de publicación de un paquete llamado transmogrify:

Publishing transmogrify 1.0.0
    .gitignore
    CHANGELOG.md
    README.md
    lib
        transmogrify.dart
        src
            transmogrifier.dart
            transmogrification.dart
    pubspec.yaml
    test
        transmogrify_test.dart

Package has 0 warnings.

Para publicar tu paquete cuando esté listo, elimina el argumento --dry-run:

$ dart pub publish

Con este comando, dart pub realiza las siguientes tareas:

1. Verifica que tu paquete siga el formato de pubspec y las convenciones de diseño de paquetes (package layout).

2. Valida que git status esté limpio. Advierte si los archivos rastreados en git tienen cambios sin registrar (uncommitted).

3. Muestra todos los archivos que tiene la intención de publicar.

4. Carga tu paquete en pub.dev.

Después de que tu paquete se cargue correctamente en pub.dev, cualquier usuario de pub puede descargarlo o depender de él en sus proyectos.

Por ejemplo, si acabas de publicar la versión 1.0.0 de tu paquete transmogrify, entonces otro desarrollador de Dart puede agregarlo como una dependencia en su pubspec.yaml:

dependencies:
  transmogrify: ^1.0.0

El sitio pub.dev detecta qué plataformas admite un paquete, mostrando estas plataformas en la página del paquete. Los usuarios de pub.dev pueden filtrar las búsquedas por plataforma.

Para cambiar la lista generada de plataformas compatibles, especifica las plataformas compatibles en el archivo pubspec.yaml.

Una vez que hayas publicado la primera versión de un paquete, puedes configurar la publicación automatizada a través de GitHub Actions o cuentas de servicio de Google Cloud. Para obtener más información sobre la publicación automatizada, consulta Publicación automatizada de paquetes en pub.dev.

A medida que trabajas en un paquete, considera publicarlo como una versión preliminar (prerelease). Las versiones preliminares pueden ser útiles cuando:

• Estás desarrollando activamente la próxima versión mayor del paquete.
• Quieres probadores beta para la próxima candidata a lanzamiento (release candidate) del paquete.
• El paquete depende de una versión inestable del SDK de Dart o Flutter.

Como se describe en el versionamiento semántico, para hacer una versión preliminar de una versión, agrega un sufijo a la versión. Por ejemplo, para hacer una versión preliminar de la versión 2.0.0, podrías usar la versión 2.0.0-dev.1. Más tarde, cuando lances la versión 2.0.0, esta tendrá prioridad sobre todas las versiones preliminares 2.0.0-XXX.

Dado que pub prefiere los lanzamientos estables cuando están disponibles, es posible que los usuarios de un paquete preliminar necesiten cambiar sus restricciones de dependencia. Por ejemplo, si un usuario desea probar las versiones preliminares de la versión 2.1.0, entonces en lugar de ^2.0.0 o ^2.1.0 podría especificar ^2.1.0-dev.1.

Cuando publicas una versión preliminar en pub.dev, la página del paquete muestra enlaces tanto a la versión preliminar como al lanzamiento estable. La versión preliminar no afecta la puntuación de análisis, no aparece en los resultados de búsqueda ni reemplaza el archivo README.md ni la documentación del paquete.

Las vistas previas (previews) pueden ser útiles cuando se cumplen todas las condiciones siguientes:

• La próxima versión estable del paquete está completa.
• Esa versión del paquete depende de una API o característica en el SDK de Dart que aún no se ha lanzado en una versión estable del SDK de Dart.
• Sabes que la API o característica de la que depende el paquete es estable a nivel de API y no cambiará antes de llegar al SDK estable.

Como ejemplo, considera una nueva versión de package:args que tiene una versión finalizada 2.0.0. Depende de una característica en Dart 3.0.0-417.1.beta. Sin embargo, la versión estable del SDK de Dart 3.0.0 no se ha lanzado. El archivo pubspec.yaml podría verse así:

name: args
version: 2.0.0
​
environment:
  sdk: '^3.0.0-417.1.beta'

Cuando publicas este paquete en pub.dev, se etiqueta como una versión de vista previa (preview). La siguiente captura de pantalla ilustra esto. Enumera la versión estable como 1.6.0 y la versión de vista previa como 2.0.0.

Cuando Dart lanza la versión estable de 3.0.0, pub.dev actualiza el listado del paquete para mostrar 2.0.0 como la última versión (estable) del paquete.

Si se cumplen todas las condiciones al principio de esta sección, ignora la siguiente advertencia de dart pub publish:

"Los paquetes con una restricción de SDK en una versión preliminar del SDK de Dart deben publicarse ellos mismos como una versión preliminar. Si este paquete necesita la versión 3.0.0-0 de Dart, considera publicar el paquete como una versión preliminar en su lugar."

Si un paquete tiene un editor verificado, la página de pub.dev para ese paquete muestra el dominio del editor.

Para los paquetes publicados sin un editor, pub.dev no revela el editor por razones de privacidad. El campo Publisher (Editor) muestra "unverified uploader" (cargador no verificado).

Quienquiera que publique la primera versión de un paquete se convierte en la primera y única persona autorizada para cargar versiones adicionales de ese paquete.

Para permitir o no que otras personas carguen versiones, ya sea:

• Gestiona los cargadores autorizados en la página de administración del paquete: https://pub.dev/packages/<package>/admin.
• Transfiere el paquete a un editor verificado; todos los miembros de un editor están autorizados para realizar cargas.

Para transferir un paquete a un editor verificado, debes ser un cargador (uploader) del paquete y un administrador del editor verificado.

Para transferir un paquete a un editor verificado:

1. Inicia sesión en pub.dev con una cuenta de Google que figure como cargador del paquete.

2. Ve a la página de detalles del paquete (por ejemplo, https://pub.dev/packages/http).

3. Selecciona la pestaña Admin (Administración).

4. Introduce el nombre del editor y haz clic en Transferir al editor (Transfer to Publisher).

Para evitar que nuevos consumidores de paquetes adopten una versión publicada de tu paquete dentro de una ventana de siete días, puedes retirar (retract) esa versión del paquete dentro de los siete días posteriores a su publicación. La versión retirada se puede restaurar nuevamente dentro de los siete días posteriores al retiro.

El retiro (retraction) no es una eliminación. Una versión de paquete retirada aparece en la lista de versiones del paquete en pub.dev en la sección Retracted versions (Versiones retiradas). La vista detallada de esa versión del paquete muestra una insignia RETRACTED (RETIRADA).

Antes de retirar un paquete, considera publicar una nueva versión en su lugar. Retirar un paquete puede tener un impacto negativo en los usuarios del paquete.

Si publicas una nueva versión con una restricción de dependencia faltante o una restricción de dependencia laxa, entonces retirar la versión del paquete podría ser la única solución. Publicar una versión más nueva de tu paquete no impedirá que el solucionador de versiones elija la versión anterior. Esa versión podría ser la única que pub pueda elegir. Retirar una versión de paquete con restricciones de dependencia incorrectas obliga a los usuarios a actualizar otras dependencias o a obtener un conflicto de dependencias.

Sin embargo, si tu paquete contiene un error menor, es posible que no necesites retirar la versión. Publica una versión más nueva con el error corregido y una descripción del error corregido en el CHANGELOG.md. Esto ayuda a los usuarios a comprender lo sucedido. Publicar una versión más nueva es menos disruptivo para los usuarios de paquetes.

Si un paquete depende de la versión de un paquete que luego se retira (retracted), aún puede usar esa versión siempre que dicha versión se encuentre en el archivo pubspec.lock del paquete dependiente. Para depender de una versión específica que ya ha sido retirada, el paquete dependiente debe fijar (pin) la versión en la sección dependency_overrides del archivo pubspec.yaml.

Cuando un paquete depende de una versión de paquete retirada, tienes opciones sobre cómo migrar para dejar de usar esta versión, dependiendo de otras versiones disponibles.

En la mayoría de los casos, se ha publicado una versión más nueva para reemplazar la versión retirada. En este caso, ejecuta dart pub upgrade <package>.

Si no hay una versión más nueva disponible, considera degradar a la versión más reciente no retirada. Puedes hacerlo de una de las dos formas siguientes.

1. Usa los comandos de la herramienta pub:

   1. Ejecuta dart pub downgrade <package> para obtener la versión más baja del paquete especificado que coincida con las restricciones en el archivo pubspec.yaml.

   2. Ejecuta dart pub upgrade <package> para obtener la versión compatible y no retirada más reciente disponible.

2. Edita el archivo pubspec.lock en tu IDE preferido:

   1. Elimina la entrada completa del paquete para el paquete con la versión retirada.

   2. Ejecuta dart pub get para obtener la versión compatible y no retirada más reciente disponible.

Aunque podrías eliminar el archivo pubspec.lock y ejecutar dart pub get, no se recomienda esto. Podría dar lugar a cambios de versión para otras dependencias.

Si no hay una versión alternativa disponible que satisfaga la restricción de versión actual, edita la restricción de versión en el archivo pubspec.yaml y ejecuta dart pub upgrade.

Para retirar o restaurar la versión de un paquete, primero inicia sesión en pub.dev utilizando una cuenta de Google que sea cargador (uploader) o administrador de un editor verificado del paquete. Luego ve a la pestaña Admin (Administración) del paquete, donde puedes retirar o restaurar versiones recientes del paquete.

Aunque los paquetes sigan publicados, puedes indicar a los desarrolladores que un paquete no recibe mantenimiento activo. Esto requiere que marques el paquete como descontinuado (discontinued).

Una vez que descontinúas un paquete, el paquete:

• Permanecerá publicado en pub.dev.
• Permanecerá visible en pub.dev.
• Muestra una insignia clara de DESCONTINUADO (DISCONTINUED).
• No aparecerá en los resultados de búsqueda de pub.dev.

Para marcar un paquete como descontinuado:

1. Inicia sesión en pub.dev utilizando una cuenta de Google con permisos de cargador o de editor verificado para el paquete.

2. Navega a la pestaña Admin (Administración) del paquete.

3. Para descontinuar un paquete, selecciona Marcar "descontinuado" (Mark "discontinued").

También puedes recomendar un paquete de reemplazo.

1. En el campo debajo de Reemplazo sugerido (Suggested replacement), escribe el nombre de otro paquete.

2. Haz clic en Actualizar "Reemplazo sugerido" (Update "Suggested Replacement").

Si cambias de opinión, puedes quitar la marca de descontinuado en cualquier momento.