Fast, easy publishing to NPM

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 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/[email protected]
      - uses: actions/[email protected]
        with:
          node-version: 10
      - run: npm install
      - run: npm test
      - uses: JS-DevTools/[email protected]
        with:
          token: ${{ secrets.NPM_TOKEN }}

Input Parameters

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

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/[email protected]
    with:
      token: ${{ secrets.NPM_TOKEN }}

  - if: steps.publish.outputs.type != 'none'
    run: |
      echo "Version changed: ${{ steps.publish.outputs.old-version }} => ${{ steps.publish.outputs.version }}"

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:

Return Value

The npmPublish() function asynchronously returns an object with the following properties:

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:

1. Clone this repo
   git clone https://github.com/JS-DevTools/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. 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 ❤