Publishing packages

    Note: To publish to a location other than pub.dev, or to prevent publication anywhere, use the publish_to field, as defined in the .

    When publishing a package, it’s important to follow the pubspecformat and.Some of these are required in order for others to be able to use your package.Others are suggestions to help make it easier for users to understand and workwith your package. In both cases, pub tries to help you by pointing out whatchanges will help make your package play nicer with the Dart ecosystem. Thereare a few additional requirements for uploading a package:

    • Your package must be less than 10 MB large after gzip compression. Ifit’s too large, consider splitting it into multiple packages, or cutting downon the number of included resources or examples.

    • Your package should depend only on hosted dependencies (from the default pubpackage server) and SDK dependencies (sdk: flutter). These restrictionsensure that dependencies of your packages cannot become unavailable in thefuture.

    • You must have a Google Account,which pub uses to manage package upload permissions.Your Google Account can be associated with a Gmail address orwith any other email address.

    Note: Unless you publish using a , pub.dev displays the email address associated with your Google Account.

    Pub uses the contents of a few files to create a page for yourpackage at pub.dev/packages/<your_package>. Here are the files thataffect how your package’s page looks:

    • README: The README file (README, README.md, README.mdown,README.markdown) is the main content featured in your package’s page.
    • CHANGELOG: Your package’s CHANGELOG (CHANGELOG, CHANGELOG.md,, CHANGELOG.markdown), if found, is also featured in atab on your package’s page, so that developers can read it right frompub.dev.
    • The pubspec: Your package’s pubspec.yaml file is used to fill outdetails about your package on the right side of your package’s page, like itsdescription, homepage, etc.

    Advantages of using a verified publisher

    You can publish packages using either a verified publisher (recommended)or an independent Google Account.Using a verified publisher has the following advantages:

    • The consumers of your package know that the publisher domain has been verified.
    • You can avoid having pub.dev display your personal email address.Instead, pub.dev displays displays the publisher domain and contact address.
    • A verified publisher badge is displayed next to your package nameon both search pages and individual package pages.

    To create a verified publisher, follow these steps:

    • Go to pub.dev.

    • Log in to pub.dev using a Google Account.

    • Enter the domain name that you want to associate with your publisher (for example,dart.dev), and click Create Publisher.

    • In the confirmation dialog, select OK.

    Publishing your package

    Use the command to publish your package for the first time,or to update it to a new version.

    Performing a dry run

    To test how pub publish will work, you can perform a dry run:

    Pub makes sure that your package follows thepubspec format and,and then uploads your package to pub.dev. Pub also shows you all ofthe files it intends to publish. Here’s an example of publishing a packagenamed transmogrify:

    When you’re ready to publish your package, remove the —dry-run argument:

    Note: The pub command currently doesn’t support publishing a new package directly to a verified publisher. As a temporary workaround, publish new packages to a Google Account, and then .

    Once a package has been transferred to a publisher, you can update the package using pub publish.

    After your package has been successfully uploaded to pub.dev, any pub user candownload it or depend on it in their projects. For example, if you justpublished version 1.0.0 of your transmogrify package, then another Dartdeveloper can add it as a dependency in their pubspec.yaml:

    Transferring a package to a verified publisher

    To transfer a package to a verified publisher,you must be an uploader for the packageand an admin for the verified publisher.

    Note: This process isn’t reversible. Once you transfer a package to a publisher, you can’t transfer it back to an individual account.

    • Log in to with a Google Account that’s listed asan uploader of the package.
    • Go to the package details page (for example,https://pub.dev/packages/http).
    • Select the Admin tab.
    • Enter the name of the publisher, and click Transfer to Publisher.

    All files in your package are included in the published package, withthe following exceptions:

    • Any directories.
    • Your package’s .
    • If you aren’t using Git, all hidden files (that is,files whose names begin with .).
    • If you’re using Git, any files ignored by your .gitignore file.

    Be sure to delete any files you don’t want to include (or add them to.gitignore). pub publish lists all files that it’s going to publishbefore uploading your package,so examine the list carefully before completing your upload.

    Uploaders

    Whoever publishes the first version of a package automatically becomesthe first and only person authorized to upload additional versions of that package.To allow or disallow other people to upload versions,use the pub uploader commandor transfer the package to a .

    If a package has a verified publisher,then the pub.dev page for that package displays the publisher domain.Otherwise, the page displays the email addresses ofthe authorized uploaders for the package.

    As you work on a package, consider publishing it as a prerelease.Prereleases can be useful when any of the following are true:

    • You’re actively developing the next major version of the package.
    • You want beta testers for the next release candidate of the package.
    • The package depends on an unstable version of the Dart or Flutter SDK.

    As described in semantic versioning, to make a prerelease of a versionyou append a suffix to the version. For example, to make a prerelease ofversion 2.0.0 you might use the version 2.0.0-dev.1. Later, when yourelease version 2.0.0, it will take precedence over all 2.0.0-XXX prereleases.

    Because pub prefers stable releases when available, users of a prerelease packagemight need to change their dependency constraints.For example, if a user wants to test prereleases of version 2.1, theninstead of ^2.0.0 or ^2.1.0 they might specify ^2.1.0-dev.1.

    Note: If a stable package in the dependency graph depends on a prerelease, then pub chooses that prerelease instead of a stable release.

    When a prerelease is published to pub.dev,the package page displays links to both the prerelease and the stable release.The prerelease doesn’t affect the analysis score, show up in search results,or replace the package README and documentation.

    Publishing is forever

    Keep in mind that publishing is forever. As soon as you publish your package,users can depend on it. Once they start doing that, removingthe package would break theirs. To avoid that, pub strongly discouragesdeleting packages. You can always upload new versions of your package, butold ones will continue to be available for users that aren’t ready toupgrade yet.

    Although packages always remain published, it can be useful to signal todevelopers that a package is no longer being actively maintained.For this, you can mark a package as discontinued.A discontinued package remains published and viewable on pub.dev,but it has a clear DISCONTINUED badge anddoesn’t appear in pub.dev search results.

    To mark a package as discontinued, sign in to pub.dev using a Google Accountthat’s an uploader or verified publisher admin for the package.Then use the Admin tab of the individual package to mark the package asdiscontinued.

    Resources