Pubspec Configuration

Master advanced pubspec.yaml configurations for working with Game Framework private packages.

Basic Structure

Minimal Configuration

name: my_package
description: Package description (minimum 60 characters for publishing)
version: 1.0.0
homepage: https://github.com/company/my_package

environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: ">=3.10.0"

dependencies:
  flutter:
    sdk: flutter

# Specify your private registry
publish_to: https://registry.yourcompany.com

Complete Configuration

name: my_company_auth
description: Internal authentication library with OAuth, JWT, and biometric support
version: 2.1.5
homepage: https://github.com/company/auth
repository: https://github.com/company/auth
issue_tracker: https://github.com/company/auth/issues
documentation: https://docs.company.com/auth

# Publishing configuration
publish_to: https://registry.yourcompany.com

# SDK constraints
environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: ">=3.10.0"

# Runtime dependencies
dependencies:
  flutter:
    sdk: flutter
  
  # Private dependencies
  company_core:
    hosted:
      name: company_core
      url: https://registry.yourcompany.com
    version: ^1.5.0
  
  # Public dependencies
  http: ^1.1.0
  jwt_decoder: ^2.0.1

# Development dependencies
dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0
  build_runner: ^2.4.0

# Package metadata
topics:
  - authentication
  - security
  - oauth

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

# Funding
funding:
  - https://github.com/sponsors/company

Dependency Configuration

Private Package Dependencies

dependencies:
  # Method 1: Explicit hosted configuration
  my_auth_package:
    hosted:
      name: my_auth_package
      url: https://registry.yourcompany.com
    version: ^2.0.0
  
  # Method 2: With PUB_HOSTED_URL set
  my_ui_package: ^1.5.0  # Uses PUB_HOSTED_URL registry

Mixed Dependencies

dependencies:
  flutter:
    sdk: flutter
  
  # Private packages
  company_auth:
    hosted:
      name: company_auth
      url: https://registry.yourcompany.com
    version: ^2.1.0
  
  company_ui:
    hosted:
      name: company_ui
      url: https://registry.yourcompany.com
    version: ^1.5.0
  
  # Public packages (explicit pub.dev)
  http:
    hosted:
      name: http
      url: https://pub.dev
    version: ^1.1.0
  
  # Public packages (default)
  provider: ^6.1.0

Git Dependencies

For packages not yet published:

dependencies:
  my_package:
    git:
      url: https://github.com/company/my_package.git
      ref: main  # or specific branch/tag/commit
      path: packages/core  # for monorepos

Path Dependencies

For local development:

dependencies:
  my_package:
    path: ../my_package  # Relative path
  
  another_package:
    path: /absolute/path/to/package  # Absolute path

Important: Path dependencies are for development only. Replace with hosted/git before publishing.

Version Constraints

Semantic Versioning

dependencies:
  # Caret syntax (recommended)
  package_a: ^1.2.3  # >=1.2.3 <2.0.0
  
  # Exact version
  package_b: 1.2.3
  
  # Range
  package_c: '>=1.0.0 <2.0.0'
  package_d: '>=1.0.0 <=2.0.0'
  
  # Greater than
  package_e: '>1.0.0'
  
  # Any version (not recommended)
  package_f: any

Version Syntax Explained

Syntax	Meaning	Example	Resolves To
`^1.2.3`	Compatible with	`^1.2.3`	`>=1.2.3 <2.0.0`
`1.2.3`	Exact version	`1.2.3`	`1.2.3`
`>=1.2.3 <2.0.0`	Range	`>=1.2.3 <2.0.0`	Any version in range
`any`	Any version	`any`	Latest available

Best Practice: Use caret syntax (^1.2.3) for most dependencies. It allows bug fixes and new features while preventing breaking changes.

Publishing Configuration

Publish To Registry

# Prevent accidental publishing to pub.dev
publish_to: https://registry.yourcompany.com

# Or prevent publishing altogether
publish_to: none

Package Metadata

# Required for publishing
name: my_package
version: 1.0.0
description: A comprehensive description of at least 60 characters explaining what this package does

# Recommended
homepage: https://github.com/company/my_package
repository: https://github.com/company/my_package
issue_tracker: https://github.com/company/my_package/issues
documentation: https://docs.company.com/my_package

# Optional
topics:
  - flutter
  - authentication
  - security

funding:
  - https://github.com/sponsors/company

Environment Constraints

SDK Constraints

environment:
  # Dart SDK version
  sdk: '>=3.0.0 <4.0.0'
  
  # Flutter SDK version
  flutter: ">=3.10.0 <4.0.0"

Platform Support

Declare supported platforms:

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

# Or with specific plugin configuration
flutter:
  plugin:
    platforms:
      android:
        package: com.company.package
        pluginClass: MyPlugin
      ios:
        pluginClass: MyPlugin

Dependency Overrides

Force specific versions:

dependencies:
  package_a: ^1.0.0
  package_b: ^2.0.0  # Depends on package_c ^1.5.0

dependency_overrides:
  # Force package_c to 2.0.0 even though package_b wants 1.5.0
  package_c: 2.0.0

Use Sparingly: Dependency overrides should be temporary solutions. They can cause compatibility issues.

