abanoub-ashraf/ios-swift-packages

Swift Package Manager Expert

You are an expert in Swift Package Manager. When this skill activates, help create and manage Swift packages effectively.

Creating Local Packages

Quick Create via Xcode

1. File → New → Package
2. Choose Library type
3. Add to existing project

Command Line Creation

# Create new package
mkdir MyPackage && cd MyPackage
swift package init --type library --name MyPackage

# Create executable
swift package init --type executable

# Create with specific tools version
swift package init --type library

Package.swift Anatomy

Full Featured Example

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    // MARK: - Package Identity
    name: "DesignSystem",

    // MARK: - Default Localization
    defaultLocalization: "en",

    // MARK: - Supported Platforms
    platforms: [
        .iOS(.v17),
        .macOS(.v14),
        .watchOS(.v10),
        .tvOS(.v17),
        .visionOS(.v1)
    ],

    // MARK: - Products (What others can import)
    products: [
        // Main library
        .library(
            name: "DesignSystem",
            targets: ["DesignSystem"]
        ),
        // Dynamic library (for faster debug builds)
        .library(
            name: "DesignSystemDynamic",
            type: .dynamic,
            targets: ["DesignSystem"]
        ),
        // Plugin
        .plugin(
            name: "SwiftLintPlugin",
            targets: ["SwiftLintPlugin"]
        )
    ],

    // MARK: - Dependencies
    dependencies: [
        // Remote package (exact version)
        .package(url: "https://github.com/apple/swift-algorithms", exact: "1.2.0"),

        // Remote package (version range)
        .package(url: "https://github.com/pointfreeco/swift-composable-architecture", from: "1.5.0"),

        // Remote package (branch)
        .package(url: "https://github.com/user/repo", branch: "main"),

        // Remote package (commit)
        .package(url: "https://github.com/user/repo", revision: "abc123"),

        // Local package
        .package(path: "../Core"),
        .package(path: "../Networking"),

        // Conditional (for development)
        // .package(url: "...", from: "1.0.0"),
    ],

    // MARK: - Targets
    targets: [
        // Main target
        .target(
            name: "DesignSystem",
            dependencies: [
                // Product from package
                .product(name: "Algorithms", package: "swift-algorithms"),
                // Local target
                "DesignSystemCore",
                // Conditional dependency
                .target(name: "DesignSystemMacOS", condition: .when(platforms: [.macOS]))
            ],
            path: "Sources/DesignSystem",
            exclude: ["README.md"],
            resources: [
                // Process resources (localization, asset catalogs)
                .process("Resources"),
                // Copy as-is
                .copy("Fonts")
            ],
            swiftSettings: [
                .define("DEBUG", .when(configuration: .debug)),
                .enableUpcomingFeature("StrictConcurrency"),
                .enableExperimentalFeature("VariadicGenerics")
            ],
            linkerSettings: [
                .linkedFramework("CoreGraphics"),
                .linkedLibrary("sqlite3")
            ]
        ),

        // Core target (no dependencies)
        .target(
            name: "DesignSystemCore"
        ),

        // Platform-specific target
        .target(
            name: "DesignSystemMacOS",
            dependencies: ["DesignSystemCore"]
        ),

        // Test target
        .testTarget(
            name: "DesignSystemTests",
            dependencies: [
                "DesignSystem",
                .product(name: "CustomDump", package: "swift-custom-dump")
            ],
            resources: [
                .process("Fixtures")
            ]
        ),

        // Plugin target
        .plugin(
            name: "SwiftLintPlugin",
            capability: .buildTool(),
            dependencies: [
                .target(name: "SwiftLintBinary")
            ]
        ),

        // Binary target
        .binaryTarget(
            name: "SwiftLintBinary",
            url: "https://github.com/.../swiftlint.zip",
            checksum: "abc123..."
        )
    ],

    // MARK: - Swift Language Version
    swiftLanguageVersions: [.v5]
)

Common Patterns

Multi-Target Package

let package = Package(
    name: "Networking",
    platforms: [.iOS(.v17)],
    products: [
        .library(name: "Networking", targets: ["Networking"]),
        .library(name: "NetworkingMocks", targets: ["NetworkingMocks"])
    ],
    targets: [
        .target(name: "Networking"),
        .target(
            name: "NetworkingMocks",
            dependencies: ["Networking"]
        ),
        .testTarget(
            name: "NetworkingTests",
            dependencies: ["Networking", "NetworkingMocks"]
        )
    ]
)

Interface + Implementation Split

let package = Package(
    name: "Analytics",
    platforms: [.iOS(.v17)],
    products: [
        .library(name: "AnalyticsInterface", targets: ["AnalyticsInterface"]),
        .library(name: "Analytics", targets: ["Analytics"]),
        .library(name: "AnalyticsMock", targets: ["AnalyticsMock"])
    ],
    targets: [
        // Protocol only - no implementation
        .target(name: "AnalyticsInterface"),

        // Real implementation
        .target(
            name: "Analytics",
            dependencies: ["AnalyticsInterface"]
        ),

        // Mock for testing
        .target(
            name: "AnalyticsMock",
            dependencies: ["AnalyticsInterface"]
        ),

        .testTarget(
            name: "AnalyticsTests",
            dependencies: ["Analytics", "AnalyticsMock"]
        )
    ]
)

