pakker/docs/MIGRATION.md

Migrating from Pakku to Pakker

This guide helps you migrate from Pakku (Kotlin) to Pakker (Rust).

Overview

Pakker is designed to be largely compatible with Pakku, maintaining the same configuration format and workflow. Most Pakku modpacks can be imported directly into Pakker with minimal changes.

Key Differences

Performance

• Faster execution - Rust implementation provides significant speed improvements
• Lower memory usage - More efficient resource utilization
• Parallel operations - Better concurrency for downloads and processing

Enhanced Features

• Non-interactive mode - add-prj command for CI/CD workflows
• Advanced inspection - Enhanced inspect command with dependency trees
• Export profiles - More flexible profile-based export configuration
• Platform filtering - Automatic platform-specific mod filtering

Compatibility

✅ Compatible:

• Configuration format (pakku.json)
• Lockfile format (pakku-lock.json)
• Export formats (CurseForge ZIP, Modrinth .mrpack)
• Override directory structure
• Project properties and metadata

⚠️ Differences:

• Some CLI flag names (documented below)
• New features not in Pakku
• Performance characteristics

Quick Migration

Step 1: Import Existing Modpack

If you have an existing Pakku modpack:

# Navigate to your modpack directory
cd my-modpack

# Pakker will use existing pakku.json and pakku-lock.json
pakker ls

That's it! Pakker reads the same configuration files.

Step 2: Verify Projects

# List all projects
pakker ls

# Inspect specific projects
pakker inspect sodium lithium

Step 3: Test Export

# Export for your target platform
pakker export --profile curseforge
pakker export --profile modrinth

Configuration Migration

pakku.json Format

Pakker uses the same format as Pakku:

{
  "name": "My Modpack",
  "version": "1.0.0",
  "description": "A performance modpack",
  "author": "YourName",
  "overrides": ["overrides"],
  "serverOverrides": ["server-overrides"],
  "clientOverrides": ["client-overrides"]
}

Export Profiles

Pakker extends Pakku's configuration with enhanced export profiles:

Pakku format (still supported):

{
  "exportProfiles": {
    "curseforge": {
      "filterPlatform": "curseforge"
    }
  }
}

Pakker enhancements (new features):

{
  "exportProfiles": {
    "curseforge": {
      "filterPlatform": "curseforge",
      "includeNonRedistributable": false,
      "overrides": ["overrides", "curseforge-specific"]
    },
    "modrinth": {
      "filterPlatform": "modrinth",
      "includeNonRedistributable": true
    },
    "serverpack": {
      "includeClientOnly": false,
      "serverOverrides": ["server-config"]
    }
  }
}

See EXPORT_PROFILES.md for complete documentation.

Command Mapping

Most commands are identical or very similar:

Pakku	Pakker	Notes
pakku init	pakker init	Identical
pakku import	pakker import	Identical
pakku add	pakker add	Identical
pakku add	pakker add-prj	New non-interactive variant
pakku rm	pakker rm	Identical
pakku update	pakker update	Identical
pakku ls	pakker ls	Identical
pakku status	pakker status	Identical
pakku fetch	pakker fetch	Identical
pakku export	pakker export	Enhanced with profiles
pakku link	pakker link	Identical
pakku set	pakker set	Identical
pakku cfg	pakker cfg	Identical
pakku diff	pakker diff	Identical

New Commands in Pakker

• pakker add-prj - Non-interactive project addition for CI/CD
• pakker inspect - Enhanced project inspection with dependency trees
• pakker sync - Combined update + fetch operation
• pakker credentials - Credential management
• pakker remote - Git remote management
• pakker fork - Fork configuration

Feature Comparison

Project Management

Feature	Pakku	Pakker	Notes
Add projects	✅	✅	Enhanced with add-prj
Remove projects	✅	✅	Identical
Update projects	✅	✅	Identical
List projects	✅	✅	Identical
Project properties	✅	✅	Identical
Dependencies	✅	✅	Enhanced inspection

Export System

Feature	Pakku	Pakker	Notes
CurseForge export	✅	✅	Identical format
Modrinth export	✅	✅	Identical format
Server pack	✅	✅	Enhanced filtering
Export profiles	✅	✅	Extended features
Override dirs	✅	✅	Identical
Platform filtering	❌	✅	New in Pakker
Profile-specific overrides	❌	✅	New in Pakker

Configuration

Feature	Pakku	Pakker	Notes
pakku.json	✅	✅	Same format
pakku-lock.json	✅	✅	Same format
Project config	✅	✅	Identical
Export profiles	✅	✅	Extended in Pakker

Migration Scenarios

Scenario 1: Local Development

Pakku workflow:

pakku init
pakku add sodium lithium
pakku fetch
pakku export

Pakker workflow:

pakker init
pakker add sodium lithium
pakker fetch
pakker export --profile modrinth

No changes needed!

Scenario 2: CI/CD Pipeline

Pakku workflow:

# Interactive, requires user input
pakku add sodium
pakku add lithium
pakku fetch
pakku export

Pakker workflow:

