{"id":13454929,"url":"https://github.com/JS-DevTools/npm-publish","last_synced_at":"2025-03-24T07:32:13.878Z","repository":{"id":37710831,"uuid":"235231513","full_name":"JS-DevTools/npm-publish","owner":"JS-DevTools","description":"GitHub Action to publish to NPM","archived":false,"fork":false,"pushed_at":"2025-01-27T21:55:39.000Z","size":2143,"stargazers_count":634,"open_issues_count":3,"forks_count":77,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-20T06:12:39.015Z","etag":null,"topics":["github-action","javascript","nodejs","npm","npm-publish","typescript","version-bump","version-checker"],"latest_commit_sha":null,"homepage":"https://jstools.dev/npm-publish","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JS-DevTools.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-21T01:25:58.000Z","updated_at":"2025-03-20T02:55:40.000Z","dependencies_parsed_at":"2024-01-01T20:25:38.118Z","dependency_job_id":"9f11efc2-a6bb-477e-9853-9eed691d2d16","html_url":"https://github.com/JS-DevTools/npm-publish","commit_stats":{"total_commits":232,"total_committers":17,"mean_commits":"13.647058823529411","dds":0.4267241379310345,"last_synced_commit":"e06fe3ef65499b38eb12224f2a60979f6d797330"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":"JS-DevTools/template-node-typescript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JS-DevTools%2Fnpm-publish","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JS-DevTools%2Fnpm-publish/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JS-DevTools%2Fnpm-publish/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JS-DevTools%2Fnpm-publish/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JS-DevTools","download_url":"https://codeload.github.com/JS-DevTools/npm-publish/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244560393,"owners_count":20472220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-action","javascript","nodejs","npm","npm-publish","typescript","version-bump","version-checker"],"created_at":"2024-07-31T08:00:59.498Z","updated_at":"2025-03-24T07:32:13.871Z","avatar_url":"https://github.com/JS-DevTools.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","typescript"],"sub_categories":[],"readme":"# Fast, easy publishing to NPM\n\n[![Build Status](https://github.com/JS-DevTools/npm-publish/workflows/CI-CD/badge.svg)](https://github.com/JS-DevTools/npm-publish/actions)\n[![Coverage Status](https://coveralls.io/repos/github/JS-DevTools/npm-publish/badge.svg?branch=main)](https://coveralls.io/github/JS-DevTools/npm-publish)\n[![npm](https://img.shields.io/npm/v/@jsdevtools/npm-publish.svg)](https://www.npmjs.com/package/@jsdevtools/npm-publish)\n[![License](https://img.shields.io/npm/l/@jsdevtools/npm-publish.svg)](LICENSE)\n[![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](https://plant.treeware.earth/JS-DevTools/npm-publish)\n\nPublish packages to npm automatically in GitHub Actions by updating the version number.\n\n- [Change log][releases]\n- [v2 to v3 migration guide](#v2-to-v3)\n- [v1 to v3 migration guide](#v1-to-v3)\n\n[releases]: https://github.com/JS-DevTools/npm-publish/releases\n\n## Features\n\n- 🧠 **Smart**\n  Only publishes if the version number in `package.json` differs from the latest on npm.\n\n- 🛠 **Configurable**\n  Customize the version-checking behavior, the registry URL, and path of your package.\n\n- 🔐 **Secure**\n  Keeps your npm authentication token secret. Doesn't read nor write to `~/.npmrc`.\n\n- ⚡ **Fast**\n  100% JavaScript (which is faster than Docker) and bundled to optimize loading time.\n\n- 📤 **Outputs**\n  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.\n\n## Usage\n\nThis package can be used three different ways:\n\n- 🤖 A [**GitHub Action**](#github-action) as part of your CI/CD process\n\n- 🧩 A [**function**](#javascript-api) that you call in your JavaScript code\n\n- 🖥 A [**CLI**](#command-line-interface) that you run in your terminal\n\n## GitHub Action\n\nTo 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][].\n\n```yaml\non:\n  push:\n    branches: main\n\njobs:\n  publish:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v3\n        with:\n          node-version: \"20\"\n      - run: npm ci\n      - run: npm test\n      - uses: JS-DevTools/npm-publish@v3\n        with:\n          token: ${{ secrets.NPM_TOKEN }}\n```\n\nYou can also publish to third-party registries. For example, to publish to the [GitHub Package Registry][], set `token` to `secrets.GITHUB_TOKEN` and `registry` to `https://npm.pkg.github.com`:\n\n```yaml\non:\n  push:\n    branches: main\n\njobs:\n  publish:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      packages: write # allow GITHUB_TOKEN to publish packages\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v3\n        with:\n          node-version: \"20\"\n      - run: npm ci\n      - run: npm test\n      - uses: JS-DevTools/npm-publish@v3\n        with:\n          token: ${{ secrets.GITHUB_TOKEN }}\n          registry: \"https://npm.pkg.github.com\"\n```\n\n[workflow file]: https://help.github.com/en/actions/automating-your-workflow-with-github-actions\n[npm authentication token]: https://docs.npmjs.com/creating-and-viewing-authentication-tokens\n[GitHub Package Registry]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry\n\n### Action usage\n\nYou can set any or all of the following input parameters using `with`:\n\n| Name             | Type                   | Default                       | Description                                                                      |\n| ---------------- | ---------------------- | ----------------------------- | -------------------------------------------------------------------------------- |\n| `token`          | string                 | **required**                  | Authentication token to use with the configured registry.                        |\n| `registry`¹      | string                 | `https://registry.npmjs.org/` | Registry URL to use.                                                             |\n| `package`        | string                 | Current working directory     | Path to a package directory, a `package.json`, or a packed `.tgz` to publish.    |\n| `tag`¹           | string                 | `latest`                      | [Distribution tag][npm-tag] to publish to.                                       |\n| `access`¹        | `public`, `restricted` | [npm defaults][npm-access]    | Whether the package should be publicly visible or restricted.                    |\n| `provenance`¹ ²  | boolean                | `false`                       | Run `npm publish` with the `--provenance` flag to add [provenance][] statements. |\n| `strategy`       | `all`, `upgrade`       | `all`                         | Use `all` to publish all unique versions, `upgrade` for only semver upgrades.    |\n| `ignore-scripts` | boolean                | `true`                        | Run `npm publish` with the `--ignore-scripts` flag as a security precaution.     |\n| `dry-run`        | boolean                | `false`                       | Run `npm publish` with the `--dry-run` flag to prevent publication.              |\n\n1. May be specified using `publishConfig` in `package.json`.\n2. Provenance requires npm `\u003e=9.5.0`.\n\n[npm-tag]: https://docs.npmjs.com/cli/v9/commands/npm-publish#tag\n[npm-access]: https://docs.npmjs.com/cli/v9/commands/npm-publish#access\n[provenance]: https://docs.npmjs.com/generating-provenance-statements\n\n### Action output\n\nnpm-publish exposes several output variables, which you can use in later steps of your workflow if you provide an `id` for the npm-publish step.\n\n```diff\n  steps:\n    - uses: JS-DevTools/npm-publish@v3\n+     id: publish\n      with:\n        token: ${{ secrets.NPM_TOKEN }}\n\n+   - if: ${{ steps.publish.outputs.type }}\n+     run: echo \"Version changed!\"\n```\n\n| Name          | Type    | Description                                                                                                   |\n| ------------- | ------- | ------------------------------------------------------------------------------------------------------------- |\n| `id`          | string  | Package identifier of the release: `${name}@${version}` or empty if no release.                               |\n| `type`        | string  | [Semver release type][], `initial` if first release, `different` if other change, or empty if no release.     |\n| `name`        | string  | Name of the package.                                                                                          |\n| `version`     | string  | Version of the package.                                                                                       |\n| `old-version` | string  | Previously published version on `tag` or empty if no previous version on tag.                                 |\n| `tag`         | string  | [Distribution tag][npm-tag] the package was published to.                                                     |\n| `access`      | string  | [Access level][npm-access] the package was published with, or `default` if scoped-package defaults were used. |\n| `registry`    | string  | Registry the package was published to.                                                                        |\n| `dry-run`     | boolean | Whether `npm publish` was run in \"dry run\" mode.                                                              |\n\n[semver release type]: https://github.com/npm/node-semver#release_types\n\n## JavaScript API\n\nTo use npm-package in your JavaScript code, you'll need to install it using [npm][] or other package manager of choice:\n\n```bash\nnpm install --save-dev @jsdevtools/npm-publish\n```\n\nYou can then import it and use it in your code like this:\n\n```javascript\nimport { npmPublish } from \"@jsdevtools/npm-publish\";\n\n// Run npm-publish with all defaults\nawait npmPublish({ token: \"YOUR_NPM_AUTH_TOKEN_HERE\" });\n```\n\n[npm]: https://docs.npmjs.com/about-npm/\n\n### API usage\n\nAs 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.\n\n```ts\nimport type { Options } from \"@jsdevtools/npm-publish\";\n```\n\n| Name                 | Type                   | Default                       | Description                                                                      |\n| -------------------- | ---------------------- | ----------------------------- | -------------------------------------------------------------------------------- |\n| `token`              | string                 | **required**                  | Authentication token to use with the configured registry.                        |\n| `registry`¹          | string, `URL`          | `https://registry.npmjs.org/` | Registry URL to use.                                                             |\n| `package`            | string                 | Current working directory     | Path to a package directory, a `package.json`, or a packed `.tgz` to publish.    |\n| `tag`¹               | string                 | `latest`                      | [Distribution tag][npm-tag] to publish to.                                       |\n| `access`¹            | `public`, `restricted` | [npm defaults][npm-access]    | Whether the package should be publicly visible or restricted.                    |\n| `provenance`¹ ²      | boolean                | `false`                       | Run `npm publish` with the `--provenance` flag to add [provenance][] statements. |\n| `strategy`           | `all`, `upgrade`       | `all`                         | Use `all` to publish all unique versions, `upgrade` for only semver upgrades.    |\n| `ignoreScripts`      | boolean                | `true`                        | Run `npm publish` with the `--ignore-scripts` flag as a security precaution.     |\n| `dryRun`             | boolean                | `false`                       | Run `npm publish` with the `--dry-run` flag to prevent publication.              |\n| `logger`             | object                 | `undefined`                   | Logging interface with `debug`, `info`, and `error` log methods.                 |\n| `temporaryDirectory` | string                 | `os.tmpdir()`                 | Temporary directory to hold a generated `.npmrc` file                            |\n\n1. May be specified using `publishConfig` in `package.json`.\n2. Provenance requires npm `\u003e=9.5.0`.\n\n### API output\n\nThe `npmPublish()` function returns a promise of a `Results` object. In TypeScript, the `Results` interface is available as an import.\n\n```ts\nimport type { Results } from \"@jsdevtools/npm-publish\";\n```\n\n| Name         | Type            | Description                                                                                                     |\n| ------------ | --------------- | --------------------------------------------------------------------------------------------------------------- |\n| `id`         | Optional string | Package identifier of the release: `${name}@${version}` or `undefined` if no release.                           |\n| `type`       | Optional string | [Semver release type][], `initial` if first release, `different` if other change, or `undefined` if no release. |\n| `name`       | string          | Name of the package.                                                                                            |\n| `version`    | string          | Version of the package.                                                                                         |\n| `oldVersion` | Optional string | Previously published version on `tag` or `undefined` if no previous version.                                    |\n| `tag`        | string          | [Distribution tag][npm-tag] that the package was published to.                                                  |\n| `access`     | Optional string | [Access level][npm-access] the package was published with, or `undefined` if scoped-package defaults were used. |\n| `registry`   | `URL`           | Registry the package was published to.                                                                          |\n| `dryRun`     | boolean         | Whether `npm publish` was run in \"dry run\" mode.                                                                |\n\n## Command Line Interface\n\nYou can also use `npm-publish` as a command-line tool in your terminal.\n\n```bash\nnpm install --save-dev @jsdevtools/npm-publish\n```\n\nYou can then use it in your terminal or in `npm run` scripts.\n\n```bash\nnpx npm-publish --token YOUR_NPM_AUTH_TOKEN_HERE\n```\n\nYou can customize your call with options to change the registry, package, etc.\n\n```bash\nnpx npm-publish --token YOUR_NPM_AUTH_TOKEN_HERE --registry http://example.com ./path/to/package\n```\n\n### Options\n\nRun `npm-publish --help` to see the full list of options available.\n\n```text\nUsage:\n\n  npm-publish \u003coptions\u003e [package]\n\nArguments:\n\n  package                 The path to the package to publish.\n                          May be a directory, package.json, or .tgz file.\n                          Defaults to the package in the current directory.\n\nOptions:\n\n  --token \u003ctoken\u003e         (Required) npm authentication token.\n\n  --registry \u003curl\u003e        Registry to read from and write to.\n                          Defaults to \"https://registry.npmjs.org/\".\n\n  --tag \u003ctag\u003e             The distribution tag to check against and publish to.\n                          Defaults to \"latest\".\n\n  --access \u003caccess\u003e       Package access, may be \"public\" or \"restricted\".\n                          See npm documentation for details.\n\n  --provenance            Publish with provenance statements.\n                          See npm documentation for details.\n\n  --strategy \u003cstrategy\u003e   Publish strategy, may be \"all\" or \"upgrade\".\n                          Defaults to \"all\", see documentation for details.\n\n  --no-ignore-scripts     Allow lifecycle scripts, which are disabled by default\n                          as a security precaution. Defaults to false.\n\n  --dry-run               Do not actually publish anything.\n  --quiet                 Only print errors.\n  --debug                 Print debug logs.\n\n  -v, --version           Print the version number.\n  -h, --help              Show usage text.\n\nExamples:\n\n  $ npm-publish --token abc123 ./my-package\n```\n\n## Migration guides\n\nMajor releases of the action and libraries may contain breaking changes, documented here.\nFor more detailed change logs, see [releases][].\n\n### v2 to v3\n\nThe v3 release does not require any changes to how you use `npm-publish` from `v2`. The version of Node.js used by the action was updated to v20 due to GitHub Action's [deprecation of Node.js v16][node16-deprecation]. The minimum required version of Node.js for the library and CLI remains v16.\n\n[node16-deprecation]: https://github.blog/changelog/2023-09-22-github-actions-transitioning-from-node-16-to-node-20/\n\n### v1 to v3\n\nThe v2 release made several breaking changes to inputs, outputs, and behaviors that were present in `v1`. The examples below focus on the action, but the same changes are applicable to the library and CLI, too.\n\n#### v2 option changes\n\nThe `check-version` and `greater-version-only` boolean options were replaced with the `strategy` option:\n\n- `strategy: all` (default) will publish any version that does not yet exist in the registry\n- `strategy: upgrade` will publish only if the version is a semver upgrade of the requested `dist-tag`\n\n```diff\n  with:\n    token: ${{ secrets.NPM_TOKEN }}\n-   check-version: true\n-   greater-version-only: false\n+   strategy: all\n\n  with:\n    token: ${{ secrets.NPM_TOKEN }}\n-   check-version: true\n-   greater-version-only: true\n+   strategy: upgrade\n```\n\n`check-version: false` has been removed. If you only need to publish, without first checking whether the version exists in the registry, you can [use `npm` directly][publishing-nodejs-packages] instead:\n\n```diff\n  - uses: actions/setup-node@v3\n    with:\n      node-version: '18'\n+     registry-url: https://registry.npmjs.org/\n\n- - uses: JS-DevTools/npm-publish@v1\n-   with:\n-     token: ${{ secrets.NPM_TOKEN }}\n-     check-version: false\n+ - run: npm publish\n+   env:\n+     NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n```\n\n[publishing-nodejs-packages]: https://docs.github.com/actions/publishing-packages/publishing-nodejs-packages\n\n#### v2 output changes\n\nThe `type` output is now an empty string instead of `'none'` when no release occurs\n\n```diff\n  - run: echo \"Version changed!\"\n-   if: ${{ steps.publish.outputs.type != 'none' }}\n+   if: ${{ steps.publish.outputs.type }}\n```\n\n#### v2 behavior changes\n\nThe `--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` - we recommend you run that logic as a separate explicit build step.\n\n```diff\n+ - run: npm run build\n\n- - uses: JS-DevTools/npm-publish@v1\n+ - uses: JS-DevTools/npm-publish@v3\n    with:\n      token: ${{ secrets.NPM_TOKEN }}\n```\n\nIf you can't change your build, you can set the `ignore-scripts` input to `false` as a workaround. Be aware that failures during a lifecycle script can be difficult to debug, and any `stdout`/`stderr` output from your build script could interfere with how `npm-publish` interprets results from the `npm` CLI.\n\n```diff\n- - uses: JS-DevTools/npm-publish@v1\n+ - uses: JS-DevTools/npm-publish@v3\n    with:\n      token: ${{ secrets.NPM_TOKEN }}\n+     ignore-scripts: false\n```\n\nThe global `.npmrc` file is no longer read nor modified. This means the `token` option is now required for the library and CLI. (It was already required for the action.) You may have workarounds in place referencing `INPUT_TOKEN`, which v1 [erroneously wrote][#15] to `.npmrc`. These workarounds should be removed.\n\n```diff\n  - uses: actions/setup-node@v3\n    with:\n      node-version: '18'\n      registry-url: https://registry.npmjs.org/\n\n- - uses: JS-DevTools/npm-publish@v1\n+ - uses: JS-DevTools/npm-publish@v3\n    with:\n      token: ${{ secrets.NPM_TOKEN }}\n\n  - name: Do some more stuff with npm\n    run: npm whoami\n    env:\n-     INPUT_TOKEN: ${{ secrets.NPM_TOKEN }}\n+     NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n```\n\n[#15]: https://github.com/JS-DevTools/npm-publish/issues/15\n\n## License\n\nnpm-publish is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.\n\nThis package is [Treeware](http://treeware.earth). 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.\n\n## Big Thanks To\n\nThanks to these awesome companies for their support of Open Source developers ❤\n\n[![GitHub](https://jstools.dev/img/badges/github.svg)](https://github.com/open-source)\n[![NPM](https://jstools.dev/img/badges/npm.svg)](https://www.npmjs.com/)\n[![Coveralls](https://jstools.dev/img/badges/coveralls.svg)](https://coveralls.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJS-DevTools%2Fnpm-publish","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJS-DevTools%2Fnpm-publish","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJS-DevTools%2Fnpm-publish/lists"}