{"id":10557,"library":"balena-semver","title":"Balena Semantic Versioning Utilities","description":"balena-semver, currently at version 4.0.18, provides a collection of Balena-specific utility methods for working with semantic versions. While it parses and adheres to standard semver strings, its key differentiator is its ability to handle Balena OS version formats, such as 'Resin OS vX.Y.Z'. The package maintains a frequent release cadence, primarily issuing patch updates as seen with numerous recent v4.0.x releases. This module is explicitly noted as a low-level utility intended for internal Balena components and is generally not recommended for direct use by end-users; instead, the Balena SDK is suggested for most applications. It ships with TypeScript types, facilitating its use in modern JavaScript and TypeScript projects. The package requires Node.js versions `^20.12.0 || >= 22.0.0`.","status":"active","version":"4.0.18","language":"javascript","source_language":"en","source_url":"https://github.com/balena-io-modules/balena-semver","tags":["javascript","balena","balena.io","resin","resin.io","semver","typescript"],"install":[{"cmd":"npm install balena-semver","lang":"bash","label":"npm"},{"cmd":"yarn add balena-semver","lang":"bash","label":"yarn"},{"cmd":"pnpm add balena-semver","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary way to compare two Balena-specific or standard semver strings.","wrong":"const compare = require('balena-semver').compare;","symbol":"compare","correct":"import { compare } from 'balena-semver';"},{"note":"Checks if a version satisfies a given range, handling Balena-specific formats.","wrong":"const satisfies = require('balena-semver').satisfies;","symbol":"satisfies","correct":"import { satisfies } from 'balena-semver';"},{"note":"Extracts the major version from a semver string, including Balena OS variants.","wrong":"const { major } = require('balena-semver');","symbol":"major","correct":"import { major } from 'balena-semver';"}],"quickstart":{"code":"import { compare, satisfies, major, prerelease, parse } from 'balena-semver';\n\nconst versionA = 'Resin OS v2.0.2+rev2';\nconst versionB = '2.0.5';\nconst versionC = '1.16.0';\nconst versionD = 'Resin OS 1.16.0';\nconst versionE = '1.2.3-beta.1';\n\nconsole.log(`Comparing '${versionA}' and '${versionB}': ${compare(versionA, versionB)}`);\n// Expected: 1 (versionA is greater, custom parsing applies)\n\nconsole.log(`'${versionB}' satisfies '>=2.0.0 <2.1.0': ${satisfies(versionB, '>=2.0.0 <2.1.0')}`);\n// Expected: true\n\nconsole.log(`Major version of '${versionA}': ${major(versionA)}`);\n// Expected: 2\n\nconsole.log(`Prerelease of '${versionE}': ${prerelease(versionE)}`);\n// Expected: ['beta', 1]\n\nconst parsedVersion = parse(versionD);\nif (parsedVersion) {\n  console.log(`Parsed version of '${versionD}': Major=${parsedVersion.major}, Minor=${parsedVersion.minor}, Patch=${parsedVersion.patch}`);\n} else {\n  console.log(`Failed to parse '${versionD}'.`);\n}\n\n// Example of sorting versions\nconst versions = ['2.0.0', 'Resin OS 1.16.0', '1.2.3', 'Resin OS v2.0.2+rev2', '2.0.0-beta'];\nversions.sort(compare);\nconsole.log('Sorted versions (ascending):', versions);","lang":"typescript","description":"Demonstrates basic usage including comparing different version formats, satisfying ranges, and extracting version components."},"warnings":[{"fix":"Consider using the higher-level Balena SDK for application development unless you explicitly require these specific, low-level semver utilities.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Remove any 'v' prefixes from version strings in `balena.yml` (e.g., use `version: '1.2.3'` instead of `version: 'v1.2.3'`).","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure version strings do not contain a 'v' prefix. Use '1.2.3' instead of '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`.","error":"Error: Invalid Version: v1.2.3"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'major')"}],"ecosystem":"npm"}