A date-based npm package versioning scheme

Npm recommends semantic versioning for npm packages. However, sometimes we would prefer integrating dates into the versioning scheme, due to the nature of the package or whatever reasons. How can we integrate date into a semantic versioning scheme? Here’s what I found helpful.

Semantic Versioning

Semantic versioning has 3 component:


Where bumping PATCH indicates a bug fix release, bumping MINOR indicates a release with new feature but no breaking changes, while bumping MAJOR indicates a breaking change.

Associate MINOR with Date

For most projects, it’s likely a good idea to associate MINOR with date, if a date-based versioning is desired. Bump MAJOR only when a breaking change takes place, and bump PATCH for quick bug-fix releases.

For example, cpi-us is such a package. Each month it adds new CPI data, which is considered a new feature. Its MINOR follows the YYYYMM (e.g., 202405) format, while bumping MAJOR indicates breaking changes and bumping PATCH indicates bug-fix releases in between.

Additional Notes

While this versioning method complies with the core principles of semantic versioning, it doesn’t fully comply. The semver specification requires:

Patch version MUST be reset to 0 when minor version is incremented.


Patch and minor versions MUST be reset to 0 when major version is incremented.