Resources in Packages

Adding Resources

.target(
    name: "DesignSystem",
    resources: [
        // Asset catalogs, localized strings, storyboards
        .process("Resources"),

        // Copy files exactly as-is
        .copy("Fonts/CustomFont.ttf"),

        // Specific file
        .process("config.json")
    ]
)

Accessing Resources

// Bundle for this module
let bundle = Bundle.module

// Load image
let image = UIImage(named: "icon", in: .module, with: nil)

// SwiftUI image
Image("icon", bundle: .module)

// Load data file
if let url = Bundle.module.url(forResource: "config", withExtension: "json") {
    let data = try Data(contentsOf: url)
}

// Localized strings
Text("welcome_message", bundle: .module)

Asset Catalog Setup

Sources/
└── DesignSystem/
    └── Resources/
        ├── Assets.xcassets/
        │   ├── Colors/
        │   │   └── Primary.colorset/
        │   └── Images/
        │       └── Logo.imageset/
        └── Localizable.xcstrings

Dependency Best Practices

Version Constraints

dependencies: [
    // ✅ Good - Allows compatible updates
    .package(url: "...", from: "1.0.0"),

    // ⚠️ Okay - Specific range
    .package(url: "...", "1.0.0"..<"2.0.0"),

    // ⚠️ Careful - Exact version (prevents updates)
    .package(url: "...", exact: "1.2.3"),

    // 🔬 Development only - Branch tracking
    .package(url: "...", branch: "main"),
]

Conditional Dependencies

.target(
    name: "MyTarget",
    dependencies: [
        .product(name: "UIFeature", package: "UIPackage",
                 condition: .when(platforms: [.iOS, .macOS])),
        .product(name: "WatchFeature", package: "WatchPackage",
                 condition: .when(platforms: [.watchOS]))
    ]
)

Package Plugins

Build Tool Plugin

// Plugins/MyPlugin/plugin.swift
import PackagePlugin

@main
struct MyPlugin: BuildToolPlugin {
    func createBuildCommands(context: PluginContext, target: Target) throws -> [Command] {
        guard let target = target as? SourceModuleTarget else { return [] }

        let outputPath = context.pluginWorkDirectory.appending("Generated.swift")

        return [
            .buildCommand(
                displayName: "Generate Code",
                executable: try context.tool(named: "generator").path,
                arguments: [
                    "--input", target.directory.string,
                    "--output", outputPath.string
                ],
                outputFiles: [outputPath]
            )
        ]
    }
}

Command Plugin

@main
struct FormatPlugin: CommandPlugin {
    func performCommand(context: PluginContext, arguments: [String]) throws {
        let swiftformat = try context.tool(named: "swiftformat")

        let process = Process()
        process.executableURL = URL(fileURLWithPath: swiftformat.path.string)
        process.arguments = [context.package.directory.string]

        try process.run()
        process.waitUntilExit()
    }
}

Troubleshooting SPM

Common Issues

"Dependency Resolution Failed"

# Reset package cache
rm -rf ~/Library/Caches/org.swift.swiftpm
rm -rf .build
rm Package.resolved

# In Xcode
File → Packages → Reset Package Caches

"Missing Module"

// Check target name matches import
.target(name: "MyModule")  // Creates module "MyModule"

import MyModule  // Must match exactly

"Circular Dependency"

A → B → C → A  ❌

Fix: Extract shared types to new module
A → Shared
B → Shared
C → Shared

Build Errors in Dependencies

# Update to latest compatible versions
swift package update

# Or force resolve
swift package resolve

Debugging Package Issues

# Show dependency graph
swift package show-dependencies --format json

# Show what's resolved
cat Package.resolved

# Verbose build
swift build -v

# Clean everything
swift package clean
swift package purge-cache

Xcode Integration

Adding Local Package

1. File → Add Package Dependencies
2. Click "Add Local..."
3. Select package folder
4. Add to target

Workspace with Packages

MyApp.xcworkspace/
├── MyApp.xcodeproj
└── Packages/
    ├── FeatureA/
    ├── FeatureB/
    └── Core/

Package.swift in Xcode

• Double-click Package.swift to edit
• Xcode provides autocomplete
• Errors shown inline

CI/CD with SPM

GitHub Actions

- name: Resolve Dependencies
  run: swift package resolve

- name: Build Package
  run: swift build -c release

- name: Run Tests
  run: swift test --parallel

Caching Dependencies

- uses: actions/cache@v4
  with:
    path: .build
    key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }}
    restore-keys: |
      ${{ runner.os }}-spm-

Package Commands Reference

# Initialize
swift package init --type library
swift package init --type executable

# Build
swift build
swift build -c release
swift build --target TargetName

# Test
swift test
swift test --parallel
swift test --filter TestClassName

# Clean
swift package clean
swift package purge-cache

# Dependencies
swift package update
swift package resolve
swift package show-dependencies

# Documentation
swift package generate-documentation

# Edit in Xcode
swift package generate-xcodeproj  # deprecated
open Package.swift  # Modern approach