swift-spm

Master Swift Package Manager - dependencies, creating libraries, publishing, local packages

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides comprehensive expertise in Swift Package Manager (SPM), the native tool for managing the distribution of Swift code. It empowers developers to master dependency management, modularize codebases through local packages, and configure complex Package.swift manifests. By covering everything from basic library creation to advanced Swift Macros and CLI automation, this skill streamlines the development workflow for iOS, macOS, and server-side Swift projects.

Use Cases

  • Architecting modular applications by breaking down monolithic codebases into reusable local Swift packages to improve build times and maintainability.
  • Configuring complex Package.swift files with multiple targets, conditional platform dependencies, and custom build settings for cross-platform support.
  • Migrating legacy projects from third-party dependency managers like CocoaPods or Carthage to a native Swift Package Manager workflow.
  • Developing and distributing open-source Swift libraries with proper semantic versioning and automated testing configurations.
  • Troubleshooting dependency resolution conflicts and optimizing CI/CD pipelines using SPM command-line tools for automated building and testing.
nameswift-spm
descriptionMaster Swift Package Manager - dependencies, creating libraries, publishing, local packages
version"2.0.0"
sasmp_version"1.3.0"
bonded_agent01-swift-fundamentals
bond_typeSECONDARY_BOND

Swift Package Manager Skill

Dependency management, package creation, and distribution with Swift Package Manager.

Prerequisites

  • Swift 5.5+ toolchain
  • Xcode 14+ or VS Code with Swift extension
  • Git for version control

Parameters

parameters:
  swift_tools_version:
    type: string
    default: "5.9"
  platforms:
    type: array
    items: [iOS, macOS, watchOS, tvOS, visionOS, linux]
    default: [iOS, macOS]
  package_type:
    type: string
    enum: [library, executable, plugin]
    default: library

Topics Covered

Package.swift Structure

Element Purpose
name Package name
platforms Supported platforms/versions
products Libraries/executables exposed
dependencies External packages
targets Build targets

Dependency Specification

Format Example
Version range .upToNextMajor(from: "1.0.0")
Exact version .exact("1.2.3")
Branch .branch("main")
Commit .revision("abc123")
Path .package(path: "../LocalPkg")

Target Types

Type Purpose
.target Library code
.executableTarget Command-line tool
.testTarget Unit tests
.plugin Build tool plugin
.macro Swift macro

Code Examples

Complete Package.swift

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "NetworkKit",
    platforms: [
        .iOS(.v15),
        .macOS(.v12),
        .watchOS(.v8),
        .tvOS(.v15)
    ],
    products: [
        .library(
            name: "NetworkKit",
            targets: ["NetworkKit"]
        ),
        .library(
            name: "NetworkKitMocks",
            targets: ["NetworkKitMocks"]
        )
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-log.git", from: "1.5.0"),
        .package(url: "https://github.com/apple/swift-collections.git", from: "1.0.0")
    ],
    targets: [
        .target(
            name: "NetworkKit",
            dependencies: [
                .product(name: "Logging", package: "swift-log"),
                .product(name: "OrderedCollections", package: "swift-collections")
            ],
            resources: [
                .process("Resources")
            ],
            swiftSettings: [
                .enableExperimentalFeature("StrictConcurrency")
            ]
        ),
        .target(
            name: "NetworkKitMocks",
            dependencies: ["NetworkKit"]
        ),
        .testTarget(
            name: "NetworkKitTests",
            dependencies: [
                "NetworkKit",
                "NetworkKitMocks"
            ],
            resources: [
                .copy("Fixtures")
            ]
        )
    ]
)

