Custom package repositories

The dart pub tool supports third-party package repositories. A package repository is a server that hosts Dart packages for consumption by the dart pub tool. The default package repository used, pub.dev, is operated by the Dart team to facilitate publication of Dart packages for public use. A package repository is identified by a hosted-url, such as https://dart-packages.example.com/.

Sometimes a custom package repository might be useful for hosting private packages, including in some of the following scenarios:

1. Sharing internal proprietary packages within an organization.
2. Tight control of dependencies in enterprise environments.
3. Secure environments without public internet access.

It's also common to use git-dependencies for hosting private packages, however, the dart pub tool doesn't support resolving versions against a git repository; it just fetches a specific revision of the git repository. Therefore, when many people are collaborating it's often preferable to use a private package repository.

Most custom package repositories are private package repositories that require authentication. To authenticate against custom package repositories, the dart pub tool attaches a secret token to the requests.

You can obtain the secret token from your custom package repository and either specify it manually or through an environment variable. To manually specify the secret token, use the dart pub token add command which prompts for the 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.

You can also tell dart pub to read the token from an environment variable, including in a CI environment, with the --env-var flag:

$ 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".

This ensures that dart pub doesn't actually store the secret token in its configuration, instead it merely stores the fact that it should read the secret from the environment variable $MY_SECRET_TOKEN. This reduces the risk that secrets are accidentally leaked if the execution environment is shared between CI jobs.

To fetch a package from custom package repository, you must specify the hosted-url for the package in pubspec.yaml, using the syntax for hosted packages. For example:

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

In the previous example, package:example_package is fetched from https://dart-packages.example.com. If authentication is required by this package repository, see Authenticating with a custom package repository for more information on how to authenticate your requests.

You can also use the dart pub add command with the --hosted flag to add a dependency from a custom package repository:

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

You can also fetch different dependencies from different package repositories, as the hosted-url can be specified for each dependency:

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

This enables you to keep private packages on a private package repository while using the most up-to-date public packages as dependencies.

However, conflicts can easily arise if your dependencies require a package with the same name from different repositories. For example, if package retry requires meta from pub.dev, and example_package requires meta from https://dart-packages.example.com. Therefore, if mirroring any packages into a private package repository it's often necessary to mirror all dependencies and either update the dependencies section of each package, or override the default package repository.

To publish a package to a custom package repository instead of pub.dev, specify the publish_to property in pubspec.yaml. If authentication is enabled, publishing uses the same token authentication as retrieving packages.

To prepare a package for publishing to https://dart-packages.example.com, your pubspec.yaml should look minimally like the following:

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

To then publish a new version of the package, use 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
...

By default, dart pub retrieves dependencies from and publishes packages to the pub.dev site unless the hosted-dependency syntax is used to specify a custom package repository. However, you can override the default package repository using the PUB_HOSTED_URL environment variable.

This approach is particularly useful when mirroring all packages in a private package repository or a subset of pub.dev when working in a restricted network environment.

You can write a custom package repository by implementing the REST API outlined in the Hosted Pub Repository Specification Version 2.

Custom package repositories are also offered as a service with support for token authentication by multiple vendors, alleviating you from the overhead of hosting and maintaining your own custom package repository:

• Cloudsmith
• Inedo ProGet
• JFrog Artifactory
• OnePub Dart Repository

Unless stated otherwise, the documentation on this site reflects Dart 3.6.0. Page last updated on 2024-11-05. View source or report an issue.