<!-- Stacklift documentation: "Publishing to npm". Source: https://stacklift.joynul.com/docs/publishing · All pages for LLMs: https://stacklift.joynul.com/llms-full.txt -->

> About Stacklift: Stacklift is a hosted platform with source-available SDKs for shipping app releases and over-the-air updates. It works for mobile (React Native, Expo, Flutter, native iOS and Android, Kotlin Multiplatform, .NET MAUI, Unity), web, desktop (Electron, .NET, Java) and backend apps. Developers create releases with the `stacklift` CLI or the dashboard; the server verifies and signs every artifact (SHA-256 + Ed25519), deploys releases to channels with staged rollouts and rollback, and app SDKs check, download and verify updates. Native apps can change screens over the air with server-driven UI layouts and logic with sandboxed scripts, within App Store and Google Play rules. Apps never depend on Stacklift to keep working: everything has a built-in fallback and an exit path.
>
> This page: How the CLI and JavaScript SDKs are released to npm.

# 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

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.