Library with Multiple Targets

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "FeatureKit",
    platforms: [.iOS(.v16), .macOS(.v13)],
    products: [
        // Main library
        .library(name: "FeatureKit", targets: ["FeatureKit"]),
        // Individual features for selective import
        .library(name: "AuthFeature", targets: ["AuthFeature"]),
        .library(name: "ProfileFeature", targets: ["ProfileFeature"])
    ],
    dependencies: [
        .package(url: "https://github.com/pointfreeco/swift-composable-architecture", from: "1.0.0")
    ],
    targets: [
        // Core shared code
        .target(
            name: "Core",
            dependencies: []
        ),

        // Auth feature
        .target(
            name: "AuthFeature",
            dependencies: [
                "Core",
                .product(name: "ComposableArchitecture", package: "swift-composable-architecture")
            ]
        ),

        // Profile feature
        .target(
            name: "ProfileFeature",
            dependencies: [
                "Core",
                .product(name: "ComposableArchitecture", package: "swift-composable-architecture")
            ]
        ),

        // Umbrella target
        .target(
            name: "FeatureKit",
            dependencies: ["AuthFeature", "ProfileFeature"]
        ),

        // Tests
        .testTarget(
            name: "AuthFeatureTests",
            dependencies: ["AuthFeature"]
        ),
        .testTarget(
            name: "ProfileFeatureTests",
            dependencies: ["ProfileFeature"]
        )
    ]
)

Command-Line Tool

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "swift-format-tool",
    platforms: [.macOS(.v13)],
    products: [
        .executable(name: "swift-format-tool", targets: ["swift-format-tool"])
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-argument-parser", from: "1.2.0"),
        .package(url: "https://github.com/apple/swift-syntax", from: "509.0.0")
    ],
    targets: [
        .executableTarget(
            name: "swift-format-tool",
            dependencies: [
                .product(name: "ArgumentParser", package: "swift-argument-parser"),
                .product(name: "SwiftSyntax", package: "swift-syntax"),
                .product(name: "SwiftParser", package: "swift-syntax")
            ]
        )
    ]
)

Local Development Package

// In your app's Package.swift or Xcode project
// Use local path during development

// Package.swift with local override
let package = Package(
    name: "MyApp",
    dependencies: [
        // Production: Use remote
        // .package(url: "https://github.com/company/SharedKit", from: "1.0.0")

        // Development: Use local
        .package(path: "../SharedKit")
    ],
    targets: [
        .target(name: "MyApp", dependencies: ["SharedKit"])
    ]
)

Swift Macro Package

// swift-tools-version: 5.9
import PackageDescription
import CompilerPluginSupport

let package = Package(
    name: "MacroKit",
    platforms: [.macOS(.v10_15), .iOS(.v13)],
    products: [
        .library(name: "MacroKit", targets: ["MacroKit"])
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-syntax", from: "509.0.0")
    ],
    targets: [
        // Macro implementation
        .macro(
            name: "MacroKitMacros",
            dependencies: [
                .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
                .product(name: "SwiftCompilerPlugin", package: "swift-syntax")
            ]
        ),

        // Library that exposes the macro
        .target(
            name: "MacroKit",
            dependencies: ["MacroKitMacros"]
        ),

        // Tests for the macro
        .testTarget(
            name: "MacroKitTests",
            dependencies: [
                "MacroKitMacros",
                .product(name: "SwiftSyntaxMacrosTestSupport", package: "swift-syntax")
            ]
        )
    ]
)

CLI Commands

# Create new package
swift package init --type library
swift package init --type executable
swift package init --type macro

# Build
swift build
swift build -c release

# Test
swift test
swift test --filter MyTests

# Update dependencies
swift package update
swift package update PackageName

# Resolve dependencies
swift package resolve

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

# Generate Xcode project (deprecated but useful)
swift package generate-xcodeproj

# Clean
swift package clean
swift package reset

# Dump package description
swift package dump-package

Troubleshooting

Common Issues

Issue Cause Solution
"No such module" Missing dependency Add to target dependencies
Version conflict Incompatible requirements Use version that satisfies all
Build fails on CI Different Swift version Pin swift-tools-version
Resources not found Wrong resource rule Use .process or .copy correctly
Xcode not seeing changes Cache stale Clean derived data

Debug Tips

# Verbose build
swift build -v

# Check resolved versions
cat Package.resolved

# Dependency tree
swift package show-dependencies --format dot | dot -Tpng -o deps.png

# Rebuild from scratch
rm -rf .build Package.resolved
swift package resolve
swift build

Validation Rules

validation:
  - rule: pin_versions
    severity: warning
    check: Use version ranges, not branch/revision in production
  - rule: semantic_versioning
    severity: error
    check: Follow semver for your packages
  - rule: platform_support
    severity: info
    check: Declare minimum platform versions

Usage

Skill("swift-spm")
  • swift-fundamentals - Language basics
  • swift-testing - Package testing
  • swift-architecture - Package design