feat(migrate): migrate .nvmrc to .node-version during vp migrate (#1159)

naokihaba · web-flow · commit 066fe5fb30a6 · 2026-03-27T17:44:50.000+08:00
### 🔗 Related Issues  Resolves: #1158 ### 📚 Description Vite+ previously retrieved the Node.js version from .node-version, but projects using nvm typically use .nvmrc. With this change, automatic detection of .nvmrc and a migration feature to .node-version have been added as part of the vp migrate command execution process. During migration, if a v prefix is present at the beginning, it is removed, while aliases such as lts/* are carried over as is. Unit tests have confirmed that it works correctly regardless of the presence of the v prefix. On the other hand, if unsupported aliases like node or stable are included, the system is designed to display a warning and skip the migration rather than failing. ### Manual Test: .nvmrc Migration ```bash $ mkdir /tmp/vp-migrate-test $ echo '{ "name": "test-migrate", "version": "1.0.0" }' > package.json $ echo 'v20.5.0' > .nvmrc ``` #### Command ```bash $ cd /tmp/vp-migrate-test && vp migrate --no-interactive ``` #### Output (Excerpt) ``` .nvmrc detected. Auto-migrating to .node-version... ... • Node version manager file migrated to .node-version ``` #### Final State ``` $ cat /tmp/vp-migrate-test/.node-version 20.5.0 ``` - .nvmrc (v20.5.0) -> Deleted - .node-version -> 20.5.0 (With the v prefix removed)
diff --git a/packages/cli/snap-tests-global/migration-nvmrc-lts/.nvmrc b/packages/cli/snap-tests-global/migration-nvmrc-lts/.nvmrc
@@ -0,0 +1 @@
+lts/iron
diff --git a/packages/cli/snap-tests-global/migration-nvmrc-lts/package.json b/packages/cli/snap-tests-global/migration-nvmrc-lts/package.json
@@ -0,0 +1,6 @@
+{
+  "name": "migration-nvmrc-lts",
+  "devDependencies": {
+    "vite": "^7.0.0"
+  }
+}
diff --git a/packages/cli/snap-tests-global/migration-nvmrc-lts/snap.txt b/packages/cli/snap-tests-global/migration-nvmrc-lts/snap.txt
@@ -0,0 +1,12 @@
+> vp migrate --no-interactive # migration should detect .nvmrc with lts alias and auto-migrate
+VITE+ - The Unified Toolchain for the Web
+
+◇ Migrated . to Vite+<repeat>
+• Node <semver>  pnpm <semver>
+• 2 config updates applied
+• Node version manager file migrated to .node-version
+
+> cat .node-version # check lts alias is preserved as-is
+lts/iron
+
+> test ! -f .nvmrc # check .nvmrc is removed
diff --git a/packages/cli/snap-tests-global/migration-nvmrc-lts/steps.json b/packages/cli/snap-tests-global/migration-nvmrc-lts/steps.json
@@ -0,0 +1,7 @@
+{
+  "commands": [
+    "vp migrate --no-interactive # migration should detect .nvmrc with lts alias and auto-migrate",
+    "cat .node-version # check lts alias is preserved as-is",
+    "test ! -f .nvmrc # check .nvmrc is removed"
+  ]
+}
diff --git a/packages/cli/snap-tests-global/migration-nvmrc-node-alias/.nvmrc b/packages/cli/snap-tests-global/migration-nvmrc-node-alias/.nvmrc
@@ -0,0 +1 @@
+node
diff --git a/packages/cli/snap-tests-global/migration-nvmrc-node-alias/package.json b/packages/cli/snap-tests-global/migration-nvmrc-node-alias/package.json
@@ -0,0 +1,6 @@
+{
+  "name": "migration-nvmrc-node-alias",
+  "devDependencies": {
+    "vite": "^7.0.0"
+  }
+}
diff --git a/packages/cli/snap-tests-global/migration-nvmrc-node-alias/snap.txt b/packages/cli/snap-tests-global/migration-nvmrc-node-alias/snap.txt
@@ -0,0 +1,14 @@
+> vp migrate --no-interactive # 'node' alias should be mapped to lts/* with an info message
+VITE+ - The Unified Toolchain for the Web
+
+
+"node" in .nvmrc is not a specific version; automatically mapping to "lts/*"
+◇ Migrated . to Vite+<repeat>
+• Node <semver>  pnpm <semver>
+• 2 config updates applied
+• Node version manager file migrated to .node-version
+
+> cat .node-version # check node alias is mapped to lts/*
+lts/*
+
+> test ! -f .nvmrc # check .nvmrc is removed
diff --git a/packages/cli/snap-tests-global/migration-nvmrc-node-alias/steps.json b/packages/cli/snap-tests-global/migration-nvmrc-node-alias/steps.json
@@ -0,0 +1,7 @@
+{
+  "commands": [
+    "vp migrate --no-interactive # 'node' alias should be mapped to lts/* with an info message",
+    "cat .node-version # check node alias is mapped to lts/*",
+    "test ! -f .nvmrc # check .nvmrc is removed"
+  ]
+}
diff --git a/packages/cli/snap-tests-global/migration-nvmrc/.nvmrc b/packages/cli/snap-tests-global/migration-nvmrc/.nvmrc
@@ -0,0 +1 @@
+v25.8.2
diff --git a/packages/cli/snap-tests-global/migration-nvmrc/package.json b/packages/cli/snap-tests-global/migration-nvmrc/package.json
@@ -0,0 +1,6 @@
+{
+  "name": "migration-nvmrc",
+  "devDependencies": {
+    "vite": "^7.0.0"
+  }
+}
diff --git a/packages/cli/snap-tests-global/migration-nvmrc/snap.txt b/packages/cli/snap-tests-global/migration-nvmrc/snap.txt
@@ -0,0 +1,12 @@
+> vp migrate --no-interactive # migration should detect .nvmrc and auto-migrate to .node-version
+VITE+ - The Unified Toolchain for the Web
+
+◇ Migrated . to Vite+<repeat>
+• Node <semver>  pnpm <semver>
+• 2 config updates applied
+• Node version manager file migrated to .node-version
+
+> cat .node-version # check .node-version is created with v prefix stripped
+25.8.2
+
+> test ! -f .nvmrc # check .nvmrc is removed
diff --git a/packages/cli/snap-tests-global/migration-nvmrc/steps.json b/packages/cli/snap-tests-global/migration-nvmrc/steps.json
@@ -0,0 +1,7 @@
+{
+  "commands": [
+    "vp migrate --no-interactive # migration should detect .nvmrc and auto-migrate to .node-version",
+    "cat .node-version # check .node-version is created with v prefix stripped",
+    "test ! -f .nvmrc # check .nvmrc is removed"
+  ]
+}
diff --git a/packages/cli/src/migration/__tests__/migrator.spec.ts b/packages/cli/src/migration/__tests__/migrator.spec.ts
@@ -1,4 +1,8 @@
-import { describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { PackageManager } from '../../types/index.js';
 
@@ -10,7 +14,12 @@ vi.mock('../../utils/constants.js', async (importOriginal) => {
   return { ...mod, VITE_PLUS_VERSION: 'latest' };
 });
 
-const { rewritePackageJson } = await import('../migrator.js');
+const {
+  rewritePackageJson,
+  parseNvmrcVersion,
+  detectNodeVersionManagerFile,
+  migrateNodeVersionManagerFile,
+} = await import('../migrator.js');
 
 describe('rewritePackageJson', () => {
   it('should rewrite package.json scripts and extract staged config', async () => {
@@ -121,3 +130,109 @@ describe('rewritePackageJson', () => {
     expect(pkg).toMatchSnapshot();
   });
 });
+
+describe('parseNvmrcVersion', () => {
+  it('strips v prefix', () => {
+    expect(parseNvmrcVersion('v20.5.0')).toBe('20.5.0');
+  });
+
+  it('passes through version without prefix', () => {
+    expect(parseNvmrcVersion('20.5.0')).toBe('20.5.0');
+    expect(parseNvmrcVersion('20')).toBe('20');
+  });
+
+  it('passes through lts aliases', () => {
+    expect(parseNvmrcVersion('lts/*')).toBe('lts/*');
+    expect(parseNvmrcVersion('lts/iron')).toBe('lts/iron');
+    expect(parseNvmrcVersion('lts/-1')).toBe('lts/-1');
+  });
+
+  it('converts node/stable aliases to lts/*', () => {
+    expect(parseNvmrcVersion('node')).toBe('lts/*');
+    expect(parseNvmrcVersion('stable')).toBe('lts/*');
+  });
+
+  it('returns null for untranslatable aliases', () => {
+    expect(parseNvmrcVersion('iojs')).toBeNull();
+    expect(parseNvmrcVersion('system')).toBeNull();
+    expect(parseNvmrcVersion('default')).toBeNull();
+    expect(parseNvmrcVersion('')).toBeNull();
+  });
+
+  it('returns null for invalid version strings', () => {
+    expect(parseNvmrcVersion('v')).toBeNull();
+    expect(parseNvmrcVersion('laetst')).toBeNull();
+    expect(parseNvmrcVersion('20.5.0.1')).toBeNull();
+  });
+});
+
+describe('detectNodeVersionManagerFile', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'vp-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns undefined when no version files found', () => {
+    expect(detectNodeVersionManagerFile(tmpDir)).toBeUndefined();
+  });
+
+  it('returns undefined when .node-version already exists', () => {
+    fs.writeFileSync(path.join(tmpDir, '.node-version'), '20.5.0\n');
+    fs.writeFileSync(path.join(tmpDir, '.nvmrc'), 'v20.5.0\n');
+    expect(detectNodeVersionManagerFile(tmpDir)).toBeUndefined();
+  });
+
+  it('detects .nvmrc', () => {
+    fs.writeFileSync(path.join(tmpDir, '.nvmrc'), 'v20.5.0\n');
+    expect(detectNodeVersionManagerFile(tmpDir)).toEqual({ file: '.nvmrc' });
+  });
+});
+
+describe('migrateNodeVersionManagerFile', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'vp-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('migrates .nvmrc to .node-version and removes .nvmrc', () => {
+    fs.writeFileSync(path.join(tmpDir, '.nvmrc'), 'v20.5.0\n');
+    const ok = migrateNodeVersionManagerFile(tmpDir, { file: '.nvmrc' });
+    expect(ok).toBe(true);
+    expect(fs.readFileSync(path.join(tmpDir, '.node-version'), 'utf8')).toBe('20.5.0\n');
+    expect(fs.existsSync(path.join(tmpDir, '.nvmrc'))).toBe(false);
+  });
+
+  it('returns false and warns for unsupported alias', () => {
+    fs.writeFileSync(path.join(tmpDir, '.nvmrc'), 'system\n');
+    const report = {
+      createdViteConfigCount: 0,
+      mergedConfigCount: 0,
+      mergedStagedConfigCount: 0,
+      inlinedLintStagedConfigCount: 0,
+      removedConfigCount: 0,
+      tsdownImportCount: 0,
+      rewrittenImportFileCount: 0,
+      rewrittenImportErrors: [],
+      eslintMigrated: false,
+      prettierMigrated: false,
+      nodeVersionFileMigrated: false,
+      gitHooksConfigured: false,
+      warnings: [],
+      manualSteps: [],
+    };
+    const ok = migrateNodeVersionManagerFile(tmpDir, { file: '.nvmrc' }, report);
+    expect(ok).toBe(false);
+    expect(report.warnings.length).toBe(1);
+    expect(fs.existsSync(path.join(tmpDir, '.node-version'))).toBe(false);
+  });
+});
diff --git a/packages/cli/src/migration/bin.ts b/packages/cli/src/migration/bin.ts
@@ -44,14 +44,17 @@ import {
   checkVitestVersion,
   checkViteVersion,
   detectEslintProject,
+  detectNodeVersionManagerFile,
   detectPrettierProject,
   installGitHooks,
   mergeViteConfigFiles,
   migrateEslintToOxlint,
+  migrateNodeVersionManagerFile,
   migratePrettierToOxfmt,
   preflightGitHooksSetup,
   rewriteMonorepo,
   rewriteStandaloneProject,
+  type NodeVersionManagerDetection,
 } from './migrator.js';
 import { createMigrationReport, type MigrationReport } from './report.js';
 
@@ -168,6 +171,20 @@ async function promptPrettierMigration(
   return true;
 }
 
+async function confirmNodeVersionFileMigration(interactive: boolean): Promise<boolean> {
+  if (interactive) {
+    const confirmed = await prompts.confirm({
+      message: 'Migrate .nvmrc to .node-version?',
+      initialValue: true,
+    });
+    if (prompts.isCancel(confirmed)) {
+      cancelAndExit();
+    }
+    return !!confirmed;
+  }
+  return true;
+}
+
 const helpMessage = renderCliDoc({
   usage: 'vp migrate [PATH] [OPTIONS]',
   summary:
@@ -319,6 +336,8 @@ interface MigrationPlan {
   eslintConfigFile?: string;
   migratePrettier: boolean;
   prettierConfigFile?: string;
+  migrateNodeVersionFile: boolean;
+  nodeVersionDetection?: NodeVersionManagerDetection;
 }
 
 async function collectMigrationPlan(
@@ -436,6 +455,13 @@ async function collectMigrationPlan(
     warnPackageLevelPrettier();
   }
 
+  // 10. Node version manager file detection + prompt
+  const nodeVersionDetection = detectNodeVersionManagerFile(rootDir);
+  let migrateNodeVersionFile = false;
+  if (nodeVersionDetection) {
+    migrateNodeVersionFile = await confirmNodeVersionFileMigration(options.interactive);
+  }
+
   const plan: MigrationPlan = {
     packageManager,
     shouldSetupHooks,
@@ -447,6 +473,8 @@ async function collectMigrationPlan(
     eslintConfigFile: eslintProject.configFile,
     migratePrettier,
     prettierConfigFile: prettierProject.configFile,
+    migrateNodeVersionFile,
+    nodeVersionDetection,
   };
 
   return plan;
@@ -523,6 +551,9 @@ function showMigrationSummary(options: {
   if (report.prettierMigrated) {
     log(`${styleText('gray', '•')} Prettier migrated to Oxfmt`);
   }
+  if (report.nodeVersionFileMigrated) {
+    log(`${styleText('gray', '•')} Node version manager file migrated to .node-version`);
+  }
   if (report.gitHooksConfigured) {
     log(`${styleText('gray', '•')} Git hooks configured`);
   }
@@ -633,7 +664,13 @@ async function executeMigrationPlan(
     cancelAndExit('Vite+ cannot automatically migrate this project yet.', 1);
   }
 
-  // 3. Run vp install to ensure the project is ready
+  // 3. Migrate node version manager file → .node-version (independent of vite version)
+  if (plan.migrateNodeVersionFile && plan.nodeVersionDetection) {
+    updateMigrationProgress('Migrating node version file');
+    migrateNodeVersionManagerFile(workspaceInfo.rootDir, plan.nodeVersionDetection, report);
+  }
+
+  // 4. Run vp install to ensure the project is ready
   updateMigrationProgress('Installing dependencies');
   const initialInstallSummary = await runViteInstall(
     workspaceInfo.rootDir,
@@ -816,6 +853,18 @@ async function main() {
       workspaceInfoOptional.packages,
     );
 
+    // Check if node version manager file migration is needed
+    const nodeVersionDetection = detectNodeVersionManagerFile(workspaceInfoOptional.rootDir);
+    if (nodeVersionDetection) {
+      const confirmed = await confirmNodeVersionFileMigration(options.interactive);
+      if (
+        confirmed &&
+        migrateNodeVersionManagerFile(workspaceInfoOptional.rootDir, nodeVersionDetection, report)
+      ) {
+        didMigrate = true;
+      }
+    }
+
     // Merge configs and reinstall once if any tool migration happened
     if (eslintMigrated || prettierMigrated) {
       updateMigrationProgress('Rewriting configs');
diff --git a/packages/cli/src/migration/detector.ts b/packages/cli/src/migration/detector.ts
@@ -11,6 +11,7 @@ export interface ConfigFiles {
   eslintLegacyConfig?: string;
   prettierConfig?: string; // e.g. '.prettierrc.json', 'prettier.config.js', PRETTIER_PACKAGE_JSON_CONFIG
   prettierIgnore?: boolean;
+  nvmrcFile?: boolean;
 }
 
 // Sentinel value indicating Prettier config lives inside package.json "prettier" key.
@@ -178,5 +179,10 @@ export function detectConfigs(projectPath: string): ConfigFiles {
     configs.prettierIgnore = true;
   }
 
+  // Check for .nvmrc (nvm)
+  if (fs.existsSync(path.join(projectPath, '.nvmrc'))) {
+    configs.nvmrcFile = true;
+  }
+
   return configs;
 }
diff --git a/packages/cli/src/migration/migrator.ts b/packages/cli/src/migration/migrator.ts
diff --git a/packages/cli/src/migration/report.ts b/packages/cli/src/migration/report.ts
