@orderly.network/npm-release

CLI for releasing npm packages using release-it, with support for environment-based registry/token config, Git auth, pre-release tags, optional internal registry publishing, and Slack notifications.

Features

• release-it driven — Bump version, commit, tag, push, and publish via release-it.
• Environment-based config — Registry URLs and npm tokens via environment variables; no local .release-it.json required.
• Git authentication — GitHub/GitLab push via GIT_TOKEN + GIT_USERNAME; commit identity via GIT_NAME / GIT_EMAIL.
• Pre-release tags — Optional PRERELEASE_TAG (e.g. alpha, beta) for prerelease versions and npm dist-tag.
• Dual registry publish — Publish to public npm first, then publish the same version to an internal registry when NPM_REGISTRY_INTERNAL and NPM_TOKEN_INTERNAL are set.
• Slack notifications — Optional webhook for success/failure after publish.
• Internal registry friendly — When publishing directly to a custom registry (non-npmjs.org), git tag creation is skipped so internal flows stay simple.

Installation and usage

From your project root:

npx @orderly.network/npm-release

Or add it as a devDependency and run it from your package scripts:

pnpm add -D @orderly.network/npm-release

{
  "scripts": {
    "release": "orderly-npm-release"
  }
}

The package also exposes the orderly-npm-release binary directly.

Environment variables

| Variable | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------- | | CI_COMMIT_BRANCH | Current branch in CI. Used to infer a prerelease tag from internal/* branches. | | NPM_REGISTRY | Primary npm registry URL. Defaults to https://registry.npmjs.org. | | NPM_TOKEN | Auth token for the primary registry. Appended to the local .npmrc when set. | | NPM_REGISTRY_INTERNAL | Optional internal registry URL. Used only after a successful public npm publish. | | NPM_TOKEN_INTERNAL | Auth token for NPM_REGISTRY_INTERNAL. Required with NPM_REGISTRY_INTERNAL for dual publishing. | | GIT_TOKEN | Git personal access token for push. Used with GIT_USERNAME to rewrite GitHub/GitLab remote URLs. | | GIT_USERNAME | Git username used with GIT_TOKEN for authenticated Git push. | | GIT_NAME | Git user.name for release commits. | | GIT_EMAIL | Git user.email for release commits. | | RELEASE_VERSION_TYPE | Bump type passed to release-it, usually patch, minor, or major. | | PRERELEASE_TAG | Pre-release identifier (e.g. alpha, beta). Sets release-it preRelease and npm dist-tag. | | SLACK_WEBHOOK_URL | Webhook URL for success/failure Slack notifications. |

All variables are optional. Unset values use defaults or disable the corresponding feature (e.g. no Slack notification if SLACK_WEBHOOK_URL is not set).

Behavior

Internal registry

There are two internal registry flows:

• Direct internal publish: when NPM_REGISTRY is set and is not https://registry.npmjs.org, the CLI publishes to that registry and does not create a git tag. Commits and push still occur; only tagging is skipped.
• Dual publish: when publishing to the public npm registry and both NPM_REGISTRY_INTERNAL and NPM_TOKEN_INTERNAL are set, the CLI runs npm publish --registry <NPM_REGISTRY_INTERNAL> after release-it succeeds. This publishes the same version to the internal registry without another version bump or git operation.

Internal package URLs in Slack notifications use the Verdaccio-style path:

<registry>/-/web/detail/<package-name>

Pre-release

• If PRERELEASE_TAG is set and the current package.json version is already a prerelease with the same preId (e.g. 1.0.0-alpha.0 with tag alpha), the version is incremented as prerelease (e.g. 1.0.0-alpha.1).
• Otherwise, the bump follows RELEASE_VERSION_TYPE (patch, minor, or major). When PRERELEASE_TAG is set, the new version is a prerelease and published under that npm dist-tag.
• If PRERELEASE_TAG is not set and the current branch is internal/<tag>, the CLI uses <tag> as the prerelease tag.

Working directory

The CLI does not require a clean working directory. It is intended to run in CI after pnpm install or build steps that may change the lockfile or generated files.

CI integration

In GitLab CI (or similar), set the needed environment variables and run:

pnpm release

or:

npx @orderly.network/npm-release

When GIT_USERNAME and GIT_TOKEN are set, the CLI rewrites origin before release-it pushes. This also works with GitLab Runner checkout URLs such as https://gitlab-ci-token:<token>@gitlab.com/group/project.git; the existing checkout credentials are ignored and replaced with the configured git token.

Example

Public npm release with an additional internal registry publish:

GIT_NAME="Release Bot" \
GIT_EMAIL="[email protected]" \
GIT_USERNAME="<git-user>" \
GIT_TOKEN="<git-token>" \
NPM_TOKEN="<npm-token>" \
NPM_REGISTRY_INTERNAL="https://npm.example.com" \
NPM_TOKEN_INTERNAL="<internal-npm-token>" \
RELEASE_VERSION_TYPE="patch" \
orderly-npm-release

License

MIT