# @bluecargo/npm-publish
> Fast, easy publishing to NPM
Latest version **2.0.3** (published 2022-10-18) · MIT license · 0 weekly downloads
## Install
```sh
npm install @bluecargo/npm-publish
pnpm add @bluecargo/npm-publish
yarn add @bluecargo/npm-publish
bun add @bluecargo/npm-publish
```
Provides the command `npm-publish`.
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 2.0.3 |
| Published | 2022-10-18 |
| First published | 2022-10-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=16 |
| Dependencies | 4 |
| Unpacked size | 59.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | bluecargo |
| Maintainers | bluecargo-admin |
| Keywords | github-action, npm, publish, version, bump |
## Links
- npm: https://www.npmjs.com/package/@bluecargo/npm-publish
- Repository: https://github.com/bluecargo/npm-publish
- Homepage: https://jstools.dev/npm-publish
- Issues: https://github.com/bluecargo/npm-publish/issues
- npm.io page: https://npm.io/package/@bluecargo/npm-publish
## Dependencies (4)
- [semver](https://npm.io/package/semver.md) ^7.3.4
- [@jsdevtools/ono](https://npm.io/package/@jsdevtools/ono.md) ^7.1.3
- [command-line-args](https://npm.io/package/command-line-args.md) ^5.1.1
- [@jsdevtools/ez-spawn](https://npm.io/package/@jsdevtools/ez-spawn.md) ^3.0.4
## Recent versions
- 2.0.3 (latest) — 2022-10-18
- 2.0.2 — 2022-10-18
- 2.0.1 — 2022-10-18
- 2.0.0 — 2022-10-18
## README
# Fast, easy publishing to NPM
[](https://github.com/JS-DevTools/npm-publish/actions)
[](https://github.com/bluecargo/npm-publish/actions)
[](https://coveralls.io/github/JS-DevTools/npm-publish)
[](https://david-dm.org/JS-DevTools/npm-publish)
[](https://www.npmjs.com/package/@jsdevtools/npm-publish)
[](LICENSE)
[](https://plant.treeware.earth/JS-DevTools/npm-publish)
## 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 access token secret. Doesn't write it 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-function) that you call in your JavaScript code
- 🖥 A [**CLI**](#command-line-interface) that you run in your terminal
## GitHub Action
To use the GitHub Action, you'll need to add it as a step in your [Workflow file](https://help.github.com/en/actions/automating-your-workflow-with-github-actions). By default, the only thing you need to do is set the `token` parameter to your [NPM auth token](https://docs.npmjs.com/creating-and-viewing-authentication-tokens).
```yaml
on: push
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 12
- run: npm install
- run: npm test
- uses: bluecargo/npm-publish@v2
with:
token: ${{ secrets.NPM_TOKEN }}
```
## Input Parameters
You can set any or all of the following input parameters:
|Name |Type |Default |Description
|----------------------|-------- |----------------------------|------------------------------------
|`token` |string |**required** |The NPM auth token to use for publishing
|`registry` |string |https://registry.npmjs.org/ |The NPM registry URL to use
|`package` |string |./package.json |The path of your package.json file
|`tag` |string |"latest" |The tag to publish to. This allows people to install the package using `npm install @`.
|`access` |string |"public" for non-scoped packages. "restricted" for scoped packages.|Determines whether the published package should be publicly visible, or restricted to members of your NPM organization.
|`dry-run` |boolean |false |Run NPM publish with the `--dry-run` flag to prevent publication
|`check-version` |boolean |true |Only publish to NPM if the version number in `package.json` differs from the latest on NPM
|`greater-version-only`|boolean |false |Only publish to NPM if the version number in `package.json` is greater than the latest on NPM |
## Output Variables
npm-publish writes env variables, which you can use in later steps of your workflow.
```yaml
steps:
- id: publish
uses: bluecargo/npm-publish@v2
with:
token: ${{ secrets.NPM_TOKEN }}
- run: |
echo "Version changed: ${{ env.old-version }} => ${{ env.version }}"
```
| Variable | Type | Description |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | The type of version change that occurred ("major", "minor", "patch", etc.). If there was no version change, then type will be "none". If `greater-version-only` is set and the version is lower, then type will be "lower". |
| `version` | string | The version that was published |
| `old-version` | string | The version number that was previously published to NPM |
| `tag` | string | The tag that the package was published to. |
| `access` | string | Indicates whether the published package is publicly visible or restricted to members of your NPM organization. |
| `dry-run` | boolean | Indicates whether NPM was run in "dry run" mode |
## JavaScript Function
To use npm-package in your JavaScript code, you'll need to install it using [NPM](https://docs.npmjs.com/about-npm/):
```bash
npm install @jsdevtools/npm-publish
```
You can then import it and use it in your code like this:
```javascript
const npmPublish = require("@jsdevtools/npm-publish");
// Run npm-publish with all defaults
await npmPublish();
// Run npm-publish with options
await npmPublish({
package: "./path/to/package.json",
token: "YOUR_NPM_AUTH_TOKEN_HERE",
});
```
### Options
As shown in the example above, you can pass options to the `npmPublish()` function. Here are the available options:
| Name | Type | Default | Description |
| -------------------- | -------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token` | string | NPM's default credentials | The NPM auth token to use for publishing. If not set, then NPM will |
| `registry` | string | https://registry.npmjs.org/ | The NPM registry URL to use |
| `package` | string | ./package.json | The path of your package.json file |
| `tag` | string | "latest" | The tag to publish to. This allows people to install the package using `npm install @`. |
| `access` | string | "public" for non-scoped packages. "restricted" for scoped packages. | Determines whether the published package should be publicly visible, or restricted to members of your NPM organization. |
| `dryRun` | boolean | false | Run NPM publish with the `--dry-run` flag to prevent publication |
| `checkVersion` | boolean | true | Only publish to NPM if the version number in `package.json` differs from the latest on NPM |
| `greaterVersionOnly` | boolean | false | Only publish to NPM if the version number in `package.json` is greater then the latest on NPM |
| `quiet` | boolean | false | Suppress console output from NPM and npm-publish |
| `debug` | function | no-op | A function to log debug messages. You can set this to a custom function to receive debug messages, or just set it to `console.debug` to print debug messages to the console. |
### Return Value
The `npmPublish()` function asynchronously returns an object with the following properties:
| Name | Type | Description |
| ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | The type of version change that occurred ("major", "minor", "patch", etc.) If there was no version change, then the the type is "none". If `greater-version-only` is set and the version is lower, then type will be "lower". |
| `package` | string | The name of the NPM package that was published |
| `version` | string | The version number that was published |
| `oldVersion` | string | The version number that was previously published to NPM |
| `tag` | string | The tag that the package was published to. |
| `access` | string | Indicates whether the published package is publicly visible or restricted to members of your NPM organization. |
| `dryRun` | boolean | Indicates whether NPM was run in "dry run" mode |
## Command Line Interface
To use npm-package from as a command-line tool in your terminal, you'll need to install it globally using [NPM](https://docs.npmjs.com/about-npm/):
```bash
npm install -g @jsdevtools/npm-publish
```
You can then use it in your terminal or in Bash scripts. You can call it without any arguments, and it will publish the current directory using NPM's default credentials.
```bash
npm-publish
```
Or you can call it with arguments to explicitly set the NPM auth token, registry, package path, etc.
```bash
npm-publish --token=YOUR_NPM_AUTH_TOKEN_HERE ./path/to/package.json
```
### Options
Run `npm-publish --help` to see the full list of options available.
```
> npm-publish --help
Usage: npm-publish [options] [package_path]
options:
--token The NPM access token to use when publishing
--registry The NPM registry URL to use
--tag The tag to publish to. Allows the package to be installed
using "npm install @"
--access "public" = The package will be publicly visible.
"restricted" = The package will only be visible to members
of your NPM organization.
--dry-run Don't actually publish to NPM, but report what would have
been published
--debug, -d Enable debug mode, with increased logging
--quiet, -q Suppress unnecessary output
--version, -v Print the version number
--help, -h Show help
package_path The absolute or relative path of the NPM package to publish.
Can be a directory path, or the path of a package.json file.
Defaults to the current directory.
```
## Contributing
Contributions, enhancements, and bug-fixes are welcome! [Open an issue](https://github.com/JS-DevTools/npm-publish/issues) on GitHub and [submit a pull request](https://github.com/JS-DevTools/npm-publish/pulls).
#### Building
To build the project locally on your computer:
1. **Clone this repo**
`git clone https://github.com/bluecargo/npm-publish.git`
2. **Install dependencies**
`npm install`
3. **Build the code**
`npm run build`
4. **Run the tests**
`npm test`
## License
npm-publish is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.
This 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.
## Big Thanks To
Thanks to these awesome companies for their support of Open Source developers ❤
[](https://github.com/open-source)
[](https://www.npmjs.com/)
[](https://coveralls.io)
[](https://travis-ci.com)
[](https://saucelabs.com)
---
_Source: https://npm.io/package/@bluecargo/npm-publish · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._