Introducing Publish-Diff

October 19, 2016

Safer, more predictable npm publishing with publish-diff

Publishing JavaScript projects to the 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 .npmignore file, .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 np 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.

Until now. publish-diff is a simple tool that produces a prepublication text diff of what is about to be published with what is currently published in the npm registry.

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.

Getting started

Installing 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 rowdy@0.4.0 -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

$ publish-diff

checks the local project against the latest npm registry package to produce a diff analogous to what will happen when a developer finally types npm publish.

Under the hood, publish-diff relies on the quite flexible npm pack command, which opens up a lot of possibilities for diffing versions of local and/or remote packages via:

  • local file (/PATH/TO/my-project)
  • npm registry tag (my-project@beta) / version (my-project@1.2.3)
  • git tag (GitHubOrg/my-project#v1.2.3) / hash (GitHubOrg/my-project#fe25a22)

In this manner, we can easily audit previous publications to the npm registry or git tagged source. For example, let’s see the diff for the v0.4.0 vs. v0.5.0 release of rowdy (a functional test wrapper):

$ publish-diff -o rowdy@0.4.0 -n rowdy@0.5.0

which gives us:

rowdy diff

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 https://github.com/FormidableLabs/publish-diff and we welcome any comments, issues, and feature requests.

Happy diffing!

Related Posts

Rust vs Go: Which Is Right For My Team?

August 29, 2024
In recent years, the shift away from dynamic, high-level programming languages back towards statically typed languages with low-level operating system access has been gaining momentum as engineers seek to more effectively solve problems with scaling and reliability. Demands on our infrastructure and devices are increasing every day and downtime seems to lurk around every corner.

A Rare Interview With A Designer who Designs Command-line Interfaces

May 13, 2024
For years, terminal and command-line applications have followed a familiar pattern: developers identify a need, code a solution, and release it for free, often as open-source software.

The Evolution of urql

December 6, 2022
As Formidable and urql evolve, urql has grown to be a project that is driven more by the urql community, including Phil and Jovi, than by Formidable itself. Because of this, and our commitment to the ethos of OSS, we are using this opportunity to kick off what we’re calling Formidable OSS Partnerships.