release-it-calver-plugin

Calendar Versioning (calver) plugin for Release It!

This plugin enables Calendar Versioning (calver) with Release It! This is especially useful for application projects in a continuous delivery environment.

npm install --save-dev @csmith/release-it-calver-plugin

In release-it config:

"plugins": {
  "@csmith/release-it-calver-plugin": {
    "cycle": "month"
  }
}

Configuration

| Option | Description | Default | Values | |---|---|---|---| | cycle | The calendar cycle to use | month | year, month, week, day, auto | | prefix | String to prepend to the version | "" | Any string | | separator | Separator between date segments | "." | "." or "-" |

Cycle options

year

Versions contain only the year and a minor number.

2026.0
2026.1
2027.0

month (default)

Versions contain the year, month, and a minor number.

2026.3.0
2026.3.1
2026.4.0

week

Versions contain the year, week number, and a minor number.

2026.13.0
2026.13.1
2026.14.0

day

Versions contain the year, month, day, and a minor number.

Note: 4-segment versions (e.g. 2026.3.24.0) are not valid semver and will be rejected by npm version. If you publish to npm, either use a different cycle or set "npm": { "skipChecks": true } in your release-it config.

2026.3.24.0
2026.3.24.1
2026.3.25.0

Prefix

Useful for monorepos where multiple modules need distinct version tags.

"@csmith/release-it-calver-plugin": {
    "cycle": "month",
    "prefix": "ui-"
}

Produces versions like ui-2026.3.0, ui-2026.3.1, etc.

Separator

By default, all date segments are separated by . for npm semver compatibility. Set to "-" to use dash-separated output (calver-native format). Only use this if you don't need npm compatibility.

"@csmith/release-it-calver-plugin": {
    "cycle": "month",
    "separator": "-"
}

Produces versions like 2026-3.0, 2026-3.1, etc.

Dash-separated versions are not valid semver, so you will also need to configure release-it to skip npm version checks:

"npm": {
    "skipChecks": true
}

Upgrading from pre-calver 24.x versions

This plugin now uses calver 24.x, which is a complete rewrite of the calver library. The plugin handles the transition automatically, but there are some things to be aware of.

What happens automatically

• Old config still works. The format, increment, and fallbackIncrement options are deprecated but still supported. The plugin maps them to the new cycle setting and logs a deprecation warning. You can upgrade your config at your own pace.
• Old tags are migrated. Existing tags in the old format (e.g. 24.11.0 or 2024.11.0) are automatically converted when computing the next version. No manual retagging is needed.
• Initial versions work. If your repository has no prior calver tags (or only a 0.0.0 tag), the plugin now correctly generates an initial version instead of returning 0.0.0.

What changes

• 4-digit years. Versions now always use 4-digit years. If your previous tags used 2-digit years (e.g. 24.11.0), the next version will use 4-digit years (e.g. 2026.3.0).
• Simplified config. The format and increment options are replaced by a single cycle option. See the table below for the mapping.

Config mapping

| Old config | New config | |---|---| | "format": "yy.mm.minor", "increment": "calendar" | "cycle": "month" | | "format": "yyyy.mm.minor", "increment": "calendar" | "cycle": "month" | | "format": "yyyy.minor", "increment": "calendar" | "cycle": "year" | | "format": "yyyy.ww.minor", "increment": "calendar" | "cycle": "week" | | "format": "yyyy.mm.dd.minor", "increment": "calendar" | "cycle": "day" | | "format": "yyyy.0m.minor" | "cycle": "month" | | "format": "yyyy.0m.0d.minor" | "cycle": "day" |

Example upgrade

Before:

"@csmith/release-it-calver-plugin": {
    "format": "yyyy.mm.minor",
    "increment": "calendar",
    "fallbackIncrement": "minor"
}

After:

"@csmith/release-it-calver-plugin": {
    "cycle": "month"
}

More information on calendar versioning can be found here: calver