[Replacement]: semver

[sxzz]

Package to replace

semver

Suggested replacement(s)

verkit

Manifest type

preferred (lighter or more modern alternative package)

Rationale

verkit is a modern SemVer toolkit designed for ESM and TypeScript projects. It follows node-semver semantics while providing:

• Complete SemVer version and range support
• Faster performance across the operations covered by its benchmarks
• Pure ESM with zero runtime dependencies
• First-class TypeScript declarations, without requiring @types/semver
• Functional, tree-shakeable named exports
• Smaller bundles:
  • 26.0% smaller for full-package imports
  • 60.1% smaller for common tree-shaken imports
• Immutable collection operations

The README includes a detailed migration guide from node-semver, including mappings for renamed or reshaped APIs.

verkit is already being adopted by several projects, including Nuxt, tsdown, bumpp, npmx, and Nuxt DevTools. The migration progress is tracked in e18e/ecosystem-issues#277.

This is not a completely drop-in replacement: verkit is ESM-only and does not provide node-semver's CommonJS entry point, CLI, or NODE_DEBUG=semver output. It is therefore best suited to modern ESM projects whose node-semver usage is covered by verkit.

Availability

Not applicable; this is a package replacement rather than a native API.

Code example (optional)

// Before
import semver from 'semver'

semver.valid('1.2.3')
semver.inc('1.2.3', 'minor')
semver.maxSatisfying(['1.2.3', '1.5.0', '2.0.0'], '^1.0.0')

// After
import {
  findMaxSatisfying,
  increment,
  normalize,
} from 'verkit'

normalize('1.2.3')
increment('1.2.3', 'minor')
findMaxSatisfying(['1.2.3', '1.5.0', '2.0.0'], '^1.0.0')

[zloirock]

I'm not a fan of semver package after a day when they broke semver in their own package, but here you are forced to load the full package even if you need one simple helper when in semver you can load only required.

[sxzz]

Even when loaded in its entirety, verkit starts up remarkably quickly.

semver’s sleight of hand is that, while it may appear to load only one or two functions, it actually pulls in many additional files. Reading those files from disk incurs extra overhead, making a partial semver import slower than loading all of verkit.

Simple benchmark:

semver

console.time('loading semver.parse')
const parse = require('semver/functions/parse.js')
const eq = require('semver/functions/eq.js')
console.timeEnd('loading semver.parse')
console.log(
  'Loading files',
  Object.keys(require.cache).map((k) => k.replace(__dirname, '')),
)

loading semver.parse: 3.273ms
Loading files [
  '/main.cjs',
  '/node_modules/.pnpm/semver@7.8.5/node_modules/semver/functions/parse.js',
  '/node_modules/.pnpm/semver@7.8.5/node_modules/semver/classes/semver.js',
  '/node_modules/.pnpm/semver@7.8.5/node_modules/semver/internal/debug.js',
  '/node_modules/.pnpm/semver@7.8.5/node_modules/semver/internal/constants.js',
  '/node_modules/.pnpm/semver@7.8.5/node_modules/semver/internal/re.js',
  '/node_modules/.pnpm/semver@7.8.5/node_modules/semver/internal/parse-options.js',
  '/node_modules/.pnpm/semver@7.8.5/node_modules/semver/internal/identifiers.js',
  '/node_modules/.pnpm/semver@7.8.5/node_modules/semver/functions/eq.js',
  '/node_modules/.pnpm/semver@7.8.5/node_modules/semver/functions/compare.js'
]

verkit

console.time('loading verkit')
const { parse, eq } = require('verkit')
console.timeEnd('loading verkit')
console.log(
  'Loading files',
  Object.keys(require.cache).map((k) => k.replace(__dirname, '')),
)

loading verkit: 2.06ms
Loading files [
  '/main.cjs',
  '/node_modules/.pnpm/verkit@0.2.0/node_modules/verkit/dist/index.js'
]

[43081j]

i'm generally agreed with this move but i'd like to see some more usage in the wild first.

it gained adoption very quickly thanks to your effort @sxzz , but that is different to natural adoption over time. i'd prefer to revisit in a couple of weeks at least when it has been running in prod a while.