npm-update-package

CLI tool for creating pull requests to update npm packages

Table of Contents

• Requirements
• Supported platforms
• Usage
• Options
  • --additional-labels
  • --assignees
  • --assignees-sample-size
  • --commit-message
  • --dependency-types
  • --draft-pr
  • --fetch-interval
  • --fetch-release-notes
  • --git-user-email
  • --git-user-name
  • --github-token
  • --ignore-packages
  • --log-level
  • --outdated-pr-strategy
  • --package-manager
  • --pr-body-github-host
  • --pr-body-notes
  • --pr-title
  • --reviewers
  • --reviewers-sample-size
• GitHub token
• How to run on GitHub Actions
  • Use token of GitHub Actions
  • Use token of GitHub App
  • Use Personal access token
• Architecture
• FAQ
  • What is the purpose of npm-update-package?
  • What should I do if conflicts occurred in the pull request?
• How to development

Requirements

• Node.js v20 or later
• npm or Yarn
• Git

Supported platforms

• GitHub
• GitHub Enterprise

Usage

The simplest use of npm-update-package is just run the following command:

npx npm-update-package --github-token 

Alternatively, you can use a specific version as follows:

npx npm-update-package@4 --github-token 

Options

You can customize behavior via CLI options.
Some options can embed variables like {{packageName}}(HTML-escaped) or {{{packageName}}}(not HTML-escaped).

--additional-labels

Labels other than npm-update-package to add to pull request.

Name	Value
type	string[]
required	❌

Example:

npx npm-update-package \
  --github-token  \
  --additional-labels bot dependencies

--assignees

User names to assign to pull request.

Name	Value
type	string[]
required	❌

Example:

npx npm-update-package \
  --github-token  \
  --assignees alice bob

--assignees-sample-size

How many members to be assigned to assignees.

Name	Value
type	number
required	❌

Example:

npx npm-update-package \
  --github-token  \
  --assignees alice bob \
  --assignees-sample-size 1

--commit-message

Commit message template.

Name	Value
type	string
required	❌
default	chore(deps): {{{level}}} update {{{packageName}}} to v{{{newVersion}}}

Available variables:

Variable	Description
currentVersion	Current package version
newVersion	New package version
packageName	Package name
level	Semver level (major/minor/patch)
dependencyType	Dependency type (dependencies/devDependencies/peerDependencies/bundledDependencies/optionalDependencies)

Example:

npx npm-update-package \
  --github-token  \
  --commit-message "chore({{{dependencyType}}}): {{{level}}} update {{{packageName}}} from {{{currentVersion}}} to v{{{newVersion}}}"

--dependency-types

Dependency types to be updated.

Name	Value
type	string[]
required	❌
default	dependencies, devDependencies, peerDependencies, bundledDependencies, optionalDependencies

Allowed values:

Value	Description
dependencies	dependencies
devDependencies	devDependencies
peerDependencies	peerDependencies
bundledDependencies	bundledDependencies
optionalDependencies	optionalDependencies

Example:

npx npm-update-package \
  --github-token  \
  --dependency-types dependencies devDependencies

--draft-pr

Whether to create pull request as draft.

Name	Value
type	boolean
required	❌
default	false

Example:

npx npm-update-package \
  --github-token  \
  --draft-pr true

--fetch-interval

Sleep time between fetching (ms).

Name	Value
type	number
required	❌
default	1000

Example:

npx npm-update-package \
  --github-token  \
  --fetch-interval 2000

--fetch-release-notes

Whether to fetch release notes.

Name	Value
type	boolean
required	❌
default	true

Example:

npx npm-update-package \
  --github-token  \
  --fetch-release-notes false

--git-user-email

Git user email.

Name	Value
type	string
required	❌

Example:

npx npm-update-package \
  --github-token  \
  --git-user-email alice@example.com

--git-user-name

Git user name.

Name	Value
type	string
required	❌

Example:

npx npm-update-package \
  --github-token  \
  --git-user-name alice

--github-token

GitHub token.

Name	Value
type	string
required	✅

--ignore-packages

Package names to ignore.

Name	Value
type	string[]
required	❌

Example:

npx npm-update-package \
  --github-token  \
  --ignore-packages @types/jest jest

--log-level

Log level to show.

Name	Value
type	string
required	❌
default	info

Allowed values:

Value	Description
off	Do not output any logs.
fatal	Output fatal logs.
error	Output fatal/error logs.
warn	Output fatal/error/warn logs.
info	Output fatal/error/warn/info logs.
debug	Output fatal/error/warn/info/debug logs.
trace	Output fatal/error/warn/info/debug/trace logs.

Example:

npx npm-update-package \
  --github-token  \
  --log-level debug

--outdated-pr-strategy

What to do when outdated pull requests exist.

Name	Value
type	string
required	❌
default	recreate

Allowed values:

