Package publishing
How the npm, Maven Central and Swift Package Manager artifacts are built, verified and released.
Nothing is published automatically during development. Every release path has a dry run and a protected switch.
npm
Packages: @lynkoria/contracts, @lynkoria/server, @lynkoria/client, @lynkoria/react, @lynkoria/react-native, @lynkoria/scanner-client. ESM with TypeScript declarations (tsdown); @lynkoria/react-native also ships src/ (codegen specs and the react-native entry), android/, ios/ and its podspec.
- Add a changeset:
pnpm changeset. - CI runs
pnpm pack --dry-runfor each package and a built-asset secret scan. release.ymlopens a version PR and publishes with npm Trusted Publishing (OIDC, provenance) only when the repository variableNPM_PUBLISH_ENABLED=true(registry decision, ADR 013).
Packages are ESM only. Each exports map has a default condition, so require() works on Node.js 22.12 and later (ADR 022); there is no separate CommonJS build.
Maven Central (Android)
Coordinates: io.lynkoria:lynkoria-core and io.lynkoria:lynkoria-android, configured with the com.vanniktech.maven.publish plugin (Central Portal, sources and Javadoc jars, POM metadata, signing).
- Dry run:
./gradlew :lynkoria-core:publishToMavenLocal(also in CI). Verified locally: jar, sources jar, Javadoc jar and POM with correct coordinates and dependencies. - Release: run Release native SDKs (
release-native.yml) withdry_run: false. It needsMAVEN_PUBLISH_ENABLED=true, themaven-centralenvironment approval and secretsMAVEN_CENTRAL_USERNAME,MAVEN_CENTRAL_PASSWORD,MAVEN_SIGNING_KEY,MAVEN_SIGNING_KEY_PASSWORD. Theio.lynkorianamespace must be verified in the Central Portal first. lynkoria-androidbuilds with./gradlew build(Android SDK required; GitHub's Ubuntu runners include it).lynkoria-corehas a binary-compatibility dump (api/lynkoria-core.api): run./gradlew updateKotlinAbiand review the diff when its public API changes intentionally.
Swift Package Manager (iOS)
SwiftPM requires Package.swift at a repository root, so sdks/ios is mirrored to a public repository (SWIFT_MIRROR_REPO, e.g. guildsman/lynkoria-swift) with git subtree split and tagged with a plain semantic version (0.1.0). The release job needs SWIFT_MIRROR_ENABLED=true, the swiftpm environment approval and a deploy key (SWIFT_MIRROR_DEPLOY_KEY). After the first tag, the mirror can be submitted to the Swift Package Index.
LYNKORIA_CORE_ONLY=1 builds only LynkoriaCore (no LiveKit resolution), which CI uses on Linux. The full package builds for macOS with swift build; the iOS build of the Lynkoria target (CallKit, PushKit) must be done with Xcode before the first release.
Clean-install checks
scripts/clean-install-check.sh (in CI) packs every npm package as pnpm publish would, installs the tarballs into a fresh npm project and checks ESM imports, require(), strict nodenext types with TypeScript 5, server rendering with LynkoriaProvider, and that the client bundle contains no zod. The Maven dry run publishes lynkoria-core to the local repository in CI.
Still to do before the first release: a React Native 0.88 host app, an Android Compose app using the published coordinates, and a SwiftUI app using the mirrored Swift package. Record results in testing completion criteria.
Versioning
- Every package follows semantic versioning. Before 1.0, a minor version may contain breaking changes and its changeset must say so; after 1.0, breaking changes need a major version and a migration note.
- npm packages are versioned independently by Changesets. Internal dependencies use
workspace:^, so publishing rewrites them to the released ranges. - Android (
VERSION_NAMEinsdks/android/gradle.properties) and Swift (git tag on the mirror) are versioned separately from npm; therelease-native.ymlinput sets both. - Compatibility: every SDK talks to API
/v1, which only changes additively (compatibility). Keeplivekit-client,livekit-androidand LiveKit Swift within the versions tested against the deployed LiveKit server.
Release checklist
- CI is green on
main, including the browser end-to-end suites and native core integration tests. - Changesets describe every user-visible change; breaking changes include a migration note.
- The capability matrix, platform status and SDK pages match the release.
checkKotlinAbipasses, or the ABI diff was reviewed and the dump updated.- For native releases: the Android library and sample build, and an Xcode iOS build of the Swift package succeeds.
- Merge the Changesets version PR (npm), then run
release-native.ymlwithdry_run: true, review, and run it again withdry_run: false. - Record the release in the changelog.