CLI tool for creating pull requests to update npm packages

• 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

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

• GitHub
• GitHub Enterprise

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

npx npm-update-package --github-token <github-token>

Alternatively, you can use a specific version as follows:

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

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

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

Example:

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

User names to assign to pull request.

Example:

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

How many members to be assigned to assignees.

Example:

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

Commit message template.

Available variables:

Example:

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

Dependency types to be updated.

Allowed values:

Example:

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

Whether to create pull request as draft.

Example:

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

Sleep time between fetching (ms).

Example:

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

Whether to fetch release notes.

Example:

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

Git user email.

Example:

npx npm-update-package \
  --github-token <github-token> \
  --git-user-email [email protected]

Git user name.

Example:

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

GitHub token.

Package names to ignore.

Example:

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

Log level to show.

Allowed values:

Example:

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

What to do when outdated pull requests exist.

Allowed values:

Example:

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

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.

Allowed values:

Example:

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

GitHub host of pull request body.

Example:

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

Additional notes for Pull request body.

Example:

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

Pull request title template.

Available variables:

Example:

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

User names to request reviews.

Example:

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

How many members to be assigned to reviewers.

Example:

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

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.

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.

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 }}

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 }}

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: [email protected]
          # TODO: Replace with your name
          GIT_USER_NAME: npm-update-package-bot
          GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

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

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

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

See Wiki.