Value	Description
create	Create new pull request.
recreate	Close outdated pull requests and create new pull request.
skip	Skip creating pull request.

Example:

npx npm-update-package \
  --github-token  \
  --outdated-pr-strategy create

--package-manager

Package manager of your project.
Since npm-update-package automatically determines which package manager to use, it is usually not necessary to use this option.

Name	Value
type	string
required	❌

Allowed values:

Value	Description
npm	Use npm
yarn	Use Yarn

Example:

npx npm-update-package \
  --github-token  \
  --package-manager yarn

--pr-body-github-host

GitHub host of pull request body.

Name	Value
type	string
required	❌
default	togithub.com

Example:

npx npm-update-package \
  --github-token  \
  --pr-body-github-host "github.example"

--pr-body-notes

Additional notes for Pull request body.

Name	Value
type	string
required	❌

Example:

npx npm-update-package \
  --github-token  \
  --pr-body-notes "**:warning: Please see diff and release notes before merging.**"

--pr-title

Pull request title template.

Name	Value
type	string
required	❌
default	chore(deps): {{{level}}} update {{{packageName}}} to v{{{newVersion}}}

Available variables:

Variable	Description
currentVersion	Current package version
newVersion	New package version
packageName	Package name
level	Semver level (major/minor/patch)
dependencyType	Dependency type (dependencies/devDependencies/peerDependencies/bundledDependencies/optionalDependencies)

Example:

npx npm-update-package \
  --github-token  \
  --pr-title "chore({{{dependencyType}}}): {{{level}}} update {{{packageName}}} from {{{currentVersion}}} to v{{{newVersion}}}"

--reviewers

User names to request reviews.

Name	Value
type	string[]
required	❌

Example:

npx npm-update-package \
  --github-token  \
  --reviewers alice bob

--reviewers-sample-size

How many members to be assigned to reviewers.

Name	Value
type	number
required	❌

Example:

npx npm-update-package \
  --github-token  \
  --reviewers alice bob \
  --reviewers-sample-size 1

GitHub token

GitHub token is required to run npm-update-package.
Available tokens and permissions required for each token are as follows.

• GitHub Actions
• GitHub App (recommended)
  • Contents: Read & write
  • Metadata: Read-only
  • Pull requests: Read & write
• Personal access token
  • repo

Features of each token are as follows.

	GitHub Actions	GitHub App	Personal access token
Owner of token	GitHub	organization or user	user
Author of pull requests	github-actions	app	user
Trigger other actions	-	✓	✓

We recommend using GitHub App for the following reasons.

• When you use the token of GitHub Actions, the job will not trigger other actions.
• Personal access token relies on personal account.
• When you use the Personal access token, the author of pull requests will be the user who issued the token.

How to run on GitHub Actions

Use token of GitHub Actions

name: npm-update-package
on:
  schedule:
    - cron: '0 0 * * *'
jobs:
  npm-update-package:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
      - run: |
          npx npm-update-package \
            --github-token $GITHUB_TOKEN \
            --git-user-name $GIT_USER_NAME \
            --git-user-email $GIT_USER_EMAIL
        env:
          GIT_USER_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
          GIT_USER_NAME: github-actions[bot]
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Use token of GitHub App

name: npm-update-package
on:
  schedule:
    - cron: '0 0 * * *'
jobs:
  npm-update-package:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
      - name: Generate token
        id: generate_token
        uses: tibdex/github-app-token@v1
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.PRIVATE_KEY }}
      - run: |
          npx npm-update-package \
            --github-token $GITHUB_TOKEN \
            --git-user-name $GIT_USER_NAME \
            --git-user-email $GIT_USER_EMAIL
        env:
          # TODO: Replace with your GitHub App's email
          GIT_USER_EMAIL: 97396142+npm-update-package[bot]@users.noreply.github.com
          # TODO: Replace with your GitHub App's user name
          GIT_USER_NAME: npm-update-package[bot]
          GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}

Use Personal access token

name: npm-update-package
on:
  schedule:
    - cron: '0 0 * * *'
jobs:
  npm-update-package:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
      - run: |
          npx npm-update-package \
            --github-token $GITHUB_TOKEN \
            --git-user-name $GIT_USER_NAME \
            --git-user-email $GIT_USER_EMAIL
        env:
          # TODO: Replace with your email
          GIT_USER_EMAIL: 97961304+npm-update-package-bot@users.noreply.github.com
          # TODO: Replace with your name
          GIT_USER_NAME: npm-update-package-bot
          GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

Architecture

The following shows the process flow of npm-update-package.

FAQ

What is the purpose of npm-update-package?

npm-update-package can be used in environments where Renovate cannot be used for some reason.

What should I do if conflicts occurred in the pull request?

If you have difficulty resolving it manually, close the pull request and run npm-update-package again.

How to development

See Wiki.