Quick Start

Get started with Game Framework by publishing your first private Flutter package in just 5 minutes.

Prerequisites: You need a running Game Framework instance. See Installation Guide if you haven't set one up yet.

Overview

This guide will walk you through:

Creating an account and workspace
Configuring Flutter CLI to use your private registry
Publishing your first package
Installing the package in another project

Step-by-Step Guide

Create an Account

curl -X POST https://registry.yourcompany.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@yourcompany.com",
    "password": "your_secure_password",
    "name": "Your Name"
  }'

Response:

{
  "id": "usr_c0s6t7vjnb0c73f5g6eg",
  "email": "you@yourcompany.com",
  "name": "Your Name",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Save your token - you'll need it for authentication.

Create a Workspace

Create a workspace for your organization:

curl -X POST https://registry.yourcompany.com/v1/workspaces \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-company",
    "display_name": "My Company"
  }'

Response:

{
  "id": "ws_c0s6t7vjnb0c73f5g6eg",
  "name": "my-company",
  "display_name": "My Company",
  "created_at": "2025-01-10T10:00:00Z"
}

Configure Flutter CLI

Configure Flutter to use your private registry:

The simplest method is to set the PUB_HOSTED_URL environment variable:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PUB_HOSTED_URL="https://registry.yourcompany.com"

# Or set for current session only
export PUB_HOSTED_URL="https://registry.yourcompany.com"

This will make ALL packages default to your private registry. You'll need to explicitly specify hosted for pub.dev packages.

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

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

Then set the environment variable:

export GF_PUB_TOKEN="YOUR_TOKEN_HERE"

For more control, use pubspec.yaml hosted configuration:

dependencies:
  my_private_package:
    hosted:
      name: my_private_package
      url: https://registry.yourcompany.com
    version: ^1.0.0
  
  # Public packages still work
  http: ^1.1.0

Create credentials file at ~/.pub-cache/credentials.json:

{
  "accessToken": "YOUR_TOKEN_HERE",
  "refreshToken": null,
  "tokenEndpoint": "https://registry.yourcompany.com/token",
  "scopes": ["openid", "https://www.googleapis.com/auth/userinfo.email"],
  "expiration": 1893456000000
}

Create a Flutter Package

Create a new Flutter package or use an existing one:

# Create new package
flutter create --template=package my_awesome_package
cd my_awesome_package

Edit pubspec.yaml to add your registry:

name: my_awesome_package
description: My awesome private Flutter package
version: 1.0.0
homepage: https://github.com/yourcompany/my_awesome_package

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

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0

# Configure to publish to your registry
publish_to: https://registry.yourcompany.com

The publish_to field tells Flutter where to publish your package.

Publish Your Package

Publish your package to Game Framework:

# Dry run first (recommended)
flutter pub publish --dry-run

# Publish for real
flutter pub publish --server=https://registry.yourcompany.com

Output:

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

Package validation found no errors.
Do you want to publish my_awesome_package 1.0.0 (y/N)? y

Uploading...
Successfully uploaded package.

🎉 Congratulations! Your package is now published to your private registry.

Install Your Package

Now use your private package in another project:

# Create a new Flutter app
flutter create my_app
cd my_app

Add your package to pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  
  # Your private package
  my_awesome_package:
    hosted:
      name: my_awesome_package
      url: https://registry.yourcompany.com
    version: ^1.0.0

Install dependencies:

flutter pub get

Output:

Resolving dependencies...
+ my_awesome_package 1.0.0 (from https://registry.yourcompany.com)
Changed 1 dependency!

Use your package in code:

import 'package:my_awesome_package/my_awesome_package.dart';

void main() {
  // Use your private package
  print('Hello from my private package!');
}

Alternative: Using API Keys

For CI/CD environments, use API keys instead of user tokens:

Create an API Key

curl -X POST https://registry.yourcompany.com/v1/workspaces/ws_YOUR_WORKSPACE_ID/api-keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Key",
    "description": "Key for GitHub Actions",
    "expires_at": "2026-12-31T23:59:59Z",
    "permissions": ["packages.publish", "versions.create"]
  }'

Response:

{
  "id": "key_c0s6t7vjnb0c73f5g6eg",
  "key": "gf_live_abc123...",
  "name": "CI/CD Key",
  "created_at": "2025-01-10T10:00:00Z"
}

Save this key! It won't be shown again.

Use API Key for Publishing

# Set API key as environment variable
export GF_PUB_TOKEN="gf_live_abc123..."

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

Or in CI/CD:

# GitHub Actions
- name: Publish Package
  env:
    GF_PUB_TOKEN: ${{ secrets.GAME_FRAMEWORK_TOKEN }}
  run: flutter pub publish --force --server=https://registry.yourcompany.com

Publishing Updates

To publish a new version of your package:

Update Version

Update the version in pubspec.yaml:

name: my_awesome_package
version: 1.1.0  # Increment version

Update CHANGELOG

Document your changes in CHANGELOG.md:

## 1.1.0

- Added new feature X
- Fixed bug Y
- Improved performance

Publish New Version

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

Verify Your Package

Check your package in the registry:

# Get package info
curl https://registry.yourcompany.com/v1/packages/my_awesome_package \
  -H "Authorization: Bearer YOUR_TOKEN"

# List all versions
curl https://registry.yourcompany.com/v1/packages/my_awesome_package/versions \
  -H "Authorization: Bearer YOUR_TOKEN"

Common Patterns

Monorepo with Multiple Packages

If you have multiple packages in a monorepo:

my_project/
├── packages/
│   ├── core/
│   │   └── pubspec.yaml
│   ├── ui/
│   │   └── pubspec.yaml
│   └── utils/
│       └── pubspec.yaml
└── apps/
    └── mobile/
        └── pubspec.yaml

Publish each package:

cd packages/core && flutter pub publish --server=https://registry.yourcompany.com
cd ../ui && flutter pub publish --server=https://registry.yourcompany.com
cd ../utils && flutter pub publish --server=https://registry.yourcompany.com

Using Make for Automation

Create a Makefile:

publish:
	@echo "Publishing package..."
	flutter pub publish --dry-run
	flutter pub publish --server=https://registry.yourcompany.com

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

version-patch:
	@echo "Bumping patch version..."
	# Use your preferred version bumping tool
	dart pub global run cider bump patch
	
version-minor:
	@echo "Bumping minor version..."
	dart pub global run cider bump minor

Usage:

make version-patch
make publish

Next Steps

Now that you've published your first package, explore more features:

Learn Flutter Integration

Configure Flutter CLI - Advanced CLI configuration
CI/CD Integration - Automate publishing
Pubspec Configuration - Advanced pubspec.yaml options

Manage Your Workspace

Invite Team Members - Collaborate with your team
Set Permissions - Control access
Manage Packages - Package lifecycle

Set Up CI/CD

Troubleshooting

Package Not Found

If Flutter can't find your package:

Check your authentication token is valid
Verify the hosted.url in pubspec.yaml
Ensure you have permission to access the package

# Test registry connection
curl -I https://registry.yourcompany.com/health

# Test authentication
curl https://registry.yourcompany.com/v1/packages \
  -H "Authorization: Bearer YOUR_TOKEN"

Publishing Fails

If publishing fails:

Check you have packages.create permission
Verify package name is unique in workspace
Ensure version number is incremented

# Check your permissions
curl https://registry.yourcompany.com/v1/me/permissions \
  -H "Authorization: Bearer YOUR_TOKEN"

More Help

Need help? Contact support at support@gameframework.dev or join our community Slack.

On this page