npm diff
Tags: npm, node, javascript, cli
Published: 2021-02-01 14:16:00

---
title: npm diff
published: true
description: The npm registry diff command
tags: npm, node, javascript, cli
cover_image: https://dev-to-uploads.s3.amazonaws.com/i/gsakxx23s4xeh0e5dyuv.png
---

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](https://github.com/npm/rfcs/pull/144) 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.

<br />
<img src="https://dev-to-uploads.s3.amazonaws.com/i/8o1f249k5lbic18huy46.png" width="90%" alt="npm diff usage example" />

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

## 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:**
```patch
$ 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](https://www.npmjs.com/package/npm-package-arg) 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:

```patch
$ 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).

```patch
$ 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](https://github.com/npm/cli/blob/latest/docs/content/commands/npm-diff.md). :blush:

## :arrow_down: 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!