Managing Dependencies with Pub

1. Configuring pubspec.yaml

Field	Description	Example
name	Package name, used in import paths and as the package identifier.	`my_flutter_app`
description	Short description of the package.	`A sample Flutter app`
version	Package version, following semantic versioning.	`1.0.0`
environment	Specifies the Dart SDK version required.	`sdk: "^3.0.0"`
dependencies	List of packages required at runtime.	`flutter: ^3.19.0`
dev_dependencies	List of packages required only for development.	`flutter_test: ^0.19.0`
flutter	Flutter-specific configuration.	`assets: - assets/images/`

Example: pubspec.yaml configuration

name: my_flutter_app
description: A sample Flutter app
version: 1.0.0

environment:
  sdk: "^3.0.0"

dependencies:
  flutter:
    sdk: flutter
  http: ^0.13.5

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^2.0.0

flutter:
  assets:
    - assets/images/

2. Adding Package Dependencies

Flutter packages are managed using the pubspec.yaml file in your project root. Dependencies are declared under the dependencies section.

Dependency Type	Declaration	Description
pub.dev package	`package_name: ^1.2.3`	Versioned package from pub.dev
Git dependency	`package_name: <br> git:<br> url: https://github.com/example/package.git<br> ref: main`	Package from a Git repository
Path dependency	`package_name: <br> path: ../local_package`	Local package from a relative path
SDK dependency	`flutter: <br> sdk: flutter`	Flutter SDK dependency (e.g. `flutter`, `flutter_test`)

Example: Adding a pub.dev package

name: my_flutter_app
description: A new Flutter project.

publish_to: 'none'

version: 1.0.0+1

environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.2
  http: ^0.13.5

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^2.0.0

flutter:
  uses-material-design: true

Note: After adding a dependency, run flutter pub get to fetch and install the package.

Warning: Avoid using ^0.0.0 in production as it can lead to breaking changes.

3. Running pub get and pub upgrade Commands

Command	Description	Usage
pub get	Fetches all dependencies listed in pubspec.yaml	`flutter pub get`
pub upgrade	Updates dependencies to the latest versions allowed by pubspec.yaml	`flutter pub upgrade`

Example: Running pub get

flutter pub get
<span class="highlight">Resolving dependencies...</span>
<span class="highlight">Downloading...</span>
<span class="highlight">Installed 20 packages</span>

Example: Running pub upgrade

flutter pub upgrade
<span class="highlight">Upgrading packages...</span>
<span class="highlight">Updated 5 packages</span>

Note: pub get ensures all dependencies are fetched and locked to versions specified in pubspec.lock. pub upgrade allows newer compatible versions to be used.

4. Using Version Constraints

Constraint Type	Example	Description
exact version	`flutter: "^3.19.0"`	Specifies the exact version to use
compatible range	`flutter: ">=3.19.0 <4.0.0"`	Allows any version within the specified range
latest compatible	`flutter: "^3.19.0"`	Allows patch and minor updates, but not major
minimum version	`flutter: ">=3.19.0"`	Requires at least the specified version
maximum version	`flutter: "<4.0.0"`	Allows versions up to but not including the specified version

Example: Specifying Version Constraints in pubspec.yaml

name: my_app
description: A new Flutter project.
publish_to: "none"

environment:
  sdk: ">=3.19.0 <4.0.0"

dependencies:
  flutter:
    sdk: flutter
  http: "^1.2.0"
  provider: ">=6.0.0"
  shared_preferences: "<2.0.0"

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: "^2.0.0"

Note: Version constraints in pubspec.yaml ensure reproducible builds and help manage dependency conflicts.

Warning: Using <2.0.0 for a dependency like shared_preferences might prevent future updates if the package moves to version 2.0.0 or higher.

5. Discovering Packages

Example: Searching for packages

flutter pub search http

Package	Description	Version	Popularity
http	HTTP client for making requests	`1.2.2`	95%
json_annotation	JSON serialization utilities	`4.9.0`	85%

Note: Use flutter pub search to find packages by keyword.

