Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท Publishing

Versioning and the Release Workflow

Learn semantic versioning for package authors, the npm version command, pre-release tags, lifecycle scripts like prepublishOnly, and a safe release checklist.

Once strangers depend on your package, your version number becomes a promise. It tells them whether upgrading is safe. This lesson covers semantic versioning from the author's side, the commands that bump versions, the lifecycle scripts that run around a release, and a checklist that keeps releases boring.

The commands shown in plain code blocks are read-only here (the site cannot run npm). The runnable examples model the same logic in plain Node.js.

Semantic versioning for authors

A version has three numbers: MAJOR.MINOR.PATCH.

Change Bump Example
Bug fix, nothing else changes PATCH 1.4.2 to 1.4.3
New feature, old code still works MINOR 1.4.3 to 1.5.0
Breaking change MAJOR 1.5.0 to 2.0.0

What counts as "breaking" is anything a consumer could have relied on: removing an export, renaming an option, changing a return type, dropping a supported Node version, changing a default. When in doubt, think about the person with ^1.5.0 in their manifest. Their install will take any 1.x release automatically, so a surprise in 1.6.0 lands in their production build.

Versions below 1.0.0 mean "anything may change". Many tools treat ^0.3.1 as "only patch updates", because in the 0.x range the minor number acts like a major.

Three numbers, one promise

PATCH Fixes only
MINOR New, compatible
MAJOR Breaking

Consumers with a caret range accept MINOR and PATCH automatically.

1 / 2

Pre-releases and build metadata

A hyphen starts a pre-release such as 2.0.0-beta.1. Pre-releases sort before the final release (2.0.0-beta.1 < 2.0.0) and are skipped by ranges like ^1.0.0 unless the range itself names a pre-release on that same version. A plus sign adds build metadata (1.0.0+20260101), which is ignored when comparing versions.

Publish pre-releases under their own dist-tag so that latest stays stable (more in scopes and registries).

Bumping the version

Terminal
npm version patch        # 1.4.2 -> 1.4.3, commits and tags v1.4.3
npm version minor        # 1.4.3 -> 1.5.0
npm version major        # 1.5.0 -> 2.0.0
npm version prerelease --preid=beta   # 2.0.0 -> 2.0.1-beta.0
npm version 3.0.0-rc.1   # an exact version

In a git repository npm version edits package.json (and the lockfile), creates a commit named after the version and a tag v1.5.0. Add --no-git-tag-version when you only want the file changed. Yarn and pnpm have equivalents: yarn version (Yarn Berry uses yarn version patch or deferred versioning with yarn version check), and pnpm version simply delegates to npm. Many teams skip these commands and let a release tool such as Changesets or release-please do the bump (see the monorepo release project).

You can reproduce the arithmetic yourself:

Node.js A tiny semver bumper and comparator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Lifecycle scripts around a release

The package manager runs certain scripts automatically. These are the ones that matter when releasing:

Script Runs
prepare After a local install and before pack/publish (a good place to build, and for git hooks)
prepack Before the tarball is created
prepublishOnly Only before npm publish, not on install
postpublish After a successful publish
preversion, version, postversion Around npm version (run tests, build the changelog, push tags)
JSON
{
  "scripts": {
    "build": "tsc -p tsconfig.build.json",
    "test": "node --test",
    "prepublishOnly": "npm run build && npm test",
    "postversion": "git push --follow-tags"
  }
}

A caution: prepublish (without Only) is deprecated because it also ran on a plain install. Do not use it. Yarn and pnpm run the same names; pnpm additionally supports pnpm publish --no-git-checks for unusual flows.

A release checklist

  1. Working tree clean and on the release branch.
  2. npm ci (clean install from the lockfile) so you test what CI will test.
  3. Tests, lint and type-check pass.
  4. Build, then npm pack --dry-run and read the list.
  5. Update the changelog; bump the version; tag it.
  6. Publish, with two-factor authentication or a trusted CI identity.
  7. Verify by installing the published version into an empty folder.

The checklist is easy to forget, so encode it. This second example turns the list into a tiny runner where every step is a function, and a failed step stops the release.

Node.js Stand-in: a release runner that stops on the first failure

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Never reuse a version number. The registry refuses a second publish of the same version, and an npm unpublish does not let you reuse the number either. If you shipped something broken, publish a new patch and mark the bad one with npm deprecate.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You renamed an exported function and kept no alias. Which bump is right?

    Removing or renaming public API breaks consumers who rely on it, so it needs a major version.
  2. 2. Which script runs only on npm publish and not on a normal install?

    prepublishOnly runs only before publishing. The old prepublish also ran on install and is deprecated.
  3. 3. How does 2.0.0-beta.3 compare with 2.0.0?

    A pre-release has lower precedence than the release with the same major, minor and patch.
  4. 4. What does npm version minor do in a git repository by default?

    It bumps package.json (and the lockfile), makes a version commit and tags it. It does not publish.

Summary

  • MAJOR for breaking changes, MINOR for compatible features, PATCH for fixes.
  • Pre-releases sort below their release; publish them under their own dist-tag.
  • npm version bumps, commits and tags; release tools can automate it.
  • Use prepublishOnly to build and test before every publish.
  • Follow a checklist, and never reuse or rewrite a published version.

Next: npm pack and publish