|
| 1 | +# NPM Packaging |
| 2 | + |
| 3 | +This directory contains the npm package structure for distributing the Kosli CLI via npm, following the same pattern used by [esbuild](https://github.com/evanw/esbuild). |
| 4 | + |
| 5 | +## Structure |
| 6 | + |
| 7 | +``` |
| 8 | +npm/ |
| 9 | +├── wrapper/ # @kosli/cli — the package users install |
| 10 | +│ ├── bin/kosli # JS shim that detects the platform and runs the binary |
| 11 | +│ ├── install.js # postinstall script that validates the binary |
| 12 | +│ └── package.json # declares optionalDependencies for all platforms |
| 13 | +├── cli-darwin-arm64/ # @kosli/cli-darwin-arm64 |
| 14 | +│ ├── bin/kosli # the native binary — see below |
| 15 | +│ └── package.json # declares os/cpu fields for platform filtering |
| 16 | +├── cli-darwin-x64/ # @kosli/cli-darwin-x64 |
| 17 | +│ ├── bin/kosli # the native binary — see below |
| 18 | +│ └── package.json # declares os/cpu fields for platform filtering |
| 19 | +├── cli-linux-arm/ # @kosli/cli-linux-arm |
| 20 | +│ ├── bin/kosli # the native binary — see below |
| 21 | +│ └── package.json # declares os/cpu fields for platform filtering |
| 22 | +├── cli-linux-arm64/ # @kosli/cli-linux-arm64 |
| 23 | +│ ├── bin/kosli # the native binary — see below |
| 24 | +│ └── package.json # declares os/cpu fields for platform filtering |
| 25 | +├── cli-linux-x64/ # @kosli/cli-linux-x64 |
| 26 | +│ ├── bin/kosli # the native binary — see below |
| 27 | +│ └── package.json # declares os/cpu fields for platform filtering |
| 28 | +├── cli-win32-arm64/ # @kosli/cli-win32-arm64 |
| 29 | +│ ├── bin/kosli.exe # the native binary — see below |
| 30 | +│ └── package.json # declares os/cpu fields for platform filtering |
| 31 | +└── cli-win32-x64/ # @kosli/cli-win32-x64 |
| 32 | + ├── bin/kosli.exe # the native binary — see below |
| 33 | + └── package.json # declares os/cpu fields for platform filtering |
| 34 | +``` |
| 35 | + |
| 36 | +## How it works |
| 37 | + |
| 38 | +Users install a single package: |
| 39 | + |
| 40 | +```sh |
| 41 | +npm install @kosli/cli |
| 42 | +``` |
| 43 | + |
| 44 | +or if using in continuous integration you can install globally: |
| 45 | + |
| 46 | +```sh |
| 47 | +npm install -g @kosli/cli |
| 48 | +``` |
| 49 | + |
| 50 | +npm resolves the `optionalDependencies` declared in the wrapper's `package.json` and installs only the platform-specific package that matches the current OS and CPU architecture — all non-matching packages are silently skipped. The wrapper's `bin/kosli` JS shim then locates the binary inside the installed platform package and executes it. |
| 51 | + |
| 52 | +> **`npx` is not supported.** `npx @kosli/cli` does not install optional dependencies, so the platform binary is never fetched and the command fails. Always install the package before running it. |
| 53 | +
|
| 54 | +## The `bin/` directories are populated by goreleaser |
| 55 | + |
| 56 | +The platform package `bin/` directories are **not committed to git**. They are populated automatically during the release process by a post-build hook in [`.goreleaser.yml`](../.goreleaser.yml): |
| 57 | + |
| 58 | +```yaml |
| 59 | +hooks: |
| 60 | + post: |
| 61 | + - cmd: >- |
| 62 | + bash -c ' |
| 63 | + OS="{{ .Os }}"; |
| 64 | + ARCH="{{ .Arch }}"; |
| 65 | + [ "$OS" = "windows" ] && OS="win32"; |
| 66 | + [ "$ARCH" = "amd64" ] && ARCH="x64"; |
| 67 | + EXT=""; |
| 68 | + [ "{{ .Os }}" = "windows" ] && EXT=".exe"; |
| 69 | + mkdir -p npm/cli-${OS}-${ARCH}/bin && |
| 70 | + cp "{{ .Path }}" npm/cli-${OS}-${ARCH}/bin/kosli${EXT} && |
| 71 | + chmod +x npm/cli-${OS}-${ARCH}/bin/kosli${EXT}' |
| 72 | +``` |
| 73 | +
|
| 74 | +This hook runs once per build target immediately after goreleaser compiles the binary. It applies the following naming conventions: |
| 75 | +
|
| 76 | +| goreleaser | npm package dir | |
| 77 | +|------------|-----------------| |
| 78 | +| `linux` | `linux` | |
| 79 | +| `darwin` | `darwin` | |
| 80 | +| `windows` | `win32` | |
| 81 | +| `amd64` | `x64` | |
| 82 | +| `arm64` | `arm64` | |
| 83 | +| `arm` | `arm` | |
| 84 | + |
| 85 | +Windows binaries are copied as `kosli.exe`; all others as `kosli`. The `windows/arm` combination is excluded from builds. |
| 86 | + |
| 87 | +The `before` hooks in `.goreleaser.yml` clean up stale artifacts before each build run: |
| 88 | + |
| 89 | +```yaml |
| 90 | +before: |
| 91 | + hooks: |
| 92 | + - rm -rf npm/cli-*/bin |
| 93 | + - find npm -name "*.tgz" -delete |
| 94 | +``` |
| 95 | + |
| 96 | +## Publishing |
| 97 | + |
| 98 | +Packages are published to the [npm public registry](https://registry.npmjs.org). Platform packages must be published before the wrapper, since the wrapper's `optionalDependencies` references them by version. After a goreleaser build has populated the `bin/` directories: |
| 99 | + |
| 100 | +```sh |
| 101 | +# Publish platform packages first |
| 102 | +(cd npm/cli-linux-x64 && npm publish) |
| 103 | +(cd npm/cli-linux-arm64 && npm publish) |
| 104 | +(cd npm/cli-linux-arm && npm publish) |
| 105 | +(cd npm/cli-darwin-x64 && npm publish) |
| 106 | +(cd npm/cli-darwin-arm64 && npm publish) |
| 107 | +(cd npm/cli-win32-x64 && npm publish) |
| 108 | +(cd npm/cli-win32-arm64 && npm publish) |
| 109 | +
|
| 110 | +# Then publish the wrapper |
| 111 | +(cd npm/wrapper && npm publish) |
| 112 | +``` |
| 113 | + |
| 114 | +Each package directory contains an `.npmrc` that sets the auth token: |
| 115 | + |
| 116 | +```text |
| 117 | +//registry.npmjs.org/:_authToken=${NPM_TOKEN} |
| 118 | +``` |
| 119 | + |
| 120 | +## Automated Publishing with npm-publish.sh |
| 121 | + |
| 122 | +The `scripts/npm-publish.sh` script automates the npm packaging and publishing process. It injects the version into all `package.json` files, packs each package into a `.tgz`, and optionally publishes them. |
| 123 | + |
| 124 | +### Usage |
| 125 | + |
| 126 | +```bash |
| 127 | +scripts/npm-publish.sh <version> [--dry-run] |
| 128 | +``` |
| 129 | + |
| 130 | +### Arguments |
| 131 | + |
| 132 | +- `<version>`: Required. A SemVer string — either `X.Y.Z` (stable) or `X.Y.Z-TAG` (pre-release). |
| 133 | +- `--dry-run` (optional second argument): Pack packages but skip publishing. |
| 134 | + |
| 135 | +### Behavior |
| 136 | + |
| 137 | +1. Injects `<version>` into the `version` field of all `package.json` files. |
| 138 | +2. Updates the `optionalDependencies` version references in `npm/wrapper/package.json` to match. |
| 139 | +3. Runs `npm pack` on each platform package, then on the wrapper. |
| 140 | +4. Unless `--dry-run` is set, runs `npm publish --tag <tag>` on each package. |
| 141 | + |
| 142 | +The dist-tag is determined by the version format: |
| 143 | + |
| 144 | +| Version format | npm dist-tag | |
| 145 | +|----------------|--------------| |
| 146 | +| `X.Y.Z` | `latest` | |
| 147 | +| `X.Y.Z-*` | `snapshot` | |
| 148 | + |
| 149 | +### Integration with GoReleaser |
| 150 | + |
| 151 | +GoReleaser calls this script automatically via the `after` hook once all platform binaries have been built and copied into the `bin/` directories: |
| 152 | + |
| 153 | +```yaml |
| 154 | +after: |
| 155 | + hooks: |
| 156 | + - cmd: bash scripts/npm-publish.sh "{{ .Version }}" ... |
| 157 | + output: true |
| 158 | +``` |
| 159 | + |
| 160 | +The script output is surfaced in the goreleaser log (`output: true`). |
| 161 | + |
| 162 | +## Versioning |
| 163 | + |
| 164 | +All packages share the same version number. When releasing, `npm-publish.sh` updates it automatically in all eight `package.json` files — the seven platform packages and the wrapper — as well as the `optionalDependencies` version pins in `npm/wrapper/package.json`. There is no need to edit these files manually. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?v=4&size=40){kind=avatar}
0 commit comments