How to Publish Your First Package on PubDev

admin

barysol
Flutter
How to Publish Your First Package on PubDev

CLI

Prerequisites: Setting Up Your Dart and Flutter Environment

Before publishing, ensure your development environment is fully configured. You need Dart SDK version 2.12.0 or higher (preferably the latest stable release) and a Pub.dev account. Verify your Dart installation by running dart --version in your terminal. If you’re developing Flutter packages, ensure Flutter SDK 2.0.0 or later is installed. Create a Pub.dev account by visiting pub.dev and signing in with your Google account—this is mandatory because Pub.dev uses Google authentication for package management. Additionally, configure your Git credentials locally with git config --global user.name "Your Name" and git config --global user.email "your.email@example.com", as Pub.dev relies on Git for version tracking and package metadata extraction.

Structuring Your Package: The `pubspec.yaml` File

The pubspec.yaml serves as your package’s identity card. Use dart create or flutter create --template=package to generate a skeleton. Key fields include: name (lowercase, underscore-separated, unique on Pub.dev—check availability beforehand), version (follow semantic versioning: 1.0.0 for initial stable release), description (concise, under 180 characters, highlighting core functionality), homepage (URL to repository or documentation), and repository (direct link to source code, e.g., GitHub). Define dependencies in the dependencies and dev_dependencies sections. Avoid using dependency_overrides for published packages. If your package supports multiple platforms, specify platforms: with android, ios, web, etc. Use environment: to set minimum SDK constraints, e.g., sdk: ">=3.0.0 <4.0.0". A complete, valid pubspec.yaml is non-negotiable for a successful publish.

Crafting Essential Package Files

Beyond pubspec.yaml, certain files are mandatory for a well-structured package. Create a README.md with clear installation instructions (dart pub add your_package_name), a basic usage example (code block with imports and minimal working snippet), API documentation links, and contribution guidelines. Include a CHANGELOG.md that tracks each release with version numbers, dates, and lists of changes (added, fixed, changed). This builds trust with users. Add a LICENSE file—MIT, BSD-2-Clause, or Apache 2.0 are common. Avoid license-less packages; they cause legal ambiguity. Ensure your lib/ directory contains a main entry point file (e.g., lib/your_package.dart) that exports all public APIs via export statements. Organize code into subfolders under lib/src/, but never export the src/ directory directly—only re-export through the main file. This encapsulation prevents internal APIs from becoming part of your public contract.

Code Quality: Linting, Testing, and Documentation

