Skip to content

Swift#

The BSR generates Swift code for Protobuf messages and Connect clients on every push to a module’s default label, and serves the result as a Swift Package Manager registry and a per-version Git server. Two installation paths cover the Swift ecosystem:

  • Swift Package Manager: the preferred path when you control Package.swift.
  • Xcode: the fallback for iOS, macOS, watchOS, or tvOS app targets that can’t use the SPM CLI.

For copy-paste install snippets pinned to a specific version, open the module’s SDKs tab at https://buf.build/your-organization/your-module/sdks and pick the Swift language. On a private BSR instance, substitute your own host for buf.build.

For an end-to-end walkthrough, see the generated SDKs quickstart.

Swift Package Manager#

Configure SPM to resolve the buf scope through the BSR registry:

Setup
$ swift package-registry set https://buf.build/gen/swift --scope=buf

Then add the package and product to Package.swift:

  1. Add a package dependency to the dependencies block:

    Package.swift
    dependencies: [
    .package(
        id: "buf.connectrpc_eliza_connectrpc_swift",
        exact: "0.8.0-20230913231627-233fca715f49.1"
    )
],

  2. Add a product dependency to the relevant target:

    Package.swift
    .target(
    name: "ExamplePackage",
    dependencies: [
        .product(
            name: "Connectrpc_Eliza_Connectrpc_Swift",
            package: "buf.connectrpc_eliza_connectrpc_swift"
        ),
    ]
),

For the formats those identifiers follow, see SDK and product names.

Xcode#

Xcode doesn’t yet drive Swift Package Manager from Package.swift for iOS, macOS, watchOS, or tvOS app targets; those targets still resolve dependencies as Git repositories. The BSR exposes a read-only Git server for generated SDKs at https://buf.build/gen/swift/git to fit that flow.

If you don’t ship an Apple-app target, prefer Swift Package Manager.

Add a dependency#

The Git URLs for a module live on its SDKs tab at https://buf.build/your-organization/your-module/sdks with the Swift language and the Xcode sub-tab selected.

  1. In Xcode, choose File > Add Packages….

  2. Paste the SDK’s .git URL into the Search or Enter Package URL field. For example:

    Example URL
    https://buf.build/gen/swift/git/0.8.0-20230913231627-233fca715f49.1/connectrpc_eliza_connectrpc_swift.git

  3. For Dependency Rule, choose Branch with main, or Exact Version with the SemVer string. Range rules don’t work against this Git server.

  4. Click Add Package.
  5. In the prompt that follows, check the library and click Add. Each SDK ships exactly one library, and Xcode pulls in any transitive dependencies automatically.

Update a dependency#

The Git server publishes each SDK version at its own URL, so Xcode’s auto-update flow doesn’t apply. To pick up a newer version, get a new URL from the module’s SDKs tab and replace the existing dependency with that URL.

Private generated SDKs#

For private BSR repositories, supply a personal API token (or a bot user token for CI) when prompted. For setup, see Authentication.

On first access to a private SDK, Xcode prompts for credentials. Make sure the prompt is requesting username and password (not a VCS provider like GitHub or GitLab), and provide the BSR username and the token.

Authenticate the registry with swift package-registry login. The Swift toolchain stores the credentials in ~/.swiftpm/configuration/registries.json and the macOS Keychain (or .netrc):

Login
$ swift package-registry login https://buf.build/gen/swift/login --token={token}

The login command requires Swift 5.8 or later.

SDK and product names#

The identifiers in the install snippets follow three patterns.

Identifier Format Example
Xcode SDK name ORGANIZATION_MODULE-NAME_PLUGIN-OWNER_PLUGIN-NAME connectrpc_eliza_connectrpc_swift
SPM package ID buf.ORGANIZATION_MODULE-NAME_PLUGIN-OWNER_PLUGIN-NAME buf.connectrpc_eliza_connectrpc_swift
Product name Title-cased segments joined by _, with internal hyphens removed Connectrpc_Eliza_Connectrpc_Swift

The placeholders:

  • ORGANIZATION is the BSR organization that owns the module.
  • MODULE-NAME is the name of the module.
  • PLUGIN-OWNER is the owner of the plugin.
  • PLUGIN-NAME is the name of the plugin.

For the product name, each segment is title-cased and any internal hyphens are dropped: the plugin connect-swift produces ConnectSwift, not Connect-Swift.

Versions#

Each generated SDK version is a SemVer string built from the plugin and the module commit:

Version syntax
PLUGIN_VERSION-MODULE_TIMESTAMP-COMMIT_ID.PLUGIN_REVISION

# Example
1.11.0-20230727062025-d8fbf2620c60.1
Part Example Source
Version core 1.11.0 Plugin version.
Pre-release: timestamp 20230727062025 Module commit timestamp (YYYYMMDDHHMMSS).
Pre-release: commit d8fbf2620c60 First 12 characters of the module commit ID.
Build metadata 1 Plugin revision.

Commits pushed to non-default labels carry 00000000000000 as the timestamp so they sort below released versions. To browse versions interactively, open the module’s SDKs page; for scripting or pinning to a specific plugin version, see the buf registry sdk version CLI command.

Available plugins#

The full list of supported Swift plugins lives on the BSR plugins page (filter for Swift). For how those plugins are packaged, see the bufbuild/plugins repository; to request a new plugin, file an issue.