Publishing and maintaining SDK packages

The publishable web packages are @qbflex/client and @qbflex/react. They release at the same version; React declares the matching client line as a peer. @qb-flex/management-client stays private. The planned @qbflex/react-native package is a separate incomplete expanded-release requirement.

Before the first release

Create an npm organization named qbflex if it does not already exist; the organization name creates the @qbflex scope. Add the publishing account with package write access. The release owner must also enable npm two-factor authentication and choose the package license. This private checkout currently has no license file, so do not infer or add an open-source license during publication.

Authenticate and confirm the target registry:

npm login
npm whoami
npm org ls qbflex
npm config get registry

Package manifests explicitly use the public npm registry and public access. An unavailable public package name does not prove that the current account owns the scope.

Version both packages

Use a patch for compatible fixes, a minor for compatible features, and a major for breaking APIs after 1.0.0. While the SDK is below 1.0.0, breaking APIs must at least bump the minor version and be called out in the release notes. Consumers must not assume that 0.2.x is compatible with 0.1.x; the React peer range intentionally keeps them on the same minor SDK line.

bun run sdk:version 0.1.1
bun run sdk:release:check

Review and commit the version and user-visible release notes. npm versions are immutable; never reuse a published version. Prerelease versions such as 0.2.0-rc.1 use the next distribution tag by default.

Dry run and publish

bun run sdk:publish

This is a dry run. It packs both packages, installs them into an isolated npm consumer, checks declarations without skipLibCheck, exercises SSR and the client under Node, and runs npm's publication inspection without changing the registry.

From a clean, reviewed checkout, publish the client followed by React:

bun run sdk:publish -- --execute

Override the tag with --tag next. Use --provenance only in a supported public CI environment; npm does not provide provenance for a private source repository. Publication is not atomic across the package pair. If React fails after the client succeeds, fix the release condition and publish React at the same version—never overwrite or reuse the client version.

After release, verify npm view metadata and install both exact versions in a clean application. The complete maintainer checklist is in docs/sdk-releases.md in the source repository. No npm package is published merely by building, packing or running a dry run.

Loading article…