Publishing Multiplatform Libraries (Maven Central, SwiftPM, npm)

A multiplatform build creates one root publication named kotlinMultiplatform plus one publication per target.

Consumers never add the per-target artifacts. A KMP project writes one line in commonMain and Gradle picks the right target artifact for each of its own targets.

See Kotlin docs — Set up multiplatform library publishing.

The mechanism that makes this work is Gradle module metadata: a trail-geo-1.0.0.module file next to the POM that lists every variant (per target, per usage: API or runtime) and the attributes (org.jetbrains.kotlin.platform.type, target name) Gradle uses to match a consumer’s target to the right file. The root POM only redirects. This is why a KMP library cannot be resolved well by Maven or by Gradle versions that ignore module metadata, and why the JVM and Android publications also stand on their own: a plain Java project can depend on com.example:trail-geo-jvm directly. See Gradle — Gradle Module Metadata.

Apple klibs and frameworks need Apple tooling to link, and Kotlin/Native tiers also decide which targets build where (see How KMP Compiles: Kotlin/JVM, Kotlin/Native, Kotlin/JS and Kotlin/Wasm). The official Maven Central tutorial therefore states the rule bluntly: Apple targets must be built on macOS, so release builds run on one macOS machine that also builds the JVM, Android, JS and Wasm publications. That is why the publishing workflow uses macos-latest and publishes everything in one Gradle invocation.

The single-host rule has a second reason: a Central deployment is one bundle, and the root publication’s module metadata would reference files that do not exist yet if Linux and macOS jobs published separately.

For libraries that only need klib artifacts of Apple targets (no frameworks), the API guidelines point out that cross-compilation allows producing them from any host; that is useful for local experiments, but a release should still come from the macOS pipeline so the XCFramework and the Maven artifacts are built together.

With the legacy com.android.library and androidTarget(), an Android library had build types and product flavors, and you had to opt variants in with androidTarget with publishLibraryVariants("release"); without it no Android publication was created. See Kotlin docs — Set up multiplatform library publishing.

The com.android.kotlin.multiplatform.library plugin removes the problem: it has a single variant with no build types or flavors, so there is nothing to choose, and the Android publication is created automatically. The trade-off is that a library needing flavors or build-type-specific dependencies has to model them with source sets or separate modules. If your library ships Android resources, set a unique namespace, as above, so that the generated R class does not collide with another library’s. See Android Developers — Publish your library.

Maven coordinates are groupId:artifactId:version. Central only lets you publish under a groupId you have proven you own, called your namespace. Registering com.example also allows com.example.trailgeo and any deeper subgroup.

The domain example.com used here is a placeholder; a real library uses a domain or a GitHub namespace the author controls. Verification happens once; afterwards you can delete the TXT record or temporary repository. See Maven Central — Register a namespace.

Central rejects unsigned artifacts. A PGP key pair lets consumers verify that an artifact came from you: the private key signs, the public key (uploaded to a keyserver such as keyserver.ubuntu.com) verifies.

See Kotlin docs — Publish your library to Maven Central.

The Kotlin Gradle plugin also has generatePgpKeys and uploadPublicPgpKey tasks that do the same without a local gpg. In both cases the exported private key is a secret: store it in a password manager or the CI secret store, never in the repository. Details of the Central requirements are at Maven Central — GPG requirements.

com.vanniktech.maven.publish (0.37.0) configures publications, sources and javadoc jars, POM metadata, signing and the upload to the Central Portal. It is the plugin the official Kotlin tutorial recommends.

See Maven Publish Plugin — Publishing to Maven Central.

What each call does:

The plugin reads its credentials from Gradle properties (mavenCentralUsername, mavenCentralPassword, signingInMemoryKeyId, signingInMemoryKeyPassword, signingInMemoryKey), which CI supplies as ORG_GRADLE_PROJECT_* environment variables so that no secret appears in a file.

The user token comes from the Central Portal’s token page; it is a username and password pair that is separate from your portal login. The values above are placeholders.

Run ./gradlew checkSigningConfiguration (key uploaded to a keyserver), ./gradlew checkPomFileForMavenPublication (POM meets Central requirements) and ./gradlew publishToMavenLocal before the first real upload; a Central validation failure after a long macOS build wastes time. Inspect ~/.m2/repository/com/example for the root artifact, the .module file, every target artifact and the .asc signatures, then build a throwaway KMP project against mavenLocal() for each target. See Kotlin docs — Publish your library to Maven Central.

The release workflow runs on a macOS runner when a GitHub release is published. The full pipeline, with caching and the XCFramework job, is in CI/CD for KMP with GitHub Actions; this is the Maven part.

See Kotlin docs — Publish your library to Maven Central.

The publication task runs with --no-configuration-cache because the plugin does not support it, and a released Central version is immutable: run every check above before pressing Publish.

The XCFramework("TrailGeo") helper in the module script registers the assemble tasks. Debug and release variants exist; a release uses the release one.

See Kotlin docs — Build final native binaries.

swift package compute-checksum prints a SHA-256 value that SwiftPM verifies on download, so a tampered or replaced zip fails to resolve. Note the checksum for the next step.

The manifest lives at the repository root, on the tagged commit. The checksum below is a placeholder.

See Apple Developer — Distributing binary frameworks as Swift packages.

In the real file the // swift-tools-version line must be the very first line; the path comment above is only for this page. The iOS app (or another library) then adds the package in Xcode with File > Add Package Dependencies and imports the module in Swift.

See Kotlin docs — Set up Swift package export.

Automating the three manual steps (build, zip and checksum, then update Package.swift and the tag) is the job of the release workflow. Because the checksum is only known after the zip exists, the usual pattern is: build the zip in CI, compute the checksum, commit the updated Package.swift to the release tag, and upload the zip as a release asset. Tooling such as KMMBridge automates this; see iOS Integration Options.

Other routes exist: Swift export (Alpha) generates an idiomatic Swift API without Objective-C headers, CocoaPods is Stable but the documentation steers new projects toward SwiftPM, and a binary SwiftPM package (above) is the simplest for consumers at the cost of hosting and versioning the zip yourself. Swift export and SwiftPM import are Alpha at the baseline, so expect API and Gradle DSL changes between releases and do not make them the only distribution of a library you promise to keep stable. See Objective-C, Swift Interop and Swift Export and Apple Platforms: Swift Packages and Modularization. For the consuming side from inside a KMP project, see Kotlin docs — Add a Swift package dependency.

A long-lived NPM_TOKEN stored as a secret is exactly what an attacker wants. npm Trusted Publishing replaces it with a short-lived OpenID Connect (OIDC) token issued to a specific GitHub repository and workflow: you register the repository and workflow file in the package settings on npmjs.com, and the workflow proves its identity at publish time. No token exists to leak.

See npm — Trusted publishing for npm packages.

The npm job does not need macOS, since a JS package has no Apple parts; running it on Linux in parallel with the macOS job is both cheaper and faster. Trusted Publishing is configured per package in the npm settings, so publish the first version once (by hand or with a token) before attaching a trusted publisher. The general OIDC mechanism is described in GitHub Docs — About security hardening with OpenID Connect.