Namespace Management

Learn how to organize and name your packages effectively within your workspace.

Understanding Namespaces

In Game Framework, your workspace name serves as the namespace for all packages:

https://registry.yourcompany.com/workspaces/{workspace}/packages/{package}

Example:

https://registry.yourcompany.com/workspaces/acme-corp/packages/auth_package

Package Naming Conventions

Recommended Format

Use lowercase with underscores:

# ✓ Good names
company_auth
company_ui_components
company_http_client

# ✗ Bad names
CompanyAuth  # No camelCase
company-auth  # No hyphens
Auth  # Too generic

Naming Patterns

By Feature:

acme_auth
acme_analytics
acme_payments

By Platform:

acme_mobile_core
acme_web_core
acme_backend_client

By Team:

frontend_ui_kit
frontend_widgets
backend_api_client

Package Organization

Flat Structure

Simple workspaces with few packages:

acme-corp/
├── auth
├── ui
├── utils
└── analytics

Grouped by Prefix

Use prefixes for related packages:

acme-corp/
├── core_auth
├── core_http
├── core_storage
├── ui_components
├── ui_theme
├── ui_icons
└── tools_cli

Monorepo Strategy

Mirror your code repository structure:

Company Monorepo:
packages/
├── core/           → company_core
├── auth/           → company_auth
├── ui/             → company_ui
└── shared/         → company_shared

Naming Best Practices

1. Be Descriptive

# ✓ Clear purpose
company_oauth_client
company_api_models

# ✗ Too vague
company_stuff
company_helpers

2. Use Consistent Prefixes

# Team/company prefix
acme_auth
acme_ui
acme_analytics

# Or feature prefix
mobile_auth
mobile_ui
mobile_analytics

3. Avoid Reserved Names

Don't use Flutter SDK package names:

# ✗ Conflicts with SDK
flutter
material
cupertino

# ✓ Use prefixed names
company_flutter_extensions
company_material_theme

4. Keep Names Short

# ✓ Concise
company_auth
company_ui

# ✗ Too long
company_authentication_and_authorization_framework

Scoped Packages

Using Workspace as Scope

Your workspace acts as a scope:

# In pubspec.yaml
dependencies:
  # Scoped to your workspace
  auth_package:
    hosted:
      name: auth_package
      url: https://registry.yourcompany.com/workspaces/acme-corp
    version: ^1.0.0

Multiple Workspaces

Use different workspace for different scopes:

company/
├── frontend-workspace/
│   ├── ui_components
│   └── state_management
└── backend-workspace/
    ├── api_client
    └── data_models

Package Visibility

Control who can see packages:

curl -X PATCH https://registry.yourcompany.com/v1/packages/pkg_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"visibility": "private"}'

Visibility Options:

private - Workspace members only
internal - Same organization only (Enterprise)
public - Anyone with access to registry

Migration and Renaming

Warning: Package names cannot be changed after creation. Plan carefully!

If You Need to Rename

Create new package with desired name
Deprecate old package
Update all dependents
Delete old package after transition

# Deprecate old package
curl -X POST https://registry.yourcompany.com/v1/packages/old_name/deprecate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"message": "Use new_name instead"}'

Documentation

README Naming Section

Document your naming conventions:

# Package Naming

All packages follow this format:
- Prefix: `acme_`
- Feature: descriptive name
- Example: `acme_auth`, `acme_ui`

## Categories

- `acme_core_*` - Core functionality
- `acme_ui_*` - UI components
- `acme_platform_*` - Platform-specific code

Examples from Teams

Mobile Team

mobile_workspace/
├── mobile_auth          # Authentication
├── mobile_ui            # UI components
├── mobile_analytics     # Analytics
└── mobile_offline       # Offline support

Platform Teams

ios_workspace/
├── ios_native_bridge
├── ios_camera
└── ios_biometrics

android_workspace/
├── android_native_bridge
├── android_camera
└── android_biometrics

Feature Teams

payments_workspace/
├── payments_stripe
├── payments_paypal
├── payments_models
└── payments_ui

Next Steps

Package Management - Create and manage packages
Publishing - Publish your packages
Best Practices - Detailed naming guide

Need help? Contact support

On this page