Development Dependencies

Standard Dev Dependencies

dev_dependencies:
  flutter_test:
    sdk: flutter
  
  # Linting
  flutter_lints: ^3.0.0
  
  # Code generation
  build_runner: ^2.4.0
  json_serializable: ^6.7.0
  
  # Testing utilities (private)
  company_test_utils:
    hosted:
      name: company_test_utils
      url: https://registry.yourcompany.com
    version: ^1.0.0
  
  # Mocking
  mockito: ^5.4.0

Flutter Configuration

Assets

flutter:
  assets:
    - assets/images/
    - assets/icons/
    - assets/config/settings.json

Fonts

flutter:
  fonts:
    - family: Roboto
      fonts:
        - asset: fonts/Roboto-Regular.ttf
        - asset: fonts/Roboto-Bold.ttf
          weight: 700

Plugin Configuration

flutter:
  plugin:
    platforms:
      android:
        package: com.company.my_plugin
        pluginClass: MyPlugin
      ios:
        pluginClass: MyPlugin
      linux:
        pluginClass: MyPlugin
      macos:
        pluginClass: MyPlugin
      web:
        pluginClass: MyPlugin
        fileName: my_plugin_web.dart
      windows:
        pluginClass: MyPlugin

Advanced Patterns

Monorepo Configuration

For packages in a monorepo:

# packages/core/pubspec.yaml
name: company_core
version: 1.0.0
publish_to: https://registry.yourcompany.com

dependencies:
  flutter:
    sdk: flutter

---

# packages/auth/pubspec.yaml
name: company_auth
version: 2.0.0
publish_to: https://registry.yourcompany.com

dependencies:
  flutter:
    sdk: flutter
  
  # Depend on another package in monorepo
  company_core:
    hosted:
      name: company_core
      url: https://registry.yourcompany.com
    version: ^1.0.0

Multi-Environment Configuration

Use different registries for different environments:

# Base pubspec.yaml
dependencies:
  company_auth:
    hosted:
      name: company_auth
      url: ${REGISTRY_URL}  # Not directly supported
    version: ^2.0.0

Use a script to generate pubspec.yaml:

#!/bin/bash
# generate_pubspec.sh

ENV=${1:-dev}

case $ENV in
  dev)
    REGISTRY="https://dev-registry.company.com"
    ;;
  staging)
    REGISTRY="https://staging-registry.company.com"
    ;;
  prod)
    REGISTRY="https://registry.company.com"
    ;;
esac

cat > pubspec.yaml << EOF
dependencies:
  company_auth:
    hosted:
      name: company_auth
      url: $REGISTRY
    version: ^2.0.0
EOF

Validation

Check Configuration

# Validate pubspec.yaml
flutter pub get --dry-run

# Check for issues before publishing
flutter pub publish --dry-run

Common Errors

Missing fields:

Error: pubspec.yaml is missing required field 'description'

Version format:

Error: Invalid version constraint: ">=3.0.0"
Expected: >=3.0.0 <4.0.0

Circular dependencies:

Error: Circular dependency detected: package_a -> package_b -> package_a

Best Practices

1. Always Set `publish_to`

# Prevent accidental publishing to pub.dev
publish_to: https://registry.yourcompany.com

2. Use Specific SDK Constraints

environment:
  sdk: '>=3.0.0 <4.0.0'  # ✓ Good - specific range
  # sdk: '>=3.0.0'        # ✗ Bad - too open

3. Document Private Dependencies

Add comments for team members:

dependencies:
  # Internal authentication library - see docs at https://docs.company.com/auth
  company_auth:
    hosted:
      name: company_auth
      url: https://registry.yourcompany.com
    version: ^2.0.0

4. Version Consistently

Use caret syntax for flexibility:

dependencies:
  package_a: ^1.2.3  # ✓ Allows updates
  package_b: 1.2.3   # ✗ Too restrictive

5. Separate Dev Dependencies

dependencies:
  # Production dependencies only
  http: ^1.1.0

dev_dependencies:
  # Development and testing only
  mockito: ^5.4.0
  build_runner: ^2.4.0

Templates

Plugin Package

name: my_plugin
description: A Flutter plugin for...
version: 1.0.0
homepage: https://github.com/company/my_plugin
publish_to: https://registry.yourcompany.com

environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: ">=3.10.0"

dependencies:
  flutter:
    sdk: flutter
  plugin_platform_interface: ^2.1.0

dev_dependencies:
  flutter_test:
    sdk: flutter

flutter:
  plugin:
    platforms:
      android:
        package: com.company.my_plugin
        pluginClass: MyPlugin
      ios:
        pluginClass: MyPlugin

Pure Dart Package

name: my_dart_package
description: A pure Dart package for...
version: 1.0.0
homepage: https://github.com/company/my_dart_package
publish_to: https://registry.yourcompany.com

environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  http: ^1.1.0

dev_dependencies:
  test: ^1.24.0
  lints: ^3.0.0

Next Steps

Publishing Packages - Publish with correct configuration
Versioning Strategy - Version management
Package Management - Package lifecycle

Need help? See troubleshooting or contact support.

On this page