Installation and Setup
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The node-semver project is the semantic version parser used by npm. It implements the SemVer 2.0.0 specification to provide versioning logic for Node.js packages. This module can be utilized both as a programmatic library within Node.js applications and as a command-line interface (CLI) tool for version manipulation and validation.
The installation and setup process involves adding the package to a project's dependencies via npm and optionally configuring environment variables for debugging. For contributors, the setup includes a specific suite of development tools and coding conventions to ensure compliance with the project's maintenance standards.
Sources: package.json:4-5, README.md:1-5, internal/constants.js:5-6
Basic Installation
The package is distributed via the npm registry. It is intended to be used as a dependency in Node.js environments.
Programmatic Use
To install node-semver as a project dependency:
npm install --save semver
Sources: README.md:8-10
Once installed, the module can be required in JavaScript files to access its core functions such as valid, satisfies, and coerce.
const semver = require('semver')
semver.valid('1.2.3') // '1.2.3'
Sources: README.md:15-18
Command Line Interface (CLI)
The package includes a binary executable named semver located at ./bin/semver. This allows users to run version checks and increments directly from the terminal.
# Example CLI usage
semver 1.2.3 -i prerelease --preid beta
Sources: package.json:23-25, README.md:46-52
Development Setup
For developers contributing to the repository, the environment requires specific Node.js versions and testing tools.
Environment Requirements
The project maintains compatibility with older Node.js versions. For CI and testing purposes, version 6.17.1 is used as a baseline for "Old Node" support, while the latest CI tests run on version 20.
| Requirement | Value | Description |
|---|---|---|
| Baseline Node.js | 6.17.1 | Ensures no modern syntax breaks legacy support |
| Latest CI Node.js | 20 | Current target for modern environment testing |
| Package Manager | npm | Used for dependency management and running scripts |
Sources: scripts/template-oss/index.js:7-14
Setup Flow for Contributors
The following diagram illustrates the workflow for setting up the development environment and submitting changes.
The project uses tap for testing and a standard linting configuration. Pull requests are automatically validated against these requirements.
Sources: package.json:8-14, CONTRIBUTING.md:27-38
Configuration and Options
The node-semver module behavior can be modified through programmatic options and environment variables.
Global Debugging
The module includes internal debugging logic that can be enabled using the NODE_DEBUG environment variable.
NODE_DEBUG=semver node my-app.js
When enabled, the internal debug function logs details about regex execution and parsing steps to the console.
Sources: semver.js:5-18
Function Options
Most exported functions and classes (e.g., SemVer, Comparator, Range) accept an options object to control parsing behavior.
| Option | Type | Default | Description |
|---|---|---|---|
loose | Boolean | false | Be more forgiving about non-compliant strings (e.g., leading = or v). |
includePrerelease | Boolean | false | Suppresses default behavior of excluding prerelease versions from ranges. |
strict | Boolean | false | If true, throws TypeError for versions with 'v' or 'V' prefixes. |
Sources: README.md:195-207, semver.js:193-201
Project Architecture Overview
The module is structured with a central entry point that aggregates various internal modules, constants, and classes.
This structure ensures that high-level APIs (exported via index.js) rely on specific implementations for version parsing and range satisfying.
Sources: index.js:1-60, package.json:6
Summary
Setting up node-semver is straightforward for both consumers and contributors. Consumers can install the package via npm to access its robust version parsing logic programmatically or via CLI. Contributors must adhere to a development environment that respects legacy Node.js support and utilizes the tap testing framework. Options like loose and strict mode allow developers to fine-tune the parser's sensitivity to meet specific project requirements.