Configuration Options and Modes
Relevant source files
The following files were used as context for generating this wiki page:
The node-semver library employs a flexible configuration system to control how semantic versions and ranges are parsed, validated, and compared. These options allow developers to balance strict adherence to the SemVer 2.0.0 specification with the practical need to handle "real-world" versioning strings that may deviate from the standard.
Configuration is primarily handled through an options object passed to classes like SemVer, Range, and Comparator, or to functional utilities such as valid(), satisfies(), and coerce(). The primary modes of operation include Loose Mode, Strict Mode, and specific behavioral flags like Prerelease Inclusion.
Sources: README.md:270-281, classes/semver.js:10-25
Primary Configuration Options
Configuration options are passed as the final argument to most library functions. If a boolean is provided instead of an object, it is interpreted as the loose parameter for backward compatibility.
| Option | Type | Default | Description |
|---|---|---|---|
loose | Boolean | false | Enables more permissive parsing of version strings. |
strict | Boolean | false | Enforces exact SemVer compliance; specifically rejects "v" prefixes. |
includePrerelease | Boolean | false | Suppresses default behavior of excluding prerelease versions from range matches. |
rtl | Boolean | false | Used in coercion to find the right-most coercible string. |
Sources: README.md:274-281, classes/semver.js:10-34, functions/coerce.js:20-25
Loose Mode
Loose mode allows the parser to accept strings that are not strictly valid SemVer but are commonly used in the npm ecosystem. This includes versions with leading or trailing whitespace, or missing components that can be inferred. When loose is true, the system uses a different set of Regular Expressions (LOOSE and LOOSEPLAIN) which are less restrictive than the FULL counterparts.
Sources: internal/re.js:124-132, semver.js:133-146
Strict Mode
Strict mode is used to enforce high compliance with the SemVer specification. Its most notable behavior is the rejection of version strings starting with a "v" or "V" prefix, which the library normally allows and strips by default. If a version starts with "v" while options.strict is enabled, the constructor throws a TypeError.
Sources: README.md:280-281, classes/semver.js:31-34
Prerelease Inclusion
By default, prerelease versions (e.g., 1.2.3-alpha.1) are excluded from range matches unless a comparator in the range specifically includes a prerelease tag for that same [major, minor, patch] tuple. Setting includePrerelease: true suppresses this logic, treating prerelease versions as normal versions during comparison.
Sources: README.md:126-140, semver.js:685-715
Logic and Data Flow
The configuration options directly influence the Regular Expression selection and the internal branching logic of comparison functions.
Option Processing Flow
The following diagram illustrates how options are prioritized and used during the instantiation of a SemVer object.
The diagram shows the logic for resolving options and selecting the appropriate regex for parsing.
Sources: classes/semver.js:10-40, semver.js:256-270
Range Evaluation with Prerelease Flags
The includePrerelease option alters the outcome of range testing. Internally, testSet checks this flag to decide if a version with a prerelease component should be filtered out.
This flow explains how the includePrerelease configuration overrides the default safety mechanism that hides alpha/beta versions from general ranges.
Sources: semver.js:685-715, README.md:143-146
Internal Implementation Details
Constants and Limits
Configuration is also bounded by hardcoded internal constants that ensure system stability and prevent Regular Expression Denial of Service (ReDoS) attacks.
| Constant | Value | Description |
|---|---|---|
MAX_LENGTH | 256 | Maximum character length for a version string. |
MAX_SAFE_INTEGER | 9007199254740991 | The highest integer the library can safely process for version components. |
MAX_SAFE_COMPONENT_LENGTH | 16 | Max segment length specifically for coercion. |
Sources: internal/constants.js:5-15, semver.js:24-30
Safe Regex Replacements
The library uses a makeSafeRegex utility (or makeSafeRe in older versions) to modify exported regex tokens. It replaces greedy tokens like \d+ with bounded versions like \d{1,256} based on the MAX_LENGTH configuration to prevent performance issues with large input strings.
const safeRegexReplacements = [
['\\s', 1],
['\\d', MAX_LENGTH],
[LETTERDASHNUMBER, MAX_SAFE_BUILD_LENGTH],
]
const makeSafeRegex = (value) => {
for (const [token, max] of safeRegexReplacements) {
value = value
.split(`${token}*`).join(`${token}{0,${max}}`)
.split(`${token}+`).join(`${token}{1,${max}}`)
}
return value
}
Sources: internal/re.js:26-41, semver.js:46-60
Summary
Configuration in node-semver is centralized around the options object, which toggles between strict specification adherence and loose, ecosystem-compatible parsing. These settings control regex selection, prefix handling, and the inclusion of prerelease versions in range logic, ensuring that the library can be tuned for different environments—from strict CI/CD gates to permissive dependency resolution.