# Fully automated
pakker add-prj --mr sodium --yes --no-deps
pakker add-prj --mr lithium --yes --no-deps
pakker update --all --yes
pakker fetch
pakker export --profile modrinth -o dist/pack.mrpack

Benefits: No interactive prompts, perfect for CI/CD.

Scenario 3: Multi-Platform Release

Pakku workflow:

# Manual export for each platform
pakku export
# Manually select CurseForge
pakku export
# Manually select Modrinth

Pakker workflow:

# Script multiple exports
pakker export --profile curseforge -o dist/cf.zip
pakker export --profile modrinth -o dist/mr.mrpack
pakker export --profile serverpack -o dist/server.zip

Benefits: Scriptable, reproducible builds.

Migrating CI/CD Workflows

GitHub Actions

Before (Pakku):

- name: Setup Pakku
  run: |
    # Install Pakku
    
- name: Build modpack
  run: |
    pakku fetch
    pakku export

After (Pakker):

- name: Setup Pakker
  run: |
    # Install Pakker
    cargo install pakker
    
- name: Build modpack
  run: |
    pakker fetch
    pakker export --profile curseforge -o dist/curseforge.zip
    pakker export --profile modrinth -o dist/modrinth.mrpack

GitLab CI

Before (Pakku):

build:
  script:
    - pakku fetch
    - pakku export

After (Pakker):

build:
  script:
    - pakker fetch
    - pakker export --profile curseforge -o curseforge.zip
    - pakker export --profile modrinth -o modrinth.mrpack
  artifacts:
    paths:
      - "*.zip"
      - "*.mrpack"

Troubleshooting

Projects Not Found After Migration

Problem: Pakker can't find projects that worked in Pakku.

Solution: Verify lockfile format:

# Check lockfile
cat pakku-lock.json

# Re-fetch projects
pakker fetch

# If issues persist, re-add problematic projects
pakker rm problematic-mod
pakker add-prj --mr problematic-mod --yes

Export Format Differences

Problem: Exported packs look different.

Solution: Pakker may organize files slightly differently. Both formats are valid:

# Inspect export
unzip -l curseforge.zip

# Verify manifest
jq . manifest.json

If needed, configure export profiles to match Pakku behavior exactly.

Performance Issues

Problem: Pakker seems slower than expected.

Solution: Pakker should be faster than Pakku. Check:

# Enable logging
pakker -vv fetch

# Check network connectivity
pakker status

# Verify credentials (for rate limits)
pakker credentials

Configuration Not Recognized

Problem: Some configuration options don't work.

Solution: Ensure you're using compatible options:

{
  "name": "My Pack",
  "version": "1.0.0",
  "overrides": ["overrides"]
}

Pakker supports all Pakku options plus new ones. Check EXPORT_PROFILES.md for new features.

Best Practices

1. Test Before Full Migration

# Copy modpack to test directory
cp -r my-modpack my-modpack-test
cd my-modpack-test

# Test with Pakker
pakker ls
pakker fetch
pakker export --profile modrinth

# Verify exports match expectations

2. Update CI/CD Gradually

1. Test Pakker locally first
2. Update a single workflow
3. Verify builds succeed
4. Roll out to all workflows

3. Use New Features

Take advantage of Pakker enhancements:

# Non-interactive project addition
pakker add-prj --mr sodium --yes

# Enhanced inspection
pakker inspect sodium

# Profile-based exports
pakker export --profile production -o release.mrpack

4. Keep Backward Compatibility

If you need to support both Pakku and Pakker:

{
  "exportProfiles": {
    "curseforge": {
      "filterPlatform": "curseforge"
    }
  }
}

Use the common subset of features that both support.

Getting Help

Resources

• Pakker Documentation
• Command Reference
• Export Profiles

Common Issues

Issue	Solution
Project not found	Try explicit platform: pakker add-prj --mr <name>
Export fails	Check export profile configuration
Missing files	Run pakker fetch
Slow performance	Verify network, add credentials
Config not recognized	Check pakku.json syntax with jq

Support Channels

• GitHub Issues: Report bugs and feature requests
• Documentation: Check docs/ directory
• Examples: See examples/ directory

Migration Checklist

• Backup existing modpack directory
• Install Pakker
• Verify pakker ls shows all projects
• Test pakker fetch downloads files
• Test export for your target platform
• Update CI/CD workflows
• Test automated builds
• Update documentation
• Train team members on new commands
• Monitor for issues

Feature Roadmap

Pakker aims for full Pakku compatibility plus enhancements. If you find missing features, please report them!

Current Status:

• ✅ Core functionality (add, remove, update, export)
• ✅ Multi-platform support
• ✅ Export profiles
• ✅ CI/CD workflows
• ✅ Dependency resolution

Planned:

• Custom export rules
• Advanced project filtering
• Enhanced remote sync
• Plugin system

Summary

Migrating from Pakku to Pakker is straightforward:

1. No configuration changes needed for basic usage
2. Same commands for most operations
3. Enhanced features available when ready
4. Better performance out of the box
5. CI/CD friendly with non-interactive modes

Most users can start using Pakker immediately with existing Pakku modpacks!