npm-publish

GitHub Action to publish to NPM

Publish package

JS-DevTools/npm-publish jstools.dev/npm-publish @jsdevtools/npm-publish

README

Fast, easy publishing to NPM

Publish your packages to npm automatically in GitHub Actions by updating the version number.

Features

- 🧠 **Smart**

Only publishes if the version number in package.json differs from the latest on npm.

- 🛠 **Configurable**

Customize the version-checking behavior, the registry URL, and path of your package.

- 🔐 **Secure**

Keeps your npm authentication token secret. Doesn't read from or write to ~/.npmrc.

- ⚡ **Fast**

100% JavaScript (which is faster than Docker) and bundled to optimize loading time.

- 📤 **Outputs**

Exposes the old and new version numbers, and the type of change (major, minor, patch, etc.) as variables that you can use in your workflow.

Usage

This package can be used three different ways:

- 🤖 A [GitHub Action](#github-action) as part of your CI/CD process

- 🧩 A [function](#javascript-api) that you call in your JavaScript code

- 🖥 A [CLI](#command-line-interface) that you run in your terminal

v2 Migration Guide

The v1 to v2 upgrade brought a few notable breaking changes. To migrate, make the following updates:

- The type output is now an empty string instead of 'none' when no release occurs

diff

- run: echo "Version changed!"

- if: ${{ steps.publish.outputs.type != 'none' }}

+ if: ${{ steps.publish.outputs.type }}

- The --ignore-scripts option is now passed to npm publish as a security precaution. If you define any publish lifecycle scripts - prepublishOnly, prepack, prepare, postpack, publish, postpublish - run them explicitly or set the ignore-scripts input to false.

diff

with:

token: ${{ secrets.NPM_TOKEN }}

+ ignore-scripts: false

- The workflow's .npmrc file is no longer modified. If you have any workarounds to adjust for this misbehavior - for example, if you're using actions/setup-node to configure .npmrc - you should remove them.

diff

- uses: actions/setup-node@v3

with:

node-version: '18'

registry-url: https://registry.npmjs.org/

- uses: JS-DevTools/npm-publish@v1

with:

token: ${{ secrets.NPM_TOKEN }}

- name: Do some more stuff with npm

run: npm whoami

env:

- INPUT_TOKEN: ${{ secrets.NPM_TOKEN }}

+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

- The check-version and greater-version-only options have been removed and replaced with strategy.

- Use strategy: all (default) to publish all versions that do not yet exist in the registry.

diff

with:

token: ${{ secrets.NPM_TOKEN }}

- check-version: true

- greater-version-only: false

+ strategy: all

- Use strategy: upgrade to only publish versions that upgrade the selected tag.

diff

with:

token: ${{ secrets.NPM_TOKEN }}

- check-version: true

- greater-version-only: true

+ strategy: upgrade

- check-version: false has been removed. You may not need this action if you're not checking already published versions; [you can npm directly][publishing-nodejs-packages], instead.

diff

- - uses: JS-DevTools/npm-publish@v1

- with:

- token: ${{ secrets.NPM_TOKEN }}

- check-version: false

+ - uses: actions/setup-node@v3

+ with:

+ node-version: '18'

+ registry-url: https://registry.npmjs.org/

+ - run: npm publish

+ env:

+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

See the [change log][] for more details and other changes in the v2 release.

[publishing-nodejs-packages]: https://docs.github.com/actions/publishing-packages/publishing-nodejs-packages

[change log]: https://github.com/JS-DevTools/npm-publish/releases

GitHub Action

To use the GitHub Action, you'll need to add it as a step in your [workflow file][]. By default, the only thing you need to do is set the token parameter to your [npm authentication token][].

```yaml
on:
push:
branches: main
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: "18"
- run: npm ci
- run: npm test
- uses: JS-DevTools/npm-publish@v2
with:
token: ${{ secrets.NPM_TOKEN }}
```

[workflow file]: https://help.github.com/en/actions/automating-your-workflow-with-github-actions

[npm authentication token]: https://docs.npmjs.com/creating-and-viewing-authentication-tokens

Usage

You can set any or all of the following input parameters using with:

Name	Type	Default	Description
----------------	----------------------	-----------------------------	--------------------------------------------------------------------------------
`token`	string	required	Authentication
`registry`¹	string	`https://registry.npmjs.org/`	Registry
`package`	string	Current	Path
`tag`¹	string	`latest`	[Distribution
`access`¹	`public`,	[npm	Whether
`provenance`¹	boolean	`false`	Run
`strategy`	`all`,	`all`	Use
`ignore-scripts`	boolean	`true`	Run
`dry-run`	boolean	`false`	Run

1. May be specified using publishConfig in package.json.

2. Provenance requires npm >=9.5.0.

[npm-tag]: https://docs.npmjs.com/cli/v9/commands/npm-publish#tag

[npm-access]: https://docs.npmjs.com/cli/v9/commands/npm-publish#access

[provenance]: https://docs.npmjs.com/generating-provenance-statements

Output

npm-publish exposes some output variables, which you can use in later steps of your workflow. To access the output variables, you'll need to set an id for the npm-publish step.

```yaml
steps:
- id: publish
uses: JS-DevTools/npm-publish@v2
with:
token: ${{ secrets.NPM_TOKEN }}
- if: ${{ steps.publish.outputs.type }}
run: |
echo "Version changed!"
```

Name	Type	Description
-------------	-------	-------------------------------------------------------------------------------------------------------------
`id`	string	Package
`type`	string	[Semver
`name`	string	Name
`version`	string	Version
`old-version`	string	Previously
`tag`	string	[Distribution
`access`	string	[Access
`registry`	string	Registry
`dry-run`	boolean	Whether

[semver release type]: https://github.com/npm/node-semver#release_types

JavaScript API

To use npm-package in your JavaScript code, you'll need to install it using [npm][] or other package manager of choice:

```bash
npm install --save-dev @jsdevtools/npm-publish
```

You can then import it and use it in your code like this:

```javascript
import { npmPublish } from "@jsdevtools/npm-publish";
// Run npm-publish with all defaults
await npmPublish({ token: "YOUR_NPM_AUTH_TOKEN_HERE" });
```

[npm]: https://docs.npmjs.com/about-npm/

Usage

As shown in the example above, you should pass an options object to the npmPublish function. In TypeScript, the Options interface is available as an import.

```ts
import type { Options } from "@jsdevtools/npm-publish";
```

Name	Type	Default	Description
--------------------	----------------------	-----------------------------	--------------------------------------------------------------------------------
`token`	string	required	Authentication
`registry`¹	string,	`https://registry.npmjs.org/`	Registry
`package`	string	Current	Path
`tag`¹	string	`latest`	[Distribution
`access`¹	`public`,	[npm	Whether
`provenance`¹	boolean	`false`	Run
`strategy`	`all`,	`all`	Use
`ignoreScripts`	boolean	`true`	Run
`dryRun`	boolean	`false`	Run
`logger`	object	`undefined`	Logging
`temporaryDirectory`	string	`os.tmpdir()`	Temporary

1. May be specified using publishConfig in package.json.

2. Provenance requires npm >=9.5.0.

Output

The npmPublish() function returns a promise of a Results object. In TypeScript, the Results interface is available as an import.

```ts
import type { Results } from "@jsdevtools/npm-publish";
```

Name	Type	Description
------------	---------------	---------------------------------------------------------------------------------------------------------------
`id`	Optional	Package
`type`	Optional	[Semver
`name`	string	Name
`version`	string	Version
`oldVersion`	Optional	Previously
`tag`	string	[Distribution
`access`	Optional	[Access
`registry`	`URL`	Registry
`dryRun`	boolean	Whether

Command Line Interface

You can also use npm-publish as a command-line tool in your terminal.

```bash
npm install --save-dev @jsdevtools/npm-publish
```

You can then use it in your terminal or in npm run scripts.

```bash
npx npm-publish --token YOUR_NPM_AUTH_TOKEN_HERE
```

You can customize your call with options to change the registry, package, etc.

```bash
npx npm-publish --token YOUR_NPM_AUTH_TOKEN_HERE --registry http://example.com ./path/to/package
```

Options

Run npm-publish --help to see the full list of options available.

```
Usage:
npm-publish <options> [package]
Arguments:
package The path to the package to publish.
May be a directory, package.json, or .tgz file.
Defaults to the package in the current directory.
Options:
--token <token> (Required) npm authentication token.
--registry <url> Registry to read from and write to.
Defaults to "https://registry.npmjs.org/".
--tag <tag> The distribution tag to check against and publish to.
Defaults to "latest".
--access <access> Package access, may be "public" or "restricted".
See npm documentation for details.
--provenance Publish with provenance statements.
See npm documentation for details.
--strategy <strategy> Publish strategy, may be "all" or "upgrade".
Defaults to "all", see documentation for details.
--no-ignore-scripts Allow lifecycle scripts, which are disabled by default
as a security precaution. Defaults to false.
--dry-run Do not actually publish anything.
--quiet Only print errors.
--debug Print debug logs.
-v, --version Print the version number.
-h, --help Show usage text.
Examples:
$ npm-publish --token abc123 ./my-package
```

License

npm-publish is 100% free and open-source, under the MIT license. Use it however you want.

This package is Treeware. If you use it in production, then we ask that you [buy the world a tree](https://plant.treeware.earth/JS-DevTools/npm-publish) to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.