Buf Schema Registry / Remote packages

Swift

The Buf Schema Registry (BSR) provides remote packages for Swift, enabling you to download pre-packaged generated code for Protobuf schemas from the BSR using Swift Package Manager and Xcode. Packages are automatically made available when schema changes are pushed to the BSR, and they eliminate the need to manage a Protobuf toolchain or generate code locally.

Xcode

There is no setup required to start using Buf's remote Swift packages with Xcode.

However, Xcode does not yet support using the Swift Package Manager CLI and Package.swift for iOS/Mac apps. Dependency management for these targets is still done with git repositories. To account for this, Buf provides a read-only git server for remote packages, which is available at the https://buf.build/gen/swift/git host.

If you are not developing an iOS, macOS, watchOS, or tvOS app and use a Package.swift manifest file to control your package and its dependencies, please use our Swift Package Manager implementation.

Adding a dependency

To find the git URLs for your BSR module, go to the module's Assets tab, which you can find at https://{host}/{org}/{module}/assets. Ensure you have the Swift language and the Xcode tab selected.

In your Xcode project, navigate to File > Add Packages....
In the popup window, click into the Search or Enter Package URL text field in the top right and paste the provided package's .git URL:
Package-URL
```
# Example URL
https://buf.build/gen/swift/git/0.8.0-20230913231627-233fca715f49.1/connectrpc_eliza_connectrpc_swift.git
```
Next, for the Dependency Rule, select Branch and point it to main.
Click Add Package. A new pop-up will appear prompting you to link the package's products to your app.
Ensure the library is checked and click Add to confirm the package addition (there will only ever be one library). Note that this will automatically add any transitive dependencies.

When using remote packages sourced from the read-only git server with Xcode, only use the Branch dependency rule providing the main branch, or the Exact Version dependency rule, providing the SemVer, as the ranging rules will not function.

Note: Since Buf lazily produces a separate git URL for each version of a package upon first request, Xcode's auto-update functionality does not work with these remote packages. To update a package, you'll need to navigate to the module's Assets tab and get a new link for a new version. You'll then need to manually update the dependency by replacing the existing package with the package sourced from the new link.

Private packages

When you attempt to access a private BSR module's package with Xcode, a prompt window will appear. In the prompt window, ensure that it's requesting your username and password, and not the other VCS-based alternatives (GitHub, GitLab). Supply your username and token in these fields. To create a new token, log into the BSR, navigate to the user settings page, and click Create Token.

You can also use a Machine user's API token, which is useful for authenticating private packages in CI workflows.

Swift Package Manager

To find the references for your BSR module to use with Swift Package Manager, go to the module's Assets page, which you can find athttps://{host}/{org}/{module}/assets. Ensure you have the Swift language and the SPM tab selected.

Setup

To enable Swift Package Manager to properly resolve all dependencies with the buf scope, set up the project registry with the following command:

Setup

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

Adding a dependency

Finally, add a dependency on the remote package:

Add a package dependency to the dependencies block of your Package.swift manifest file:

Package.swift

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

Add a product dependency to the dependencies block of your target's entry:

Package.swift

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

Private packages

To use packages for private BSR modules, you'll need an API Token. You can use an existing API Token or generate a new one.

To create a new token, log into the BSR, navigate to the user settings page, and click Create Token.

You can also use a Machine user's API token, which is useful for authenticating private packages in CI workflows.

To access the private module, execute the following with the swift toolchain, which will associate the token with the registry in the swift configuration file ~/.swiftpm/configuration/registries.json and create a macOS Keychain (or .netrc file) entry to store the credentials locally.

The login API was introduced in Swift 5.8. Please ensure your Swift toolchain version is 5.8 or later.

Login

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

More on remote packages

For package and product names, as well as available versions for the remote package, browse the BSR module's Assets tab, which you can find at https://{host}/{org}/{module}/assets.

Naming

The BSR has a special syntax for remote package names and product names:

# SPM package naming
buf.{module-owner}_{module-name}_{plugin-owner}_{plugin-name}
# Example: buf.connectrpc_eliza_connectrpc_swift

# Xcode package naming
{module-owner}_{module-name}_{plugin-owner}_{plugin-name}
# Example: connectrpc_eliza_connectrpc_swift

# Product naming
{ModuleOwner}_{ModuleName}_{PluginOwner}_{PluginName}
# Example: Connectrpc_Eliza_Connectrpc_Swift

Versions

The version syntax is similar to our other remote packages, and is a valid SemVer:

{pluginVersion}-{commitTimestamp}-{commitShortName}.{pluginRevision}
# Example: 0.8.0-20230913231627-233fca715f49.1
# - Plugin version: `0.8.0`
# - Plugin revision: `1`
# - Commit timestamp: `20230913231627`
# - Commit short name: `233fca715f49`

Drafts

For draft commits, the commit timestamp component of the version is always zeroed out to easily differentiate package versions using draft commits.

{pluginVersion}-00000000000000-{commitShortName}.{pluginRevision}
# Example: 0.8.0-00000000000000-f3801d450ef9.1
# - Plugin version: `0.8.0`
# - Plugin revision: `1`
# - Draft timestamp: `00000000000000`
# - Commit short name: `f3801d450ef9`

Available plugins

For a full list of supported plugins, navigate to the BSR plugins page and search for Swift.

To learn more about how these plugins are packaged and distributed, go to the bufbuild/plugins repository. If you find a useful plugin that should be added, please file an issue!