Publishing to npm
Three packages go on npm. Everything else (api, web, database, the other SDKs) does not.
| Package | What it is | Install |
|---|---|---|
stacklift | The CLI. One bundled file, no runtime dependencies. | npm i -g stacklift |
@stacklift/sdk-js | Client SDK for JavaScript, React Native, Capacitor, browsers. | npm i @stacklift/sdk-js |
@stacklift/sdk-electron | Updater for Electron apps (depends on sdk-js). | npm i @stacklift/sdk-electron |
The Swift, Dart, .NET, Java, Kotlin and Rust SDKs use their own registries (SwiftPM, pub.dev, NuGet, Maven Central, crates.io) and are not covered here.
One-time setup
- Create an npm account and turn on 2FA. Run
npm login. - The scoped SDKs need the
@stackliftscope: create an organization namedstackliftat npmjs.com (free for public packages). If that name is taken, rename the scope in the two SDKpackage.jsonfiles and in the code that imports them. - Check the CLI name is still free:
npm view stackliftshould say 404. If not, pick another and changenameinapps/cli/package.json. - The licence is MIT, copyright "Stacklift contributors" (see
LICENSE). Change it before the first publish if you want something else; a published version's licence cannot be taken back.
Check before you publish
pnpm install
pnpm db:generate && pnpm build:packages
pnpm typecheck && pnpm lint && pnpm test
pnpm pack:check # lists exactly which files each package would shippack:check is a dry run. Each tarball should contain only dist/, bin/ (CLI), README.md, LICENSE and package.json. The CLI is a single ~700 kB file.
To try the real thing in a clean folder:
mkdir /tmp/try && cd /tmp/try && npm init -y
(cd <repo>/apps/cli && pnpm pack --pack-destination /tmp/try)
npm i ./stacklift-0.1.0.tgz && npx stacklift --versionPublish by hand (first time)
pnpm --filter @stacklift/sdk-js publish --access public
pnpm --filter @stacklift/sdk-electron publish --access public
pnpm --filter stacklift publish --access publicPublish sdk-js before sdk-electron, which depends on it. pnpm replaces workspace:* with the real version number when it packs. prepack rebuilds each package first, so a stale dist cannot ship. A published version can never be overwritten; if you made a mistake, bump the version and publish again (npm deprecate flags the bad one).
Releases from CI
.github/workflows/release.yml publishes all three when you push a version tag:
- Add an npm automation token as the repository secret
NPM_TOKEN. - Bump
versionin the threepackage.jsonfiles, andCLI_VERSIONinapps/cli/src/api.ts(a test fails if they differ). Keep them equal. - Commit, then
git tag v0.1.1 && git push --tags.
The workflow refuses to run if the tag and the package versions disagree, runs typecheck, lint and the package tests, and publishes with provenance (npm shows a "built from this commit" badge). It has not been run yet: the first real tag is its first test, so do the first release by hand.
Which API the published CLI talks to
A CLI built from source talks to http://localhost:4000 unless STACKLIFT_API_URL is set. The published one must default to the hosted API, which is fixed when the bundle is built:
STACKLIFT_BUILD_API_URL=https://<hosted api address> pnpm --filter stacklift buildThe release workflow sets it to https://stacklift-api.joynul.com for the build step, so a tagged release talks to the hosted API by default. Users can still override it with --api-url or STACKLIFT_API_URL. If the API hostname ever changes, update it in .github/workflows/release.yml and keep the old hostname working for as long as old CLI versions are in use.
Why the CLI is bundled
apps/cli is built with esbuild into one file that contains @stacklift/shared, @stacklift/adapters, @stacklift/sdk-core, commander, yaml and zod. That is why those appear only as devDependencies: nothing is installed alongside it, so it cannot break on a mismatched internal package, and those internal packages never need publishing.