To read the diff between two package versions, compare the published contents of both, not just the repository. With npm, the diff command prints patches between two versions from the registry. On GitHub, the compare view shows changes between two tags. Look at install scripts, new dependencies and files you did not expect.
Two views, two questions
A repository comparison shows what the maintainers changed in source control. A registry comparison shows what actually shipped in the package you will install. They usually match. When they do not, that is worth knowing, and our post on whether a published package can differ from its source repository explains why.
Compare what shipped
The npm documentation describes npm diff as printing diff patches of files for packages published to the registry, similar to its git diff counterpart. You pass two specifiers to compare versions.
npm diff --diff=example-pkg@1.2.3 --diff=example-pkg@1.2.4
The docs also note you can compare across forks, directories or git repositories, which is useful if you maintain a patched copy.
Compare the source history
On GitHub, you can append /compare to a repository path to compare branches, tags, commits and forks. The documentation explains that the compare page uses a base as the starting point and a compare value as the endpoint, so for a release comparison pick the older tag as the base and the newer tag as the compare value.
If a tag for the new version does not exist, treat that as a flag. A release with no matching tag is harder to review and harder to audit later.
What to look at first
Do not read every line. Read in this order.
- package.json or the equivalent manifest. New or changed dependencies, new install or post install scripts, changed entry points.
- File list changes. Added or removed files, especially binaries, minified blobs or files outside the usual folders.
- The files related to the fix. Does the change match the advisory? A fix for an input validation issue should touch input handling, not networking code.
- Anything that reaches out. New URLs, new network calls, environment variable reads, file system writes.
- Size and shape. A patch release that rewrites half the package deserves a closer look.
When to escalate
Flag the pull request for a second reviewer if you see an install script that did not exist before, obfuscated or minified code where the old version had readable source, a new maintainer or publisher with no explanation, or a diff that does not match what the changelog claims. Those patterns are rare, and each deserves a pause.
For ordinary fixes, the diff review takes a few minutes and often answers the question "did this change do what it said?" without running a single test.
Make it routine
Pick a rule that scales: always diff for packages that run at install time, handle untrusted input, or sit on your authentication path. Skim the file list for everything else. Safeguard's dependency scanning and SBOMs help you see which packages those are across your repositories, and you can run a free scan at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen.
Open the dependency inventory and look at how packages and versions are listed, then pick one you would diff first.
Quick check
Does npm diff need the repository?
No. It compares the published package contents from the registry, so it works even when the source repository is missing or private.
What if the diff is too large to review?
Review the manifest and file list, then the files named in the advisory. If the scope is still unclear, hold the upgrade and ask the maintainers or choose a smaller step.
Sources
Last reviewed: 19 October 2026.
