feat(migrate): skip ESLint migration when @nuxt/eslint is present

The @nuxt/eslint module wires ESLint into a Nuxt-specific flow that
Vite+ can't migrate cleanly today: the generated vite.config.ts ends
up referencing @nuxt/eslint-plugin (no longer installed), the user's
nuxt.config.ts still loads the removed module via `modules: [...]`,
and `nuxt dev` fails to boot until the user untangles it by hand.

Detect @nuxt/eslint in the project's package.json (root or any workspace
package) and skip ESLint migration entirely with a clear warning that
tells the user how to migrate manually. Their ESLint setup — eslint
itself, eslint.config.mjs, plugins, the `eslint` script — is preserved
verbatim. vite-plus is still added so the rest of the toolchain
adoption proceeds.

Verified end-to-end against
https://github.com/why-reproductions-are-required/vp-migrate-nuxt-eslint
(a minimal Nuxt 4 + @nuxt/eslint reproduction).

Author: fengmk2

packages/cli/snap-tests-global/migration-eslint-nuxt-skip/eslint.config.mjs

@@ -0,0 +1,10 @@
+// Stand-in for the auto-generated `.nuxt/eslint.config.mjs` flow.
+// We don't actually re-export from `.nuxt/` here so the snap-test
+// sandbox can load this file without running `nuxt prepare` first.
+export default [
+  {
+    rules: {
+      'no-unused-vars': 'error',
+    },
+  },
+];

packages/cli/snap-tests-global/migration-eslint-nuxt-skip/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "migration-eslint-nuxt-skip",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "nuxt build",
+    "dev": "nuxt dev",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "nuxt": "^4.0.0"
+  },
+  "devDependencies": {
+    "@nuxt/eslint": "^1.0.0",
+    "eslint": "^9.0.0",
+    "vite": "^7.0.0"
+  }
+}

packages/cli/snap-tests-global/migration-eslint-nuxt-skip/snap.txt

@@ -0,0 +1,31 @@
+> vp migrate --no-interactive # @nuxt/eslint detected — ESLint migration is skipped with a warning
+
+@nuxt/eslint detected — automatic ESLint migration is skipped. @nuxt/eslint wires ESLint into a framework-specific flow that Vite+ cannot migrate cleanly yet. Your ESLint setup is preserved. To migrate manually, remove @nuxt/eslint from package.json and re-run `vp migrate`.
+◇ Migrated . to Vite+
+• Node <semver>  pnpm <semver>
+• 2 config updates applied
+
+> cat package.json # eslint, @nuxt/eslint, and eslint.config.mjs are preserved
+{
+  "name": "migration-eslint-nuxt-skip",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "nuxt build",
+    "dev": "nuxt dev",
+    "lint": "eslint .",
+    "prepare": "vp config"
+  },
+  "dependencies": {
+    "nuxt": "^4.0.0"
+  },
+  "devDependencies": {
+    "@nuxt/eslint": "^1.0.0",
+    "eslint": "^9.0.0",
+    "vite": "catalog:",
+    "vite-plus": "catalog:"
+  },
+  "packageManager": "pnpm@<semver>"
+}
+
+> test -f eslint.config.mjs # eslint config file is NOT deleted

packages/cli/snap-tests-global/migration-eslint-nuxt-skip/steps.json

@@ -0,0 +1,7 @@
+{
+  "commands": [
+    "vp migrate --no-interactive # @nuxt/eslint detected — ESLint migration is skipped with a warning",
+    "cat package.json # eslint, @nuxt/eslint, and eslint.config.mjs are preserved",
+    "test -f eslint.config.mjs # eslint config file is NOT deleted"
+  ]
+}

packages/cli/src/migration/__tests__/migrator.spec.ts

@@ -28,6 +28,7 @@ const {
   addFrameworkShim,
   injectCreateDefaultTemplate,
   rewriteEslintPackageJson,
+  detectIncompatibleEslintIntegration,
 } = await import('../migrator.js');
 
 describe('rewritePackageJson', () => {
@@ -552,6 +553,57 @@ describe('rewriteEslintPackageJson', () => {
   });
 });
 
