19 October 2016
Safer, more predictable
npm publishing with
npm registry is an exercise that, while commonplace, is often opaque to developers and fraught with peril.
The opacity comes from projects frequently publishing built files that are omitted from
git source and the some subtle but important differences between
git source and a final
npm registry package. (For instance, if a project has a
.gitignore file, but no
.gitignore will be renamed to
.npmignore on publication.) Moreover, developers can accidentally change files in a locally checked out repository that are successfully published to
npm in the incorrect mutated state.
Tools like the wonderful can help give some assurances by checking various pre-publication pitfalls. But, even then, some errors that cannot be easily discovered beforehand can still slip by into publication.
Developers are already very familiar with running a
git diff before committing changes to a
git source repository. It is thus a natural extension to the land of
npm publication to check a diff between the last publication and the proposed new one before taking any permanent action.
publish-diff is as simple as:
$ npm install -g publish-diff
The help (
-h) gives us a basic rundown of usage options and examples:
Usage: publish-diff [options] Preview npm publish changes. Options: -h, --help output usage information -V, --version output the version number -o, --old <package> Old package to diff (default `<package>@latest`) -n, --new <package> New package to diff (default `process.cwd()`) --no-colors Disable colors in the outputted diff Examples: # Compare (old) npm registry `latest` version vs. (new) local `process.cwd()` $ publish-diff # Compare (old) npm version vs. (new) latest npm version $ publish-diff -o email@example.com -n rowdy@latest # Compare (old) git tag/hash vs. (new) git tag/hash $ publish-diff -o FormidableLabs/rowdy#v0.4.0 -n FormidableLabs/rowdy#v0.5.0
Let’s diff some releases
The most common expected use case is a local source repository checkout that is ready for publication to the
npm registry. Running
checks the local project against the latest
npm registry package to produce a diff analogous to what will happen when a developer finally types
- local file (
npmregistry tag (
my-project@beta) / version (
GitHubOrg/my-project#v1.2.3) / hash (
$ publish-diff -o firstname.lastname@example.org -n email@example.com
which gives us:
From here, there are lots of other comparison options:
# Diff git tag/hash vs. latest on npm registry $ publish-diff -o FormidableLabs/rowdy#v0.4.0 -n rowdy $ publish-diff -o FormidableLabs/rowdy#504735c -n rowdy@latest $ publish-diff -o FormidableLabs/rowdy#v0.4.0 -n rowdy@latest # Diff two old versions from git tag/hash $ publish-diff -o FormidableLabs/rowdy#v0.4.0 -n FormidableLabs/rowdy#v0.5.0 $ publish-diff -o FormidableLabs/rowdy#504735c -n FormidableLabs/rowdy#fe25a22
The ability to diff past published versions is not only useful for package maintainers, but for consuming projects as well. For example, when deciding whether or not to upgrade a given library dependency to a specific version, a developer can now get a very accurate picture of how the code in that dependency will change upon upgrade.
Publish with confidence
With this brief tour under our belt,
publish-diff offers a simple means to diff your packages right before publication to ensure everything is correct. The project is available at and we welcome any comments, issues, and feature requests.