Pub.dev automatically analyzes your package for scoring factors. Run dart analyze to catch errors and warnings. Adhere to the Dart style guide—use effective_dart or lints package for consistent formatting (enable linter: rules in analysis_options.yaml). Write comprehensive unit tests using the test package; coverage above 80% significantly boosts your package score. Place tests in the test/ directory, mirroring your lib/ structure. Document every public API with Dartdoc comments (/// triple slash). Include parameter descriptions, return values, and usage examples. Run dart doc locally to verify that documentation generates without errors. Pub.dev displays documentation automatically if you follow conventions—missing docs result in lower maintainability scores. For Flutter packages, include widget tests if you expose UI components.

Versioning and Git Integration

Pub.dev relies entirely on Git tags for release management. Initialize a Git repository in your package root (git init). Commit all files: git add . && git commit -m "Initial commit". Create version tags matching your pubspec.yaml version, prefixed with v (e.g., v1.0.0). Use annotated tags: git tag -a v1.0.0 -m "First stable release". Push the tag to your remote repository (e.g., GitHub): git push origin v1.0.0. This tag triggers CI/CD if configured, and ensures Pub.dev metadata links to the correct commit hash. Never publish a package without a corresponding Git tag. If you need to update, increment the version in pubspec.yaml, commit, tag, and push the new tag. Semantic versioning is critical—breaking changes require a major version bump (e.g., 2.0.0), new features a minor bump (1.1.0), and bug fixes a patch (1.0.1).

Pre-Publishing Dry Run: `dart pub publish --dry-run`

Before executing the actual publish, simulate the process with dart pub publish --dry-run. This command validates your package structure, checks for missing files, verifies that the pubspec.yaml is parsable, and detects any security issues like hardcoded credentials or excessive file sizes. It also shows the list of files that will be uploaded—ensure sensitive files (.env, node_modules/, test/.dart_tool/) are excluded using a .gitignore or .pubignore file. The dry run outputs warnings and errors. Fix all errors (e.g., missing homepage, invalid version). Warnings (like large example files) should be reviewed—they may lower your package score. Run the dry run multiple times until you see only a success message. For Flutter packages, also run flutter pub publish --dry-run if you used flutter create.

The Actual Publish Command

Once the dry run passes, execute the actual publish: dart pub publish (or flutter pub publish for Flutter packages). If it’s your first time, the CLI will open a browser window for Google authentication (unless you’re logged in via dart pub login). Authorize the Pub.dev website to link your account. After authentication, the CLI uploads your package, processes metadata, and prints a success message with the package URL (e.g., https://pub.dev/packages/your_package_name). If you encounter a “403 Forbidden” error, check that your Google account has not been previously used for a different package name—scoring name conflicts is possible. For “409 Conflict” errors, your version already exists—increment and tag properly. After successful publish, Pub.dev queues an analysis; your package may take 5–15 minutes to appear fully with scores and documentation.

Post-Publish: Monitoring Your Package’s Score

Within an hour of publishing, visit your package page on Pub.dev. The scoring algorithm evaluates three metrics: Popularity (download count, largely based on external usage and github stars), Health (analyzes code quality, documentation, tests, and dependency freshness), and Maintenance (looks at recent updates, resolved issues, and responsiveness). Scores range from 0 to 110. Aim for a “Maintained” badge by regularly updating your package—address deprecation warnings, support new Dart SDK versions, and respond to GitHub issues. Click the “Analysis” tab to see specific recommendations (e.g., missing platform support, outdated SDK constraints). Use pana package locally to simulate Pub.dev’s analysis: dart run pana . --no-verify. Fix reported issues before your next publish to improve your package’s discoverability.

Managing Dependencies and Version Constraints

Publishing responsibly means not accidentally breaking your users’ builds. Use ^ (caret) constraints for dependencies (e.g., http: ^1.1.0) to allow compatible upgrades. Avoid pinning exact versions (http: 1.1.0) unless absolutely necessary—this prevents users from receiving security patches for downstream dependencies. For dev_dependencies, looser constraints are acceptable. Run dart pub outdated before each publish to check for newer, stable versions of your dependencies. If you depend on third-party packages, verify they are also published on Pub.dev and not from other sources. Use dependency_overrides only for local development—never in a published package. For Flutter packages, constrain your Flutter SDK version minimally (sdk: ">=3.0.0 <4.0.0" with flutter: ">=3.10.0").

Handling Publishing for Multiple Platforms

If your package uses platform-specific APIs (e.g., file system, camera), you must declare support. In pubspec.yaml, use platforms: block:

platforms:
  android:
  ios:
  linux:
  macos:
  web:
  windows:

Place platform-specific code in separate files under lib/src/ with proper @dart =2.17 or conditional imports using export '...' if (dart.library.io). Use dart:html or package:universal_io for cross-platform consistency. Pub.dev’s analysis checks for platform conflicts—failing to declare support for a platform your code actually uses results in a “platform not supported” warning. Run dart pub publish on a CI server (e.g., GitHub Actions) with matrix builds for each platform to catch errors early.

Common Pitfalls and How to Avoid Them

Missing export files: If users cannot import 'package:your_package/your_package.dart', your package is unusable. Always create a single entry point that exports all public classes.
Forgetting .pubignore: By default, Pub.dev uploads all files except those in .gitignore. Create a .pubignore file to exclude large test fixtures, screenshots, or CI configuration files. Example:
```
.github/
test/fixtures/large/
coverage/
```
Incorrect SDK constraints: Setting sdk: ">=2.12.0 <3.0.0" prevents users with Dart 3.x from installing. Use >=3.0.0 <4.0.0 for modern packages.
No version tag: Pub.dev checks Git tags—if you publish without a tag, the version history is broken. Always tag before dart pub publish.
Overstating features: Your README.md and pubspec.description must match actual functionality. Exaggerating leads to negative reviews and low retention.

Updating Your Package: The Workflow

To publish an update, follow this exact order:

Update version in pubspec.yaml.
Add entry to CHANGELOG.md.
Commit: git add . && git commit -m "Release v1.1.0"
Tag: git tag -a v1.1.0 -m "Minor release: added new feature"
Push: git push && git push --tags
Run: dart pub publish

Avoid publishing multiple versions in quick succession—each analysis run takes time, and users prefer stable, infrequent updates. If you discover a critical bug, publish a patch version immediately. Use honeydew or gitmoji standards for commit messages to keep changelogs readable.

Leveraging Package Score for Discoverability

Pub.dev’s search algorithm prioritizes packages with high scores. To maximize your score:

Add a repository field in pubspec.yaml linking to your source code.
Include usage examples in the README and in doc comments.
Add badges to your README (CI status, code coverage, pub points).
Respond to issues within 30 days—Pub.dev tracks maintenance responsiveness.
Keep dependencies up-to-date using dart pub upgrade before each release.
Avoid descriptive conflicts like no description or using the same name as a well-known package.

A score above 100 is considered excellent; above 80 is good. Scores below 50 rarely appear in search results. Regularly revisit Pub.dev’s “Analysis” tab to identify areas for improvement—each publish recalculates your score based on the latest analysis.