How nvm Handles LTS Version Aliases: Mechanism and Implementation

nvm treats Long-Term Support (LTS) releases as dynamic filesystem aliases stored in $NVM_DIR/alias/lts/, resolving patterns like lts/* or lts/erbium to concrete Node.js versions at runtime through the nvm_normalize_lts and nvm_resolve_alias functions.

Node Version Manager (nvm) simplifies Node.js version management through an intelligent alias system that automatically tracks Long-Term Support (LTS) releases. Understanding how nvm handles LTS version aliases reveals the mechanism behind commands like nvm install --lts and nvm use lts/erbium, which dynamically resolve to specific semantic versions without requiring manual updates to version strings.

The LTS Alias Architecture

The Alias Directory Structure

The foundation of nvm's LTS handling resides in the filesystem. According to the nvm source code in nvm.sh around line 1708, nvm maintains a dedicated directory at $NVM_DIR/alias/lts/. Each file within this directory represents a named LTS line (such as erbium, fermium, or iron), and contains the exact Node.js version string that currently represents that LTS release.

Core Resolution Functions

Two primary functions coordinate LTS resolution in nvm.sh:

nvm_normalize_lts (lines 909-942): This function handles the normalization of LTS patterns. It accepts inputs like lts/* (latest LTS), lts/-N (Nth most recent LTS), or lts/<name> (specific named line). The function validates the name, enforces lowercase conversion, and returns the normalized alias format ready for filesystem lookup.

nvm_resolve_alias (lines 1389-1396): This function performs the actual alias chain resolution. It reads the content of alias files (including those in the lts/ directory) and follows the chain until reaching a concrete version string. It also detects circular references, breaking loops with the placeholder ∞ to prevent infinite recursion.

How nvm Resolves LTS Version Aliases at Runtime

When you execute a command like nvm install --lts, the resolution follows a specific pipeline through the nvm source code:

1. CLI Flag Parsing: The --lts flag sets NVM_LTS='*' (or captures a specific name with --lts=<name>), as implemented around lines 3395-3400 in nvm.sh.

2. Pattern Matching: The function nvm_match_version (lines 3730-3740) receives the pattern lts/${NVM_LTS} and forwards it to the resolution chain.

3. LTS Normalization: nvm_normalize_lts processes the pattern:

   • For lts/*, it counts the files in $NVM_DIR/alias/lts/ to determine the latest LTS
   • For lts/-N, it calculates the Nth most recent LTS
   • For named aliases like lts/erbium, it validates and lowercases the name

4. Alias Resolution: nvm_resolve_alias reads the corresponding file from the LTS alias directory and returns the concrete version string (e.g., v18.17.0).

5. Execution: The resolved version is passed to the standard install or use routines.

Creating and Managing LTS Aliases

Manual Alias Creation

Users can create custom LTS aliases using the nvm alias command. According to the source code in nvm.sh (lines 1239-1242), running:

nvm alias lts/boron 14.19.0

creates a file at $NVM_DIR/alias/lts/boron containing the version string 14.19.0. This file then participates in the standard resolution chain described above.

Automatic LTS Tracking

The nvm project maintains official LTS mappings through the update_test_mocks.sh script, which generates mock files for testing. In production, nvm relies on the community-maintained alias files in the alias/lts/ directory to track which specific semantic versions correspond to active LTS lines like iron or jod.

Edge Cases and Error Handling

The nvm source code implements robust validation for LTS alias edge cases:

Non-existent Numeric Offsets: When requesting lts/-99 (a deeper history than exists), nvm_normalize_lts detects the overflow and exits with status 2, printing That many LTS releases do not exist yet.

Case Sensitivity: LTS names must be lowercase. The normalization function explicitly checks for uppercase characters and aborts with LTS names must be lowercase (line 935).

Circular References: The nvm_resolve_alias function tracks visited aliases during chain resolution. If it detects a loop, it breaks the cycle by returning the placeholder ∞, preventing infinite recursion.

Missing Alias Files: If an LTS alias file does not exist, the resolver falls back to treating the pattern as a literal version string. This subsequently fails with the standard "not installed" message during execution.

Summary

• nvm stores LTS aliases as files in $NVM_DIR/alias/lts/, where each filename represents an LTS line name and contains the corresponding Node.js version string.
• The nvm_normalize_lts function (lines 909-942 in nvm.sh) handles syntax like lts/*, lts/-N, and lts/<name>, validating inputs and resolving offsets.
• nvm_resolve_alias (lines 1389-1396) performs the actual file-based resolution, reading LTS alias contents and detecting circular references.
• CLI flags --lts and --lts=<name> trigger this resolution pipeline via nvm_match_version, mapping abstract LTS references to concrete semantic versions at runtime.

Frequently Asked Questions

How does nvm determine which version is the latest LTS?

nvm counts the files present in $NVM_DIR/alias/lts/ to determine how many LTS lines exist. When you specify lts/* or lts/-1, the nvm_normalize_lts function calculates the offset from the most recent entry and returns the corresponding LTS name, which is then resolved to a concrete version via nvm_resolve_alias.

Can I create custom LTS aliases that aren't official Node.js LTS names?

Yes. You can create arbitrary LTS aliases using nvm alias lts/<custom-name> <version>. According to the source code in nvm.sh (lines 1239-1242), this writes the version string to $NVM_DIR/alias/lts/<custom-name>, making it available for resolution via nvm use lts/<custom-name> or nvm install lts/<custom-name>.

What happens if I request an LTS version that doesn't exist?

If you request a non-existent named LTS (e.g., lts/nonexistent), nvm_resolve_alias fails to find the file in $NVM_DIR/alias/lts/ and falls back to treating the string as a literal version. This subsequently results in a "version not found" or "not installed" error during the install or use phase. For numeric offsets like lts/-99 that exceed available LTS lines, nvm_normalize_lts explicitly exits with status 2 and prints an error message.

Why does nvm require lowercase LTS names?

The nvm_normalize_lts function enforces lowercase to ensure consistent filesystem behavior and prevent alias fragmentation. Since Unix filesystems are case-sensitive, allowing mixed-case LTS names would create separate files for LTS/Erbium and lts/erbium, causing confusion. The validation at line 935 in nvm.sh explicitly rejects uppercase characters with the message "LTS names must be lowercase" to maintain a canonical naming convention.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}