119. Shipping Viscosity

Can I install it?

Somebody reads this book, likes Viscosity, and types npm install viscosity. What do they get?

A library, version 0.3.0, described as “a sass library for fluid containers that handle aspect ratios across device sizes”. The name viscosity on npm belongs to someone else. And @viscosity/cli, the name in the repo’s package.json? The registry answers 404. Viscosity isn’t published, and its own documentation says so: viscosity.dev’s install page tells you to clone the repository and run the CLI from source.

This chapter is about the last step, from “works on my machine” to “works on yours”.

What a package is

Here is the CLI’s first package.json, in engine/ts/packages/cli:

{
  "name": "@viscosity/cli",
  "version": "0.0.1",
  "description": "The viscosity command:
    build, explain and profile.",
  "author": "Tariq Shams",
  "license": "MIT",
  "type": "module",
  "bin": { "viscosity": "src/cli.ts" }
}

(The description is wrapped here to fit.) The name and version are the only fields npm requires to publish, and together they identify the package. @viscosity/ is a scope, a namespace that belongs to a user or organization, where only they can add packages^[2]. bin asks npm to install a viscosity command that runs src/cli.ts^[1].

npm pack builds the tarball that npm publish would upload, and npm pack --dry-run lists what would go in it without writing anything^[2].

Three bugs nobody could see

To find out what would happen, the author packed that CLI and installed the tarball in an empty scratch folder, the way a stranger would. Step through it:

None of the three was visible from inside the repository, because there everything works:

1. No dependencies. cli.ts imports the core with a relative path, '../../core/src/index.ts', which only exists in the repo’s folder layout. Its package.json declared no dependencies, so npm installed one package and nothing else.

2. TypeScript in node_modules. Node 22.18 and later strip TypeScript types by default, which is why the repo runs .ts files directly. But Node deliberately refuses to do it under node_modules, to discourage publishing TypeScript sources^[3].

3. The silent main check. cli.ts ended with a check, so that importing it in a test doesn’t run it:

   if (import.meta.url ===
       `file://${process.argv[1]}`)
     process.exit(main(argv.slice(2)));

   (simplified). Run through npm’s link in node_modules/.bin, argv[1] is the link’s path, not the file’s, so the check was false and the command exited with status 0 having done nothing.

The fixes were a build step and one small file, and they are in the repository now. build.mjs runs esbuild, which compiles the TypeScript and pulls the core, the front-ends and their parsers (acorn, acorn-walk, sucrase) into one file, dist/viscosity.mjs. The package has no runtime dependencies and needs only Node 18. A bundle contains other people’s code, so their MIT licence notices have to ship with it too: the build also writes LICENSE and THIRD_PARTY_LICENSES.txt, holding the full licence text of each bundled package. And a separate entry file, bin/viscosity.mjs, calls main without any check:

#!/usr/bin/env node
import { main } from
  '../dist/viscosity.mjs';
process.exit(main(process.argv.slice(2)));

The #! line matters: npm’s documentation asks that every bin file start with it, or the script isn’t run by Node^[1]. The package.json gained the rest: bin points at that file, "files" limits the tarball to the bin file, the bundle and the two licence files, engines says >=18, and a prepack script runs the build, so npm pack always packs a fresh bundle. (The check in cli.ts now compares real paths, so even running the source through a link works.) Packed again and installed in an empty folder:

$ npm pack
npm notice total files: 5
$ npm install viscosity-cli-0.0.1.tgz
$ npx viscosity --version
viscosity 0.0.1
$ npx viscosity explain p.js
ps (line 1) {x, vx} → struct of arrays
  …

Viscosity still isn’t on the registry, but everything up to npm publish has now been walked.

Version numbers that mean something

The version 0.0.1 isn’t decoration. npm works in Semantic Versioning: it requires versions that its semver library can parse^[1]. The rules fit in a sentence: given MAJOR.MINOR.PATCH, bump MAJOR for incompatible API changes, MINOR for backward compatible new features, PATCH for backward compatible bug fixes, and reset the numbers to the right of the one you bumped^[4].

Three details catch people out. The parts are compared as numbers, so 1.10.0 is newer than 1.9.0, even though as strings it sorts first:

const a = '1.10.0';
const b = '1.9.0';
// strings: character by character
console.log(a > b);

function parse(v) {
  return v.split('.').map(Number);
}
console.log(parse(a), parse(b));
// numbers compare by value
console.log(parse(a)[1] > parse(b)[1]);

Second, a released version must never change. npm enforces it: once a name and version have been published, that pair can never be used again, even after unpublishing^[2]. Third, major version zero is for initial development, and “anything MAY change at any time”^[4]. npm’s caret ranges follow that: a dependency on ^1.2.3 accepts anything below 2.0.0, but ^0.1.0 accepts only 0.1.x, because in 0.x the minor number is treated as the breaking one, and ^0.0.1 accepts no other version at all^[5]. That is why Viscosity starts at 0.0.1: no project that depends on it gets a newer release without asking for it.

What is Viscosity’s public API?

Semver starts with a demand: declare your public API, because the numbers only mean something relative to it^[4]. For a library that is its exported functions. For Viscosity it is more:

• The CLI: commands and options. viscosity.dev’s CLI reference is generated from --help, so the documentation can’t drift from it.
• The plugin API from chapter 90, if other people write plugins.
• The explain text. Chapter 110 argued that if people read the reports, they are part of the interface. Scripts will grep them.
• The decisions. A release that suddenly keeps a collection it used to transform makes someone’s program slower without changing its output.

Is that last one a breaking change? The output is identical, which the differential tests check, so by semver’s letter it is a fix or a feature. A user who measured a speed-up may disagree. Deciding, and writing the decision down, is part of shipping. (One small thing was fixed on the way: viscosity --version used to print a hard-coded version, a second copy of the number in package.json that would one day disagree with it. Now it reads package.json.)

Your turn

function bump(v, kind) {
  return v + '.1';
}

function newer(a, b) {
  return a > b;
}

What you learned

• An npm package is a tarball described by package.json, identified by name and version, with bin, files, dependencies and engines. Viscosity is not published; the name viscosity is taken.
• Packing and installing the CLI found three bugs: undeclared dependencies, TypeScript under node_modules, and a main check that failed through npm’s link. A bundle and a bin entry fixed them, and npm pack plus an install now works.
• Semantic versioning: MAJOR.MINOR.PATCH, compared numerically, immutable once released, with 0.y.z promising nothing. ^0.1.0 accepts only 0.1.x, and ^0.0.1 only 0.0.1.
• Versions are only meaningful against a declared public API, which for Viscosity includes its options, reports and decisions.