GitHub Action
NPM Publish
Fast, easy publishing to NPM
Features
-
🧠 Smart
Only publishes if the version number inpackage.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 as part of your CI/CD process -
🧩 A function that you call in your JavaScript code -
🖥 A CLI 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. By default, the only thing you need to do is set the token
parameter to your NPM auth token.
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: JS-DevTools/npm-publish@v1
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 <package-name>@<tag> . |
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 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.
steps:
- id: publish
uses: JS-DevTools/npm-publish@v1
with:
token: ${{ secrets.NPM_TOKEN }}
- if: steps.publish.outputs.type != 'none'
run: |
echo "Version changed: ${{ steps.publish.outputs.old-version }} => ${{ steps.publish.outputs.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:
npm install @jsdevtools/npm-publish
You can then import it and use it in your code like this:
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 <package-name>@<tag> . |
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:
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.
npm-publish
Or you can call it with arguments to explicitly set the NPM auth token, registry, package path, etc.
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 <token> The NPM access token to use when publishing
--registry <url> The NPM registry URL to use
--tag <tag> The tag to publish to. Allows the package to be installed
using "npm install <package-name>@<tag>"
--access <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 on GitHub and submit a pull request.
Building
To build the project locally on your computer:
-
Clone this repo
git clone https://github.com/JS-DevTools/npm-publish.git
-
Install dependencies
npm install
-
Build the code
npm run build
-
Run the tests
npm test
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 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