The npm cli just added a new npm diff command that show changes between registry-published tarballs, similar to git diff but tracking versions of packages in the registry instead of commits.

Introducing npm diff

The idea for a npm diff command has been around since last year when I first wrote a npm diff RFC that got rather positive feedback from the community.

Providing more transparency to changes to packages installed in a given project was the main motivation but being a package author myself, I quickly saw a chance to improve package maintainers' lives by also having workflows to compare the contents of the package you're currently working on.

Following up are some examples of how to use npm diff in both the package consumer and package author scenarios.

Diffing packages from the registry

You can point to any two different published package versions and get git-like patch output that shows the difference between file contents in them.

Example:

$ npm diff --diff=ntl@5.0.0 --diff=ntl@5.1.0
diff --git a/README.md b/README.md
index v5.0.0..v5.1.0 100644
--  a/README.md
+++ b/README.md
@@ -36,6 +36,7 @@
     + [UI Size](#ui-size)
   * [Repeat the last ran task](#arrows_counterclockwise-repeat-the-last-ran-task)
   * [Run multiple tasks](#m-run-multiple-tasks)
+    + [Preserve selection order](#run-multiple-tasks-in-order-of-selection)
   * [Run in autocomplete or fuzzy search mode](#fast_forward-run-in-autocomplete-or-fuzzy-search-mode)
   * [Tips](#white_check_mark-tips)
     + [ntl as default task](#ntl-as-default-task)
@@ -85,7 +86,9 @@
 - Multiple interactive interfaces (menu list, autocomplete fuzzy search)
 - Many options to customize the UI (exclude scripts, amount of items, etc)
 - Easy to repeat last ran script (`nt` and `rerun` options)
-- Run multiple tasks (can also easily repeat multiple ran tasks)
+- Run multiple tasks
+  - Repeat previously set of ran tasks
+  - Preserve order of selection
 - Customize rerun cache options

Keep in mind the --diff arguments accepts any valid npm install arguments meaning that you can also target local folders or git repositories on top of using semver ranges and registry tags.

Diffing packages you're updating

Using a single argument is a handy shortcut to diff the contents of a local installed package to the contents you'd get with the version specified by the --diff option.

It also provides a shortcut that replicates the logic of the wanted version returned by npm outdated when using only the package name and omitting any version/tags. Example:

$ npm diff --diff=abbrev
diff --git a/package.json b/package.json
index v1.1.0..v1.1.1 100644
--  a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "abbrev",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Like ruby's abbrev module, but in js",
   "author": "Isaac Z. Schlueter <i@izs.me>",
   "main": "abbrev.js",

Diffing local changes to a package

This is the workflow package authors will find the most helpful. When working on a package that is published to the registry, you can get a diff output between the contents from you local file system comparing it to the latest published version by just running npm diff (no arguments).

$ npm diff
diff --git a/package.json b/package.json
index v3.1.1..v3.2.0-beta.1 100644
--  a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ipt",
-  "version": "3.1.1",
+  "version": "3.2.0-beta.1",
   "description": "iPipeTo - The Node.js cli interactive workflow",
   "repository": "ruyadorno/ipt",
   "author": {

Filter by file names

In some cases the full diff patch output might be too verbose and you're only interested in a single file or folder, in that case you can provide these path names as positional arguments and they will be treated as filters limiting the output to only contents of the files defined in these patterns (similar to how git diff works).

e.g: use npm diff package.json to only print diffs in the package.json file, npm diff lib/ to limit diff output to files inside a lib folder.

More options

A few more options from git diff are implemented, such as a --diff-name-only flag to only print the file names of changed files, or --diff-ignore-all-space very useful to ignore padding spaces/tabs and print shorter diff outputs.

If you want to learn more about the different options, make sure to read the npm diff docs. 😊

⬇️ Get it now

npm diff was introduced in npm@7.5.0, to make sure you have the latest v7 version install it now with:

$ npm install -g npm@7

- Happy diffing everyone!