+function writePkgAt(dir: string, pkg: object): void {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(pkg));
+}
+
+describe('detectIncompatibleEslintIntegration', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'vp-test-incompat-eslint-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns "@nuxt/eslint" when listed in devDependencies', () => {
+    writePkgAt(tmpDir, { devDependencies: { '@nuxt/eslint': '^1.0.0' } });
+    expect(detectIncompatibleEslintIntegration(tmpDir)).toBe('@nuxt/eslint');
+  });
+
+  it('returns "@nuxt/eslint" when listed in dependencies', () => {
+    writePkgAt(tmpDir, { dependencies: { '@nuxt/eslint': '^1.0.0' } });
+    expect(detectIncompatibleEslintIntegration(tmpDir)).toBe('@nuxt/eslint');
+  });
+
+  it('detects when @nuxt/eslint lives in a workspace package, not the root', () => {
+    writePkgAt(tmpDir, { name: 'root' });
+    writePkgAt(path.join(tmpDir, 'packages/app'), {
+      name: 'app',
+      devDependencies: { '@nuxt/eslint': '^1.0.0' },
+    });
+    expect(
+      detectIncompatibleEslintIntegration(tmpDir, [
+        { name: 'app', path: 'packages/app', isTemplatePackage: false },
+      ]),
+    ).toBe('@nuxt/eslint');
+  });
+
+  it('returns undefined when @nuxt/eslint is absent', () => {
+    writePkgAt(tmpDir, {
+      devDependencies: { eslint: '^9.0.0', '@nuxt/kit': '^3.0.0' },
+    });
+    expect(detectIncompatibleEslintIntegration(tmpDir)).toBeUndefined();
+  });
+
+  it('returns undefined when package.json is missing', () => {
+    expect(detectIncompatibleEslintIntegration(tmpDir)).toBeUndefined();
+  });
+});
+
 describe('parseNvmrcVersion', () => {
   it('strips v prefix', () => {
     expect(parseNvmrcVersion('v20.5.0')).toBe('20.5.0');

packages/cli/src/migration/bin.ts

@@ -47,6 +47,7 @@ import {
   confirmPrettierMigration,
   detectEslintProject,
   detectFramework,
+  detectIncompatibleEslintIntegration,
   detectNodeVersionManagerFile,
   detectPrettierProject,
   hasFrameworkShim,
@@ -60,6 +61,7 @@ import {
   promptPrettierMigration,
   rewriteMonorepo,
   rewriteStandaloneProject,
+  warnIncompatibleEslintIntegration,
   warnLegacyEslintConfig,
   warnPackageLevelEslint,
   warnPackageLevelPrettier,
@@ -374,8 +376,17 @@ async function collectMigrationPlan(
 
   // 7. ESLint detection + prompt
   const eslintProject = detectEslintProject(rootDir, packages);
+  const incompatibleEslintIntegration = detectIncompatibleEslintIntegration(rootDir, packages);
   let migrateEslint = false;
-  if (eslintProject.hasDependency && !eslintProject.configFile && eslintProject.legacyConfigFile) {
+  if (incompatibleEslintIntegration) {
+    // e.g. `@nuxt/eslint` — skip the entire ESLint migration; preserve
+    // the user's current ESLint setup and let them migrate by hand.
+    warnIncompatibleEslintIntegration(incompatibleEslintIntegration);
+  } else if (
+    eslintProject.hasDependency &&
+    !eslintProject.configFile &&
+    eslintProject.legacyConfigFile
+  ) {
     warnLegacyEslintConfig(eslintProject.legacyConfigFile);
   } else if (eslintProject.hasDependency && eslintProject.configFile) {
     migrateEslint = await confirmEslintMigration(options.interactive);

packages/cli/src/migration/migrator.ts

@@ -2951,6 +2951,59 @@ export function warnPackageLevelEslint() {
   );
 }
 
+// Framework-ESLint integration packages we can't migrate cleanly today.
+// When any of these is present, the ESLint migration is skipped entirely
+// — the user's ESLint setup stays intact and they get told how to proceed
+// manually.
+//
+// `@nuxt/eslint` is a Nuxt module that loads ESLint at runtime via the
+// dev server and writes a generated config to `.nuxt/eslint.config.mjs`,
+// which the user's `eslint.config.mjs` re-exports. Migrating it
+// produces a broken state: `vite.config.ts` references `@nuxt/eslint-plugin`
+// (no longer installed) and `nuxt.config.ts` still tries to load the
+// removed module. Track at https://github.com/voidzero-dev/vite-plus/issues
+// once an issue exists.
+const INCOMPATIBLE_ESLINT_INTEGRATIONS = ['@nuxt/eslint'] as const;
+
+/**
+ * Detect framework-ESLint integration packages whose ESLint migration is
+ * known to be incompatible. Returns the offending package name, or
+ * `undefined` if none is present.
+ */
+export function detectIncompatibleEslintIntegration(
+  projectPath: string,
+  packages?: WorkspacePackage[],
+): string | undefined {
+  const candidates = [projectPath, ...(packages ?? []).map((p) => path.join(projectPath, p.path))];
+  for (const candidate of candidates) {
+    const pkgJsonPath = path.join(candidate, 'package.json');
+    if (!fs.existsSync(pkgJsonPath)) {
+      continue;
+    }
+    let pkg: { devDependencies?: Record<string, string>; dependencies?: Record<string, string> };
+    try {
+      pkg = readJsonFile(pkgJsonPath) as typeof pkg;
+    } catch {
+      continue;
+    }
+    for (const name of INCOMPATIBLE_ESLINT_INTEGRATIONS) {
+      if (pkg.devDependencies?.[name] || pkg.dependencies?.[name]) {
+        return name;
+      }
+    }
+  }
+  return undefined;
+}
+
+export function warnIncompatibleEslintIntegration(name: string): void {
+  prompts.log.warn(
+    `${name} detected — automatic ESLint migration is skipped. ` +
+      `${name} wires ESLint into a framework-specific flow that Vite+ cannot migrate cleanly yet. ` +
+      'Your ESLint setup is preserved. ' +
+      `To migrate manually, remove ${name} from package.json and re-run \`vp migrate\`.`,
+  );
+}
+
 export function warnLegacyEslintConfig(legacyConfigFile: string) {
   prompts.log.warn(
     `Legacy ESLint configuration detected (${legacyConfigFile}). ` +
@@ -2983,6 +3036,11 @@ export async function promptEslintMigration(
   interactive: boolean,
   packages?: WorkspacePackage[],
 ): Promise<boolean> {
+  const incompatible = detectIncompatibleEslintIntegration(projectPath, packages);
+  if (incompatible) {
+    warnIncompatibleEslintIntegration(incompatible);
+    return false;
+  }
   const eslintProject = detectEslintProject(projectPath, packages);
   if (eslintProject.hasDependency && !eslintProject.configFile && eslintProject.legacyConfigFile) {
     warnLegacyEslintConfig(eslintProject.legacyConfigFile);