Using ncu (with examples)

Introduction

npm is a popular package manager for JavaScript projects. As projects grow, managing dependencies becomes increasingly important to ensure that the project is using the latest and most secure versions of its dependencies. However, manually tracking updates to dependencies can be time-consuming and error-prone. The ncu command comes to the rescue by providing a convenient way to find newer versions of package dependencies and check outdated npm packages locally or globally. In this article, we will explore different use cases of the ncu command and provide code examples for each use case.

Use Case 1: List outdated dependencies in the current directory

ncu

Motivation: Keeping track of outdated dependencies is crucial for maintaining the health of a project. By running ncu in the project directory, you can quickly identify which dependencies have newer versions available.

Explanation: Running ncu without any arguments lists all the outdated dependencies in the current directory. It reads the package.json file and compares the versions of installed packages with the latest ones available on the npm registry.

Example Output:

Checking /path/to/project/package.json
[....................]  0/14√ Checked package.json

The output shows that ncu is checking the package.json file for outdated dependencies. In this case, there are 14 dependencies that are being checked for updates.

Use Case 2: List outdated global npm packages

ncu -g

Motivation: In addition to project-specific dependencies, there might be globally installed npm packages that need to be updated. Running ncu with the -g flag allows you to inspect the outdated global npm packages.

Explanation: The -g flag instructs ncu to list the outdated global packages rather than project-specific dependencies.

Example Output:

Checking globally installed packages
[....................]  0/17√ Checked global packages

The output shows that ncu is checking the globally installed packages for updates. In this case, there are 17 global packages that are being checked.

Use Case 3: Upgrade all dependencies in the current directory

ncu -u

Motivation: After identifying the outdated dependencies, it is important to update them to their latest versions to benefit from bug fixes, new features, and security patches. Running ncu -u automates the process of upgrading the dependencies.

Explanation: The -u flag stands for “upgrade” and tells ncu to update dependency versions in the package.json file. After running this command, the package.json file will be updated with the latest compatible versions of the dependencies. However, the actual installation of the new versions is still pending.

Example Output:

Upgrading dependencies in /path/to/project/package.json
[....................]  0/14√ Upgraded dependencies

The output shows that ncu is upgrading the outdated dependencies in the package.json file. In this case, there are 14 dependencies that are being upgraded.

Use Case 4: Interactively upgrade dependencies in the current directory

ncu -i

Motivation: Sometimes, blindly upgrading dependencies based on the latest versions might introduce breaking changes or compatibility issues. Running ncu -i allows you to interactively choose which dependencies to upgrade, giving you more control over the update process.

Explanation: The -i flag enables interactive mode, where ncu prompts the user to select which dependencies to upgrade. It presents a menu that allows you to selectively upgrade dependencies, skipping those that you want to keep at their current versions.

Example Output:

Checking /path/to/project/package.json
[....................]  0/14√ Checked package.json
? Choose which dependencies to upgrade (Press <space> to select, <a> to toggle all, <i> to invert selection)

The output shows that ncu is checking the package.json file for outdated dependencies. In this case, there are 14 outdated dependencies. The user is then prompted with a menu to select which dependencies to upgrade.

Use Case 5: Display help

ncu -h

Motivation: Having access to command documentation is essential for using any command-line tool effectively. Running ncu -h provides information on how to use the ncu command and its available options.

Explanation: The -h flag stands for “help” and displays the help information for the ncu command. It provides a brief description of the command and lists all the available options and their usage.

Example Output:

ncu [options]

Options:
  -v, --version             output the version number
  -a, --adaptor             specify the version manager (substitutes system, npm, yarn)
  -p, --packageManager      specify the package manager (overrides adaptor/npmcmd)
  -r, --registry            specify third-party npm registry
  -f, --filter              filter dependencies by glob (comma-separated)
  -j, --jsonAll             output new package.json file, listing all dependencies
  -e, --errorLevel          set the error-level. 1: exits with error code 0 if no error occurred
  -u, --upgrade             overwrite dependency file with upgraded versions instead of just outputting them
  -x, --loglevel [value]    set the verbosity level. 0 = silent, 1 = error, 2 = warn, 3 = info, 4 = verbose, 5 = debug (default: 0)
  -g, --global              check global packages instead of in the current project (default: false)
  -c, --configFileName      set the config file name. defaults to .ncurc.* (default: ".ncurc.{json,yml,js}")
  -m, --minimal             Only show newer versions more recent than the version range specified in the package.json dependency for the current directory.
  -e, --error-level number  Set the error-level. 1: Exits with error code 0 if no error occurred. (default: unset)
  -r, --reject string       Reject all patches for this dependency. (Shorthand for --reject-versions *:path). repeatable. (default: "")
  --reject-versions string  Rejects versions from the range of a dependency. have this format: [^|>|>=|=|<|<=|*]?:path@range. (repeatable) (default: [])
  -f, --filter string       Filter out dependencies that don't match from the check/update/filter commands. (default: "*")
  --packageFile string      Use the specified package-file/file. (default: "package.json")
  --packageManager string   Use specified package-manager. npm, bower, yarn (default: "npm")
  --registry string         Use specified third-party npm registry (default: "unset")

i  Run this command with -h for exhaustive list of options.

The output shows the help information for the ncu command, including all the available options and their usage.

Conclusion

The ncu command provides a convenient way to find newer versions of package dependencies and check outdated npm packages. It allows you to perform various tasks ranging from listing outdated dependencies to interactively upgrading them. By incorporating ncu into your development workflow, you can ensure that your projects are always using the latest and most secure dependencies.