Comparison: pub.dev vs GitHub

pub.dev: Official Flutter package repository, curated and verified
GitHub: Direct access to source code, less curation but more flexibility

6. Using Dev Dependencies

Dev dependencies are packages that are only used during development and are not included in the final app build. They are useful for tools like testing frameworks, linters, and code generators.

Property	Description	Example
dev_dependencies	Defines packages used only during development.	`dev_dependencies:`

Example: Adding a dev dependency

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter
  mockito: ^5.4.0

Note: Dev dependencies are not included in the app's runtime, so they do not increase the app size or affect performance.

7. Managing Asset Dependencies

Example: Adding Asset Dependencies

flutter:
  assets:
    - assets/images/logo.png
    - assets/data/config.json
    - assets/fonts/custom-font.ttf

Property	Description	Usage
assets	List of asset files to include in the app bundle	Specify paths relative to `pubspec.yaml`
asset	Single asset file or directory	Supports glob patterns like `assets/images/*/.png`

Note: Asset files must be added to pubspec.yaml to be included in the app bundle.

Warning: Large asset files can increase app size significantly. Consider using flutter pub get to verify assets are correctly included.

Workflow: Adding Asset Dependencies

Edit pubspec.yaml to include asset paths under flutter:
Use glob patterns for directories or file types
Run flutter pub get to update dependencies
Access assets in code using AssetImage or rootBundle

8. Resolving Dependency Conflicts

Note: Dependency conflicts occur when two or more packages require different versions of the same transitive dependency.

Conflict Type	Description	Solution
Version Constraint	Two packages require different versions of a shared dependency.	Use `dependency_overrides` in `pubspec.yaml` to force a specific version.
Platform Mismatch	Package A supports Android, Package B only iOS.	Ensure all dependencies support the target platforms or use conditional dependencies.

Example: Using dependency_overrides

dependencies:
  flutter:
    sdk: flutter
  http: ^0.13.5
  provider: ^6.0.0

dependency_overrides:
  http: ^0.14.0

Steps to Resolve Conflicts

Run flutter pub get to see the conflict details.
Check the pubspec.lock file for version mismatches.
Use flutter pub deps to analyze dependency tree.
Apply dependency_overrides if necessary to enforce a compatible version.
Re-run flutter pub get to validate the fix.

Common Conflict Scenarios

Transitive dependency version mismatch — resolved via dependency_overrides.
Platform-specific dependency conflict — resolved by ensuring all packages support the same platforms.
Version range incompatibility — resolved by updating or pinning versions.

9. Updating Dependencies Safely

Example: Updating dependencies with `flutter pub upgrade`

flutter pub upgrade

Command	Description	Notes
flutter pub upgrade	Updates all dependencies to their latest versions within the version constraints specified in `pubspec.yaml`.	Does not update dependencies that are already at the latest compatible version.
flutter pub upgrade --major-versions	Updates dependencies to their latest major versions, potentially including breaking changes.	Use with caution; may require code changes to accommodate breaking changes.
flutter pub upgrade <package>	Updates a specific package to its latest version.	Useful for updating a single dependency without affecting others.

Note: Always run flutter pub get after updating dependencies to ensure all packages are correctly resolved and downloaded.

Warning: Major version updates can introduce breaking changes. Review the package's changelog before upgrading.

Best Practices for Safe Updates

Run flutter pub upgrade --major-versions with caution and review breaking changes.
Use flutter pub get after every update to ensure compatibility.
Test your app thoroughly after updating dependencies to catch any regressions or breaking changes.

10. Using Path and Git Dependencies

Dependency Type	Specification	Notes
path	`path: "../my_package"`	Local filesystem path to the package
git	`git: "https://github.com/example/my_package.git"`	Git repository URL

Example: Path Dependency

dependencies:
  my_package:
    path: ../my_package

Example: Git Dependency

dependencies:
  my_package:
    git:
      url: https://github.com/example/my_package.git
      ref: main

Note: Path dependencies are useful for local development and testing. Git dependencies allow you to pull from any Git repository, including private ones.