#1573·fnm

Docs: add .nvmrc / .node-version behavior parity notes vs nvm (comments, lts/*, system, version resolution)

Author: chirag127Created Jul 1, 2026Updated Aug 17, 2026

Docs: Add .nvmrc / .node-version behavior parity notes vs nvm

Problem

Developers migrating from nvm to fnm expect identical .nvmrc behavior. There are subtle differences that are not documented anywhere in the fnm README or docs:

  1. Comments: nvm supports # comment lines in .nvmrc. Does fnm? Undocumented.
  2. lts/* alias: nvm accepts lts/*, lts/hydrogen, etc. fnm's behavior with these aliases in .nvmrc is not documented — does it resolve? Fall through to node@lts? Error?
  3. system keyword: nvm accepts system to mean "use the system-installed Node." fnm behavior with system in .nvmrc is undocumented.
  4. Version resolution order: nvm checks .nvmrc then .node-version. fnm checks both but the precedence when both exist in the same directory is not documented.
  5. Partial versions: .nvmrc containing 22 (major only) vs 22.11 (major.minor) vs 22.11.0 (full). nvm resolves partial versions to the latest matching. fnm behavior: partially documented in changelog entries but not in a user-facing doc.

Proposed fix

Add a .nvmrc and .node-version compatibility section to the README (or to a docs/nvmrc.md) that:

  • Lists each nvm-specific syntax (lts/*, system, comments, partial versions) and states whether fnm supports it
  • Notes the .nvmrc vs .node-version precedence rule
  • Links to the relevant fnm source for each behavior so users can verify

This would reduce the flood of "fnm doesn't work with my .nvmrc" issues.

Environment

  • OS: Windows 11 Enterprise
  • fnm: latest via Scoop
  • Context: migrating a polyrepo from nvm to fnm; .nvmrc files use lts/* in several packages