Custom package repositories
- Authenticating with a custom package repository
- Retrieving dependencies from a custom package repository
- Publishing to a custom package repository
- Setting up a custom package repository
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
Sometimes a custom package repository might be useful for hosting private packages, including in some of the following scenarios:
- Sharing internal proprietary packages within an organization.
- Tight control of dependencies in enterprise environments.
- Secure environments without public internet access.
It’s also common to use git-dependencies
for hosting private packages, however,
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.
Authenticating with a custom package repository
Most custom package repositories are
private package repositories that require authentication.
To authenticate against custom package repositories,
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,
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
$ 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
This reduces the risk that secrets are accidentally leaked
if the execution environment is shared between CI jobs.
Retrieving dependencies from a custom package repository
To fetch a package from custom package repository,
you must specify the hosted-url for the package in
using the syntax for hosted packages.
dependencies: example_package: hosted: https://dart-packages.example.com version: ^1.4.0
In the previous example,
is fetched from
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
--hosted flag to add a dependency from a custom package repository:
$ dart pub add example_package --hosted https://dart-packages.example.com
Using multiple package repositories
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
meta from pub.dev,
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.
Publishing to a custom package repository
To publish a package to a custom package repository
instead of pub.dev,
publish_to property in
If authentication is enabled,
publishing uses the same token authentication
as retrieving packages.
To prepare a package for publishing to
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,
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 ...
Overriding the default package repository
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.
Setting up a custom package repository
You can write a custom package repository by implementing the REST API outlined in the Hosted Pub Repository Specification Version 2.
Dart package repositories as a service
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: