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 <github-token>

Alternatively, you can use a specific version as follows:

npx npm-update-package@4 --github-token <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 <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 <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 <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 <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 <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 <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 <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 <github-token> \
  --fetch-release-notes false

--git-user-email

Git user email.

|Name|Value| |---|---| |type|string| |required|❌|

Example:

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

--git-user-name

Git user name.

|Name|Value| |---|---| |type|string| |required|❌|

Example:

npx npm-update-package \
  --github-token <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 <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 <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 <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 <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 <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 <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 <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 <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 <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: [email protected]
          # 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.