Publishing Packages

Learn how to publish your Flutter packages to your private Game Framework registry.

Before You Publish

Package Requirements

Ensure your package meets these requirements:

Valid pubspec.yaml

Your pubspec.yaml must include:

name: my_package  # Required: package name
version: 1.0.0   # Required: semantic version
description: A brief description  # Required: at least 60 characters
homepage: https://github.com/company/my_package  # Optional but recommended

environment:
  sdk: '>=3.0.0 <4.0.0'  # Required: Dart SDK constraints
  flutter: ">=3.10.0"     # Required for Flutter packages

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0

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

Important: Set publish_to to prevent accidental publishing to pub.dev!

README.md

Include a comprehensive README with:

Package description and purpose
Installation instructions
Usage examples
API documentation link

# my_package

A Flutter package for authentication and authorization.

## Installation

\`\`\`yaml
dependencies:
  my_package:
    hosted:
      name: my_package
      url: https://registry.yourcompany.com
    version: ^1.0.0
\`\`\`

## Usage

\`\`\`dart
import 'package:my_package/my_package.dart';

void main() {
  // Your code here
}
\`\`\`

CHANGELOG.md

Document all changes:

## 1.0.0

- Initial release
- Added authentication features
- Implemented token refresh

LICENSE

Include a license file (required):

MIT License

Copyright (c) 2025 Your Company

Permission is hereby granted, free of charge, to any person obtaining a copy...

Package Validation

Run pub's validation check:

# Dry run to check for issues
flutter pub publish --dry-run

This checks for:

Valid pubspec.yaml
Required files (README, CHANGELOG, LICENSE)
No warnings or errors
Package size limits

Publishing Your First Version

Configure Authentication

Set your Game Framework token:

export GF_PUB_TOKEN="gf_live_your_token_here"

Or add to your credentials file (~/.pub-cache/pub-tokens.json):

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

Run Validation

# Check for issues
flutter pub publish --dry-run --server=https://registry.yourcompany.com

Fix any warnings or errors before proceeding.

Publish

# Publish to your private registry
flutter pub publish --server=https://registry.yourcompany.com

Output:

Publishing my_package 1.0.0 to https://registry.yourcompany.com:

|-- .gitignore
|-- .metadata
|-- CHANGELOG.md
|-- LICENSE
|-- README.md
|-- lib
|   '-- my_package.dart
|-- pubspec.yaml
'-- test
    '-- my_package_test.dart

Looks great! Are you ready to upload your package (y/N)? y

Uploading...
Successfully uploaded package.

Verify Publication

Check your package is available:

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

# Or try installing it
flutter pub add my_package:^1.0.0 --hosted=https://registry.yourcompany.com

🎉 Package published! It's now available to your team.

Publishing Updates

When you need to publish a new version:

Update Version Number

Follow semantic versioning:

Patch (1.0.1): Bug fixes, no API changes
Minor (1.1.0): New features, backward compatible
Major (2.0.0): Breaking changes

# pubspec.yaml
version: 1.1.0  # Increment appropriately

Update CHANGELOG

Document your changes:

## 1.1.0

### Added
- New authentication method for OAuth
- Support for refresh tokens

### Changed
- Improved error handling

### Fixed
- Token expiration bug

Publish New Version

flutter pub publish --server=https://registry.yourcompany.com

Publishing Options

Force Publish (Skip Confirmation)

For CI/CD pipelines:

flutter pub publish --force --server=https://registry.yourcompany.com

Warning: Only use --force in automated environments. Always review changes manually during development.

Dry Run Only

Test without actually publishing:

flutter pub publish --dry-run --server=https://registry.yourcompany.com

Custom Server

Override registry URL:

flutter pub publish --server=https://staging-registry.yourcompany.com

Publishing from Monorepos

If you have multiple packages in a monorepo:

my_project/
├── packages/
│   ├── auth/
│   │   └── pubspec.yaml
│   ├── ui/
│   │   └── pubspec.yaml
│   └── utils/
│       └── pubspec.yaml

Publish All Packages

#!/bin/bash
# publish_all.sh

PACKAGES=("auth" "ui" "utils")
REGISTRY="https://registry.yourcompany.com"

for pkg in "${PACKAGES[@]}"; do
  echo "Publishing $pkg..."
  cd "packages/$pkg"
  flutter pub publish --force --server=$REGISTRY
  cd ../..
done

Publish with Dependencies

Ensure you publish in dependency order:

# 1. Publish utils (no dependencies)
cd packages/utils && flutter pub publish --force --server=https://registry.yourcompany.com

# 2. Publish auth (depends on utils)
cd ../auth && flutter pub publish --force --server=https://registry.yourcompany.com

# 3. Publish ui (depends on auth and utils)
cd ../ui && flutter pub publish --force --server=https://registry.yourcompany.com

CI/CD Publishing

GitHub Actions

name: Publish Package

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.16.0'
          channel: 'stable'
      
      - name: Install dependencies
        run: flutter pub get
      
      - name: Run tests
        run: flutter test
      
      - name: Publish to Game Framework
        env:
          GF_PUB_TOKEN: ${{ secrets.GAME_FRAMEWORK_TOKEN }}
        run: |
          mkdir -p ~/.pub-cache
          echo '{"version":1,"hosted":[{"url":"https://registry.yourcompany.com","token":"${GF_PUB_TOKEN}","env":"GF_PUB_TOKEN"}]}' > ~/.pub-cache/pub-tokens.json
          flutter pub publish --force --server=https://registry.yourcompany.com

GitLab CI

publish:
  stage: deploy
  image: cirrusci/flutter:stable
  only:
    - tags
  script:
    - export GF_PUB_TOKEN=$GAME_FRAMEWORK_TOKEN
    - mkdir -p ~/.pub-cache
    - echo '{"version":1,"hosted":[{"url":"https://registry.yourcompany.com","token":"${GF_PUB_TOKEN}","env":"GF_PUB_TOKEN"}]}' > ~/.pub-cache/pub-tokens.json
    - flutter pub get
    - flutter test
    - flutter pub publish --force --server=https://registry.yourcompany.com

See CI/CD Integration Guide for more examples.

Package Metadata

Setting Package Metadata

Add metadata in pubspec.yaml:

name: my_package
version: 1.0.0
description: Detailed package description (minimum 60 characters)

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

topics:
  - authentication
  - security
  - flutter

screenshots:
  - description: 'Login screen'
    path: screenshots/login.png
  - description: 'Dashboard'
    path: screenshots/dashboard.png

Funding Links

Support open source contributions:

funding:
  - https://github.com/sponsors/your-username
  - https://www.buymeacoffee.com/your-username

Best Practices

1. Version Management

Use a consistent versioning strategy:

# Install a version management tool
dart pub global activate cider

# Bump versions easily
cider bump patch  # 1.0.0 -> 1.0.1
cider bump minor  # 1.0.0 -> 1.1.0
cider bump major  # 1.0.0 -> 2.0.0

2. Pre-publish Checklist

Before publishing, verify:

3. Git Tags

Tag releases in Git:

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

4. Release Notes

Create GitHub releases with:

Version number
CHANGELOG excerpt
Breaking changes
Migration guide (for major versions)

Troubleshooting

"Package already exists"

You cannot republish the same version:

Error: Version 1.0.0 of my_package already exists.

Solution: Increment version in pubspec.yaml

"Unauthorized"

Authentication failed:

Error: Unauthorized - authentication required

Solutions:

Check token is set: echo $GF_PUB_TOKEN
Verify token is valid
Ensure you have packages.create permission

"Package validation failed"

Fix all validation errors:

flutter pub publish --dry-run --server=https://registry.yourcompany.com

Common issues:

Missing LICENSE file
Description too short (< 60 chars)
Invalid version format
Missing dependencies

"File too large"

Package exceeds size limit:

Error: Package archive exceeds maximum size of 100 MB

Solutions:

Add large files to .pubignore
Remove unnecessary assets
Use .gitattributes for Git LFS

Package Size Optimization

.pubignore File

Exclude files from package:

# .pubignore
*.dart.js
*.dart.js.map
.dart_tool/
.packages
build/
test/
example/
*.log

Check Package Size

# See what will be included
flutter pub publish --dry-run

# Package size shown in output
Package archive: 234 KB

Next Steps

Installing Packages - Use your published packages
Versioning Strategy - Version management best practices
CI/CD Integration - Automate publishing

Questions? See our FAQ or contact support.

On this page