Installing Packages

Learn how to install and use private packages from your Game Framework registry in Flutter projects.

Quick Start

Install a Package

Add your private package to pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  
  # Private package from Game Framework
  my_auth_package:
    hosted:
      name: my_auth_package
      url: https://registry.yourcompany.com
    version: ^1.0.0

Run:

flutter pub get

Installation Methods

Specify registry per package:

dependencies:
  my_private_package:
    hosted:
      name: my_private_package
      url: https://registry.yourcompany.com
    version: ^2.1.0

Advantages:

Explicit registry per package
Mix public and private easily
No global configuration needed

Set PUB_HOSTED_URL environment variable:

export PUB_HOSTED_URL="https://registry.yourcompany.com"

Then use simple syntax:

dependencies:
  my_private_package: ^2.1.0

Advantages:

Cleaner pubspec.yaml
Team-wide consistency
Less configuration

Use semantic versioning constraints:

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'
  
  # Any version
  package_d: any

Using Installed Packages

Import in Your Code

import 'package:my_auth_package/my_auth_package.dart';

void main() {
  final auth = AuthService();
  auth.login('user@example.com', 'password');
}

Check Installed Version

# List all dependencies
flutter pub deps

# Show outdated packages
flutter pub outdated

# Get package info
flutter pub deps --style=compact | grep my_auth_package

Authentication Setup

For Development

Set your user token:

export GF_PUB_TOKEN="gf_live_your_token_here"

Create ~/.pub-cache/pub-tokens.json:

{
  "version": 1,
  "hosted": [
    {
      "url": "https://registry.yourcompany.com",
      "token": "${GF_PUB_TOKEN}",
      "env": "GF_PUB_TOKEN"
    }
  ]
}

For Team Members

Share setup script:

#!/bin/bash
# setup_registry.sh

echo "Setting up Game Framework registry..."

# Create pub-tokens.json
mkdir -p ~/.pub-cache
cat > ~/.pub-cache/pub-tokens.json << 'EOF'
{
  "version": 1,
  "hosted": [
    {
      "url": "https://registry.yourcompany.com",
      "token": "${GF_PUB_TOKEN}",
      "env": "GF_PUB_TOKEN"
    }
  ]
}
EOF

echo "✓ Registry configured!"
echo "⚠️  Set your token: export GF_PUB_TOKEN=your_token_here"

Mixed Dependencies (Public + Private)

Use both pub.dev and private packages:

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

When using mixed dependencies, always specify the hosted URL for private packages.

Dependency Management

Update Packages

# Update all dependencies
flutter pub upgrade

# Update specific package
flutter pub upgrade my_auth_package

# Get latest compatible versions
flutter pub upgrade --major-versions

Lock Dependencies

Use pubspec.lock for consistent builds:

# Commit pubspec.lock to Git
git add pubspec.lock
git commit -m "Lock dependencies"

Best Practice: Always commit pubspec.lock to ensure team uses same package versions.

Dependency Overrides

Force specific versions when needed:

dependency_overrides:
  my_auth_package: 2.1.0

Version Resolution

Understanding Version Constraints

Flutter uses pub's version resolution algorithm:

dependencies:
  # ^1.2.3 means >= 1.2.3 < 2.0.0
  package_a: ^1.2.3
  
  # This is equivalent to:
  package_a: '>=1.2.3 <2.0.0'

Solving Version Conflicts

If packages have conflicting dependencies:

Because package_a depends on http ^0.13.0 and package_b depends on http ^1.0.0, 
package_a is incompatible with package_b.

Solutions:

Update packages to compatible versions
Use dependency_overrides (temporary fix)
Fork and update package

dependency_overrides:
  http: ^1.0.0  # Force version for all packages

Private Dependencies of Private Packages

When your private package depends on other private packages:

# In my_ui_package/pubspec.yaml
name: my_ui_package
version: 1.0.0

dependencies:
  flutter:
    sdk: flutter
  
  # Another private package
  my_auth_package:
    hosted:
      name: my_auth_package
      url: https://registry.yourcompany.com
    version: ^2.0.0

Users installing my_ui_package need access to my_auth_package too.

Important: Ensure all team members have permissions for transitive private dependencies.

Development Dependencies

Adding Dev Dependencies

dev_dependencies:
  flutter_test:
    sdk: flutter
  
  # Private testing utilities
  company_test_utils:
    hosted:
      name: company_test_utils
      url: https://registry.yourcompany.com
    version: ^1.0.0
  
  # Public dev tools
  build_runner: ^2.4.0
  flutter_lints: ^3.0.0

Dev dependencies are not included in published packages.

Caching and Performance

Clear Pub Cache

If you encounter issues:

# Clear entire cache
flutter pub cache clean

# Clear and reinstall
flutter pub cache clean && flutter pub get

# Repair cache
flutter pub cache repair

Pub Cache Location

# Default locations:
# macOS/Linux: ~/.pub-cache
# Windows: %APPDATA%\Pub\Cache

# View cache
ls ~/.pub-cache/hosted/registry.yourcompany.com/

Offline Mode

Download for Offline Use

# Pre-download all dependencies
flutter pub get

# Use offline (skips network checks)
flutter pub get --offline

Troubleshooting

"Package not found"

Check:

Package name is correct
Registry URL is correct
Authentication token is set
You have permission to access package

# Test manually
curl -H "Authorization: Bearer $GF_PUB_TOKEN" \
  https://registry.yourcompany.com/v1/packages/my_package

"Version solving failed"

Common causes:

Version constraints too restrictive
Conflicting dependencies
Package doesn't exist in specified version

# See detailed resolution
flutter pub get --verbose

# Try latest versions
flutter pub upgrade --major-versions

"Unauthorized"

Authentication issues:

# Check token is set
echo $GF_PUB_TOKEN

# Verify token works
curl -H "Authorization: Bearer $GF_PUB_TOKEN" \
  https://registry.yourcompany.com/v1/me

Best Practices

1. Pin Critical Dependencies

For production apps, use exact versions for critical packages:

dependencies:
  company_auth: 2.1.5  # Exact version
  company_ui: ^1.5.0   # Allow patches

2. Regular Updates

Keep dependencies up to date:

# Weekly
flutter pub outdated
flutter pub upgrade

# Monthly  
flutter pub upgrade --major-versions

3. Security Scanning

Check for vulnerabilities:

# Audit dependencies
flutter pub deps --style=compact

# Check specific package
flutter pub deps --style=list | grep package_name

4. Document Private Packages

In your README:

## Installation

This project uses private packages from our internal registry.

### Setup

1. Get registry access token from IT
2. Configure Flutter CLI:
   \`\`\`bash
   export GF_PUB_TOKEN="your_token"
   \`\`\`
3. Run \`flutter pub get\`

Next Steps

Publishing Packages - Publish your own packages
CI/CD Integration - Automate dependency management
Pubspec Configuration - Advanced pubspec options

Need help? Check troubleshooting guide or contact support.

On this page