Markdown

Publishing to npm

Three packages go on npm. Everything else (api, web, database, the other SDKs) does not.

PackageWhat it isInstall
stackliftThe CLI. One bundled file, no runtime dependencies.npm i -g stacklift
@stacklift/sdk-jsClient SDK for JavaScript, React Native, Capacitor, browsers.npm i @stacklift/sdk-js
@stacklift/sdk-electronUpdater 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

  1. Create an npm account and turn on 2FA. Run npm login.
  2. The scoped SDKs need the @stacklift scope: create an organization named stacklift at npmjs.com (free for public packages). If that name is taken, rename the scope in the two SDK package.json files and in the code that imports them.
  3. Check the CLI name is still free: npm view stacklift should say 404. If not, pick another and change name in apps/cli/package.json.
  4. 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

bash
pnpm install
pnpm db:generate && pnpm build:packages
pnpm typecheck && pnpm lint && pnpm test
pnpm pack:check          # lists exactly which files each package would ship

pack: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:

bash
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 --version

Publish by hand (first time)

bash
pnpm --filter @stacklift/sdk-js publish --access public
pnpm --filter @stacklift/sdk-electron publish --access public
pnpm --filter stacklift publish --access public

Publish 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:

  1. Add an npm automation token as the repository secret NPM_TOKEN.
  2. Bump version in the three package.json files, and CLI_VERSION in apps/cli/src/api.ts (a test fails if they differ). Keep them equal.
  3. 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:

bash
STACKLIFT_BUILD_API_URL=https://<hosted api address> pnpm --filter stacklift build

The 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.