Balena Semantic Versioning Utilities

Common errors

• Error: Invalid Version: v1.2.3

  cause Attempting to parse or validate a version string that includes a 'v' prefix, which is not strictly compliant with the internal Balena semver validation, especially in contexts like `balena.yml`.
  fix Ensure version strings do not contain a 'v' prefix. Use '1.2.3' instead of 'v1.2.3'.

• TypeError: Cannot read properties of undefined (reading 'major')

  cause Attempting to access properties of a `null` return value from a `balena-semver` function (e.g., `parse`, `major`) when an invalid or unparsable version string was provided.
  fix Always check for `null` or `undefined` return values when calling `balena-semver` functions that can fail parsing, such as `parse(version)` or `major(version)`. Handle cases where the input version string is not a valid semantic version or Balena-specific version.

Warnings

• gotcha This module is a low-level utility primarily designed for Balena's internal components. Direct use by end-users is discouraged, and the Balena SDK is recommended for most applications.
  Fix: Consider using the higher-level Balena SDK for application development unless you explicitly require these specific, low-level semver utilities.
• breaking The package's `engines` field specifies Node.js `^20.12.0 || >= 22.0.0`. Using older Node.js versions is unsupported and may lead to unexpected behavior or runtime errors.
  Fix: Ensure your project uses Node.js version 20.12.0 or higher, or Node.js 22.0.0 or higher, to maintain compatibility and stability.
• gotcha When submitting versions in Balena Cloud via `balena.yml`, including a 'v' prefix (e.g., `version: 'v1.2.3'`) can cause the Balena semver validator to fail, potentially resulting in '0.0.0' versions appearing on the dashboard.
  Fix: Remove any 'v' prefixes from version strings in `balena.yml` (e.g., use `version: '1.2.3'` instead of `version: 'v1.2.3'`).
• gotcha Semantic Versioning build metadata (e.g., the `+dev.abc123` part in `1.2.3+dev.abc123`) is not considered for uniqueness rules in Balena Cloud releases. Subsequent pushes of the exact same major.minor.patch will result in a `+revN` suffix being automatically appended by the backend to ensure uniqueness.
  Fix: Be aware that build metadata is purely informational and does not affect release uniqueness or comparison logic within the Balena ecosystem's versioning enforcement.

Install

• npm install balena-semver npm
• yarn add balena-semver yarn
• pnpm add balena-semver pnpm

Imports

• compare
  wrong:

  const compare = require('balena-semver').compare;

  correct:

  import { compare } from 'balena-semver';

  Primary way to compare two Balena-specific or standard semver strings.
• satisfies
  wrong:

  const satisfies = require('balena-semver').satisfies;

  correct:

  import { satisfies } from 'balena-semver';

  Checks if a version satisfies a given range, handling Balena-specific formats.
• major
  wrong:

  const { major } = require('balena-semver');

  correct:

  import { major } from 'balena-semver';

  Extracts the major version from a semver string, including Balena OS variants.

Quickstart

Demonstrates basic usage including comparing different version formats, satisfying ranges, and extracting version components.

import { compare, satisfies, major, prerelease, parse } from 'balena-semver';

const versionA = 'Resin OS v2.0.2+rev2';
const versionB = '2.0.5';
const versionC = '1.16.0';
const versionD = 'Resin OS 1.16.0';
const versionE = '1.2.3-beta.1';

console.log(`Comparing '${versionA}' and '${versionB}': ${compare(versionA, versionB)}`);
// Expected: 1 (versionA is greater, custom parsing applies)

console.log(`'${versionB}' satisfies '>=2.0.0 <2.1.0': ${satisfies(versionB, '>=2.0.0 <2.1.0')}`);
// Expected: true

console.log(`Major version of '${versionA}': ${major(versionA)}`);
// Expected: 2

console.log(`Prerelease of '${versionE}': ${prerelease(versionE)}`);
// Expected: ['beta', 1]

const parsedVersion = parse(versionD);
if (parsedVersion) {
  console.log(`Parsed version of '${versionD}': Major=${parsedVersion.major}, Minor=${parsedVersion.minor}, Patch=${parsedVersion.patch}`);
} else {
  console.log(`Failed to parse '${versionD}'.`);
}

// Example of sorting versions
const versions = ['2.0.0', 'Resin OS 1.16.0', '1.2.3', 'Resin OS v2.0.2+rev2', '2.0.0-beta'];
versions.sort(compare);
console.log('Sorted versions (ascending):', versions);