@next/codemod 16.4.0-canary.8 → 16.4.0

package/README.md

@@ -7,3 +7,14 @@ Codemods are transformations that run on your codebase programmatically. This al
 ## Documentation
 
 Visit [nextjs.org/docs/advanced-features/codemods](https://nextjs.org/docs/app/guides/upgrading/codemods) to view the documentation for this package.
+
+## Skip optional feature adoption
+
+`upgrade --skip-adoption` skips codemods marked as feature adoption in the
+registry while keeping version migrations and normal dependency selection.
+Currently this excludes `cache-components-instant-false` and the
+`remove-partial-prefetch` cleanup used after adopting partial prefetching.
+Both transforms can still be run explicitly.
+
+Combine it with `--yes` for an unattended version upgrade. Without
+`--skip-adoption`, the existing upgrade selections are unchanged.

package/bin/agents-md.js

@@ -37,7 +37,7 @@ async function runAgentsMd(options) {
         // --version provided: --output is required
         if (!options.output) {
             throw new shared_1.BadInput('When using --version, --output is also required.\n' +
-                'Example: npx @next/codemod agents-md --version 15.1.3 --output CLAUDE.md');
+                'Example: npx @next/codemod agents-md --version 15.1.3 --output AGENTS.md');
         }
         nextjsVersion = options.version;
         targetFile = options.output;
@@ -58,7 +58,7 @@ async function runAgentsMd(options) {
         nextjsVersion = promptedOptions.nextVersion;
         targetFile = promptedOptions.targetFile;
     }
-    const claudeMdPath = path_1.default.join(cwd, targetFile);
+    const agentsMdPath = path_1.default.join(cwd, targetFile);
     // Next.js >= 16.2.0 ships its docs inside the published package. When the
     // installed version matches the requested one, index the bundled docs
     // directly instead of downloading a copy into .next-docs.
@@ -73,8 +73,8 @@ async function runAgentsMd(options) {
     let sizeBefore = 0;
     let isNewFile = true;
     let existingContent = '';
-    if (fs_1.default.existsSync(claudeMdPath)) {
-        existingContent = fs_1.default.readFileSync(claudeMdPath, 'utf-8');
+    if (fs_1.default.existsSync(agentsMdPath)) {
+        existingContent = fs_1.default.readFileSync(agentsMdPath, 'utf-8');
         sizeBefore = Buffer.byteLength(existingContent, 'utf-8');
         isNewFile = false;
     }
@@ -94,13 +94,13 @@ async function runAgentsMd(options) {
     }
     const docFiles = (0, agents_md_1.collectDocFiles)(docsPath);
     const sections = (0, agents_md_1.buildDocTree)(docFiles);
-    const indexContent = (0, agents_md_1.generateClaudeMdIndex)({
+    const indexContent = (0, agents_md_1.generateAgentsMdIndex)({
         docsPath: docsLinkPath,
         sections,
         outputFile: targetFile,
     });
-    const newContent = (0, agents_md_1.injectIntoClaudeMd)(existingContent, indexContent);
-    fs_1.default.writeFileSync(claudeMdPath, newContent, 'utf-8');
+    const newContent = (0, agents_md_1.injectIntoAgentsMd)(existingContent, indexContent);
+    fs_1.default.writeFileSync(agentsMdPath, newContent, 'utf-8');
     const sizeAfter = Buffer.byteLength(newContent, 'utf-8');
     // .next-docs only exists on the download path; bundled docs live in
     // node_modules, which is already ignored.
@@ -136,7 +136,6 @@ async function promptForOptions(cwd) {
             name: 'targetFile',
             message: 'Target markdown file',
             choices: [
-                { title: 'CLAUDE.md', value: 'CLAUDE.md' },
                 { title: 'AGENTS.md', value: 'AGENTS.md' },
                 { title: 'Custom...', value: '__custom__' },
             ],
@@ -154,7 +153,7 @@ async function promptForOptions(cwd) {
             type: 'text',
             name: 'customFile',
             message: 'Enter custom file path',
-            initial: 'CLAUDE.md',
+            initial: 'AGENTS.md',
             validate: (value) => value.trim() ? true : 'Please enter a file path',
         }, { onCancel: utils_1.onCancel });
         if (customResponse.customFile === undefined) {

package/bin/next-codemod.js

@@ -44,6 +44,9 @@ program
     .usage('[revision] [options]')
     .option('--verbose', 'Verbose output', false)
     .option('-y, --yes', 'Skip every interactive prompt and accept its default. Also auto-enabled when stdin is not a TTY (e.g. running under an agent or in CI).', false)
+    .option('--skip-adoption', 'Skip optional feature-adoption codemods while applying version migrations.', false)
+    .option('--skip-react-upgrade', 'Keep React dependencies, types, and overrides unchanged and skip React codemods.', false)
+    .option('--skip-eslint-upgrade', 'Keep ESLint dependencies unchanged and skip the next-lint-to-eslint-cli codemod.', false)
     .action(async (revision, options) => {
     try {
         await (0, upgrade_1.runUpgrade)(revision, options);
@@ -62,7 +65,7 @@ program
     .command('agents-md')
     .description('Generate Next.js documentation index for AI coding agents (Claude, Cursor, etc.).')
     .option('--version <version>', 'Next.js version (auto-detected if not provided)')
-    .option('--output <file>', 'Target file path (e.g., CLAUDE.md, AGENTS.md)')
+    .option('--output <file>', 'Target file path (e.g., AGENTS.md)')
     .action(async (options) => {
     try {
         await (0, agents_md_1.runAgentsMd)(options);

package/bin/transform.js

@@ -56,7 +56,7 @@ async function runTransform(transform, path, options) {
         }, { onCancel: utils_1.onCancel });
         transformer = res.transformer;
     }
-    if (transformer === 'next-request-geo-ip') {
+    if (transformer === 'next-request-geo-ip' && !options.nonInteractive) {
         const { isAppDeployedToVercel } = await (0, prompts_1.default)({
             type: 'confirm',
             name: 'isAppDeployedToVercel',
@@ -99,7 +99,7 @@ async function runTransform(transform, path, options) {
     args.push('--parser=tsx');
     args.push('--ignore-pattern=**/node_modules/**');
     args.push('--ignore-pattern=**/.next/**');
-    args.push('--extensions=tsx,ts,jsx,js');
+    args.push('--extensions=tsx,ts,jsx,js,mjs');
     args = args.concat(['--transform', transformerPath]);
     if (jscodeshift) {
         args = args.concat(jscodeshift);
@@ -109,7 +109,10 @@ async function runTransform(transform, path, options) {
     const execaChildProcess = (0, execa_1.default)(exports.jscodeshiftExecutable, args, {
         // include ANSI color codes
         // Note: execa merges env with existing env by default.
-        env: process.stdout.isTTY ? { FORCE_COLOR: 'true' } : {},
+        env: {
+            ...process.env,
+            ...(process.stdout.isTTY ? { FORCE_COLOR: 'true' } : {}),
+        },
     });
     // "\n" + "a\n" + "b\n"
     let lastThreeLineBreaks = '';

package/bin/upgrade.js

@@ -190,6 +190,7 @@ async function runUpgrade(revision, options) {
     // x-ref(release): https://github.com/vercel/next.js/releases/tag/v14.3.0-canary.45
     (0, semver_1.compare)(targetNextVersion, '14.3.0-canary.45') >= 0 &&
         installedReactVersion.startsWith('18') &&
+        !options.skipReactUpgrade &&
         // Pure App Router always uses React 19
         // The mixed case is tricky to handle from a types perspective.
         // We'll recommend to upgrade in the prompt but users can decide to try 18.
@@ -218,20 +219,23 @@ async function runUpgrade(revision, options) {
     // E.g. in peerDependencies we could have `^18.2.0 || ^19.0.0 || 20.0.0-canary`
     // If we'd just `npm add` that, the manifest would read the same version query.
     // This is basically a `npm --save-exact react@$versionQuery` that works for every package manager.
-    const targetReactVersion = shouldStayOnReact18
-        ? '18.3.1'
-        : await loadHighestNPMVersionMatching(`react@${targetNextPackageJson.peerDependencies['react']}`);
+    const targetReactVersion = options.skipReactUpgrade
+        ? installedReactVersion
+        : shouldStayOnReact18
+            ? '18.3.1'
+            : await loadHighestNPMVersionMatching(`react@${targetNextPackageJson.peerDependencies['react']}`);
     if ((0, semver_1.compare)(targetNextVersion, '15.0.0-canary') >= 0 &&
         (0, semver_1.compare)(targetNextVersion, '16.0.0-canary') < 0) {
         await suggestTurbopack(appPackageJson, targetNextVersion, nonInteractive);
     }
-    const codemods = await suggestCodemods(installedNextVersion, targetNextVersion, nonInteractive);
+    const codemods = await suggestCodemods(installedNextVersion, targetNextVersion, nonInteractive, options.skipAdoption);
     const packageManager = (0, handle_package_1.getPkgManager)(cwd);
     let shouldRunReactCodemods = false;
     let shouldRunReactTypesCodemods = false;
     let execCommand = 'npx --yes';
     // The following React codemods are for React 19
-    if (!shouldStayOnReact18 &&
+    if (!options.skipReactUpgrade &&
+        !shouldStayOnReact18 &&
         (0, semver_1.compare)(targetReactVersion, '19.0.0-0') >= 0 &&
         (0, semver_1.compare)(installedReactVersion, '19.0.0-0') < 0) {
         shouldRunReactCodemods = await suggestReactCodemods(nonInteractive);
@@ -248,19 +252,31 @@ async function runUpgrade(revision, options) {
     };
     const versionMapping = {
         next: { version: targetNextVersion, required: true },
-        react: { version: targetReactVersion, required: true },
-        'react-dom': { version: targetReactVersion, required: true },
-        'react-is': { version: targetReactVersion, required: false },
     };
+    // Recovery retries must preserve the repaired React declarations and pins.
+    if (!options.skipReactUpgrade) {
+        Object.assign(versionMapping, {
+            react: { version: targetReactVersion, required: true },
+            'react-dom': { version: targetReactVersion, required: true },
+            'react-is': { version: targetReactVersion, required: false },
+        });
+    }
     for (const optionalNextjsPackage of optionalNextjsPackages) {
+        // Preserve the lint stack together; its newer config can require newer ESLint.
+        if (options.skipEslintUpgrade &&
+            (optionalNextjsPackage === 'eslint-config-next' ||
+                optionalNextjsPackage === '@next/eslint-plugin-next')) {
+            continue;
+        }
         versionMapping[optionalNextjsPackage] = {
             version: targetNextVersion,
             required: false,
         };
     }
-    if (targetReactVersion.startsWith('19.0.0-canary') ||
-        targetReactVersion.startsWith('19.0.0-beta') ||
-        targetReactVersion.startsWith('19.0.0-rc')) {
+    if (!options.skipReactUpgrade &&
+        (targetReactVersion.startsWith('19.0.0-canary') ||
+            targetReactVersion.startsWith('19.0.0-beta') ||
+            targetReactVersion.startsWith('19.0.0-rc'))) {
         const [targetReactTypesVersion, targetReactDOMTypesVersion] = await Promise.all([
             loadHighestNPMVersionMatching(`types-react@rc`),
             loadHighestNPMVersionMatching(`types-react-dom@rc`),
@@ -278,7 +294,7 @@ async function runUpgrade(revision, options) {
             };
         }
     }
-    else {
+    else if (!options.skipReactUpgrade) {
         const [targetReactTypesVersion, targetReactDOMTypesVersion] = await Promise.all([
             loadHighestNPMVersionMatching(`@types/react@${targetNextPackageJson.peerDependencies['react']}`),
             loadHighestNPMVersionMatching(`@types/react-dom@${targetNextPackageJson.peerDependencies['react']}`),
@@ -306,7 +322,9 @@ async function runUpgrade(revision, options) {
     // Only act when the project is actually using `eslint-config-next` — we
     // don't want to silently upgrade eslint majors for projects that use
     // eslint for unrelated reasons.
-    if (allDependencies['eslint'] && allDependencies['eslint-config-next']) {
+    if (!options.skipEslintUpgrade &&
+        allDependencies['eslint'] &&
+        allDependencies['eslint-config-next']) {
         try {
             const eslintConfigNextPeerDepsJSON = (0, child_process_1.execSync)(`npm --silent view "eslint-config-next@${targetNextVersion}" peerDependencies --json`, { encoding: 'utf-8' });
             const eslintConfigNextPeerDeps = eslintConfigNextPeerDepsJSON.trim() === ''
@@ -314,7 +332,13 @@ async function runUpgrade(revision, options) {
                 : JSON.parse(eslintConfigNextPeerDepsJSON);
             const eslintRange = eslintConfigNextPeerDeps?.eslint;
             if (eslintRange) {
-                const targetEslintVersion = await loadHighestNPMVersionMatching(`eslint@${eslintRange}`);
+                // TODO: Target ESLint 10 once eslint-config-next's plugins, especially
+                // eslint-plugin-react, support its API removals (e.g. context.getFilename).
+                const cappedRange = eslintRange
+                    .split('||')
+                    .map((range) => `${range.trim()} <10`)
+                    .join(' || ');
+                const targetEslintVersion = await loadHighestNPMVersionMatching(`eslint@${cappedRange}`);
                 versionMapping['eslint'] = {
                     version: targetEslintVersion,
                     required: false,
@@ -330,10 +354,10 @@ async function runUpgrade(revision, options) {
     // Even though we only need those if we alias `@types/react` to types-react,
     // we still do it out of safety due to https://github.com/microsoft/DefinitelyTyped-tools/issues/433.
     const overrides = {};
-    if (allDependencies['@types/react']) {
+    if (!options.skipReactUpgrade && allDependencies['@types/react']) {
         overrides['@types/react'] = versionMapping['@types/react'].version;
     }
-    if (allDependencies['@types/react-dom']) {
+    if (!options.skipReactUpgrade && allDependencies['@types/react-dom']) {
         overrides['@types/react-dom'] = versionMapping['@types/react-dom'].version;
     }
     writeOverridesField(appPackageJson, packageManager, overrides);
@@ -356,8 +380,17 @@ async function runUpgrade(revision, options) {
         // Common IDE formatters would add a newline as well.
         os.EOL);
     (0, handle_package_1.runInstallation)(packageManager, { cwd });
-    for (const codemod of codemods) {
-        await (0, transform_1.runTransform)(codemod, cwd, { force: true, verbose });
+    // Opting out skips the lint migration as well as its dependency upgrades.
+    const selectedCodemods = codemods.filter((codemod) => !options.skipEslintUpgrade || codemod !== 'next-lint-to-eslint-cli');
+    if (selectedCodemods.length !== codemods.length) {
+        console.log('Skipping next-lint-to-eslint-cli. Complete any required lint migration manually before verification.');
+    }
+    for (const codemod of selectedCodemods) {
+        await (0, transform_1.runTransform)(codemod, cwd, {
+            force: true,
+            verbose,
+            nonInteractive,
+        });
     }
     // To reduce user-side burden of selecting which codemods to run as it needs additional
     // understanding of the codemods, we run all of the applicable codemods.
@@ -367,7 +400,14 @@ async function runUpgrade(revision, options) {
         // https://github.com/codemod-com/codemod/blob/c0cf00d13161a0ec0965b6cc6bc5d54076839cc8/apps/cli/src/flags.ts#L160
         // `--allow-dirty` is required because the upgrade above modified package.json
         // and the lockfile; the recipe refuses to run on a dirty tree otherwise.
-        (0, child_process_1.execSync)(`${execCommand} codemod@latest react/19/migration-recipe --no-interactive --allow-dirty`, { stdio: 'inherit' });
+        try {
+            (0, child_process_1.execSync)(`${execCommand} codemod@latest react/19/migration-recipe --no-interactive --allow-dirty`, { stdio: 'inherit' });
+        }
+        catch (error) {
+            // TODO: Remove this fallback once codemod publishes a Linux binary that
+            // supports the glibc versions used by our upgrade environments.
+            console.warn(new Error(`${picocolors_1.default.yellow('⚠')} The React 19 codemod could not run. Continue the upgrade and review the React 19 migration guide manually.`, { cause: error }));
+        }
     }
     if (shouldRunReactTypesCodemods) {
         // https://react.dev/blog/2024/04/25/react-19-upgrade-guide#typescript-changes
@@ -378,12 +418,12 @@ async function runUpgrade(revision, options) {
         });
     }
     console.log(); // new line
-    if (codemods.length > 0) {
+    if (selectedCodemods.length > 0) {
         console.log(`${picocolors_1.default.green('✔')} Codemods have been applied successfully.`);
     }
     try {
         if ((0, agents_md_1.refreshAgentRulesBlock)(cwd) === 'refreshed') {
-            console.log(`${picocolors_1.default.green('✔')} Refreshed the managed agent-rules block in AGENTS.md / CLAUDE.md to match the upgraded Next.js.`);
+            console.log(`${picocolors_1.default.green('✔')} Refreshed the managed agent-rules block in AGENTS.md to match the upgraded Next.js.`);
         }
     }
     catch {
@@ -489,7 +529,7 @@ async function suggestTurbopack(packageJson, targetNextVersion, nonInteractive)
     packageJson.scripts['dev'] =
         responseCustomDevScript.customDevScript || devScript;
 }
-async function suggestCodemods(initialNextVersion, targetNextVersion, nonInteractive) {
+async function suggestCodemods(initialNextVersion, targetNextVersion, nonInteractive, skipAdoption = false) {
     // example:
     // codemod version: 15.0.0-canary.45
     // 14.3             -> 15.0.0-canary.45: apply
@@ -508,7 +548,7 @@ async function suggestCodemods(initialNextVersion, targetNextVersion, nonInterac
     if (targetVersionIndex === -1) {
         targetVersionIndex = utils_1.TRANSFORMER_INQUIRER_CHOICES.length;
     }
-    const relevantCodemods = utils_1.TRANSFORMER_INQUIRER_CHOICES.slice(initialVersionIndex, targetVersionIndex);
+    const relevantCodemods = utils_1.TRANSFORMER_INQUIRER_CHOICES.slice(initialVersionIndex, targetVersionIndex).filter((codemod) => !skipAdoption || !codemod.adoption);
     if (relevantCodemods.length === 0) {
         return [];
     }

package/lib/__tests__/agents-md-e2e.test.js

@@ -11,7 +11,7 @@ const { getNextjsVersion } = require('../../lib/agents-md')
  * TRUE E2E TESTS
  * These tests invoke the actual CLI entry point (runAgentsMd),
  * simulating what happens when a user runs:
- * npx @next/codemod agents-md --version 15.0.0 --output CLAUDE.md
+ * npx @next/codemod agents-md --version 15.0.0 --output AGENTS.md
  */
 describe('agents-md e2e (CLI invocation)', () => {
   let testProjectDir
@@ -45,7 +45,7 @@ describe('agents-md e2e (CLI invocation)', () => {
     }
   })
 
-  it('creates CLAUDE.md and .next-docs directory when run with --version and --output', async () => {
+  it('creates AGENTS.md and .next-docs directory when run with --version and --output', async () => {
     // Create a minimal package.json (not required, but realistic)
     const packageJson = {
       name: 'test-project',
@@ -67,7 +67,7 @@ describe('agents-md e2e (CLI invocation)', () => {
       // Run the actual CLI command
       await runAgentsMd({
         version: '15.0.0',
-        output: 'CLAUDE.md',
+        output: 'AGENTS.md',
       })
 
       // Verify .next-docs directory was created and populated
@@ -83,20 +83,20 @@ describe('agents-md e2e (CLI invocation)', () => {
       )
       expect(mdxFiles.length).toBeGreaterThan(0)
 
-      // Verify CLAUDE.md was created
-      const claudeMdPath = path.join(testProjectDir, 'CLAUDE.md')
-      expect(fs.existsSync(claudeMdPath)).toBe(true)
+      // Verify AGENTS.md was created
+      const agentsMdPath = path.join(testProjectDir, 'AGENTS.md')
+      expect(fs.existsSync(agentsMdPath)).toBe(true)
 
-      const claudeMdContent = fs.readFileSync(claudeMdPath, 'utf-8')
+      const agentsMdContent = fs.readFileSync(agentsMdPath, 'utf-8')
 
       // Verify content structure
-      expect(claudeMdContent).toContain('<!-- NEXT-AGENTS-MD-START -->')
-      expect(claudeMdContent).toContain('<!-- NEXT-AGENTS-MD-END -->')
-      expect(claudeMdContent).toContain('[Next.js Docs Index]')
-      expect(claudeMdContent).toContain('root: ./.next-docs')
+      expect(agentsMdContent).toContain('<!-- NEXT-AGENTS-MD-START -->')
+      expect(agentsMdContent).toContain('<!-- NEXT-AGENTS-MD-END -->')
+      expect(agentsMdContent).toContain('[Next.js Docs Index]')
+      expect(agentsMdContent).toContain('root: ./.next-docs')
 
       // Verify paths are normalized to forward slashes (cross-platform)
-      const lines = claudeMdContent.split('|')
+      const lines = agentsMdContent.split('|')
       const pathLines = lines.filter((line) => line.includes(':'))
       pathLines.forEach((line) => {
         // Should not contain Windows backslashes in the output
@@ -117,19 +117,19 @@ describe('agents-md e2e (CLI invocation)', () => {
       const output = consoleOutput.join('\n')
       expect(output).toContain('Downloading Next.js')
       expect(output).toContain('15.0.0')
-      expect(output).toContain('CLAUDE.md')
+      expect(output).toContain('AGENTS.md')
     } finally {
       // Restore original directory
       process.chdir(originalCwd)
     }
   })
 
-  it('updates existing CLAUDE.md without losing content', async () => {
+  it('updates existing AGENTS.md without losing content', async () => {
     const originalCwd = process.cwd()
     process.chdir(testProjectDir)
 
     try {
-      // Create existing CLAUDE.md with custom content
+      // Create existing AGENTS.md with custom content
       const existingContent = `# My Project
 
 This is my project documentation.
@@ -138,31 +138,28 @@ This is my project documentation.
 - Feature 1
 - Feature 2
 `
-      fs.writeFileSync(
-        path.join(testProjectDir, 'CLAUDE.md'),
-        existingContent
-      )
+      fs.writeFileSync(path.join(testProjectDir, 'AGENTS.md'), existingContent)
 
       // Run CLI
       await runAgentsMd({
         version: '15.0.0',
-        output: 'CLAUDE.md',
+        output: 'AGENTS.md',
       })
 
       // Verify file was updated, not replaced
-      const claudeMdContent = fs.readFileSync(
-        path.join(testProjectDir, 'CLAUDE.md'),
+      const agentsMdContent = fs.readFileSync(
+        path.join(testProjectDir, 'AGENTS.md'),
         'utf-8'
       )
 
       // Original content should still be there
-      expect(claudeMdContent).toContain('# My Project')
-      expect(claudeMdContent).toContain('This is my project documentation.')
-      expect(claudeMdContent).toContain('## Features')
+      expect(agentsMdContent).toContain('# My Project')
+      expect(agentsMdContent).toContain('This is my project documentation.')
+      expect(agentsMdContent).toContain('## Features')
 
       // New index should be injected
-      expect(claudeMdContent).toContain('<!-- NEXT-AGENTS-MD-START -->')
-      expect(claudeMdContent).toContain('[Next.js Docs Index]')
+      expect(agentsMdContent).toContain('<!-- NEXT-AGENTS-MD-START -->')
+      expect(agentsMdContent).toContain('[Next.js Docs Index]')
     } finally {
       process.chdir(originalCwd)
     }
@@ -179,9 +176,8 @@ This is my project documentation.
         output: 'AGENTS.md',
       })
 
-      // Verify AGENTS.md was created (not CLAUDE.md)
+      // Verify AGENTS.md was created
       expect(fs.existsSync(path.join(testProjectDir, 'AGENTS.md'))).toBe(true)
-      expect(fs.existsSync(path.join(testProjectDir, 'CLAUDE.md'))).toBe(false)
 
       const agentsMdContent = fs.readFileSync(
         path.join(testProjectDir, 'AGENTS.md'),
@@ -216,11 +212,11 @@ This is my project documentation.
       // Run from subdirectory - should create files in CWD (subdirectory)
       await runAgentsMd({
         version: '15.0.0',
-        output: 'CLAUDE.md',
+        output: 'AGENTS.md',
       })
 
       // Verify files created in subdirectory
-      expect(fs.existsSync(path.join(subDir, 'CLAUDE.md'))).toBe(true)
+      expect(fs.existsSync(path.join(subDir, 'AGENTS.md'))).toBe(true)
       expect(fs.existsSync(path.join(subDir, '.next-docs'))).toBe(true)
     } finally {
       process.chdir(originalCwd)
@@ -234,20 +230,20 @@ This is my project documentation.
     try {
       await runAgentsMd({
         version: '15.0.0',
-        output: 'CLAUDE.md',
+        output: 'AGENTS.md',
       })
 
-      const claudeMdContent = fs.readFileSync(
-        path.join(testProjectDir, 'CLAUDE.md'),
+      const agentsMdContent = fs.readFileSync(
+        path.join(testProjectDir, 'AGENTS.md'),
         'utf-8'
       )
 
       // Extract the index content between markers
       const startMarker = '<!-- NEXT-AGENTS-MD-START -->'
       const endMarker = '<!-- NEXT-AGENTS-MD-END -->'
-      const startIdx = claudeMdContent.indexOf(startMarker) + startMarker.length
-      const endIdx = claudeMdContent.indexOf(endMarker)
-      const indexContent = claudeMdContent.slice(startIdx, endIdx)
+      const startIdx = agentsMdContent.indexOf(startMarker) + startMarker.length
+      const endIdx = agentsMdContent.indexOf(endMarker)
+      const indexContent = agentsMdContent.slice(startIdx, endIdx)
 
       // Parse the index (format: "dir:{file1,file2}|dir2:{file3}")
       const sections = indexContent.split('|').filter((s) => s.includes(':'))
@@ -276,7 +272,7 @@ This is my project documentation.
       // Use a known stable version
       await runAgentsMd({
         version: '14.2.0',
-        output: 'CLAUDE.md',
+        output: 'AGENTS.md',
       })
 
       // Verify docs were downloaded
@@ -331,7 +327,7 @@ This is my project documentation.
       process.chdir(testProjectDir)
 
       try {
-        await runAgentsMd({ output: 'CLAUDE.md' })
+        await runAgentsMd({ output: 'AGENTS.md' })
 
         // No .next-docs copy and no .gitignore entry for it
         expect(fs.existsSync(path.join(testProjectDir, '.next-docs'))).toBe(
@@ -341,14 +337,14 @@ This is my project documentation.
           false
         )
 
-        const claudeMdContent = fs.readFileSync(
-          path.join(testProjectDir, 'CLAUDE.md'),
+        const agentsMdContent = fs.readFileSync(
+          path.join(testProjectDir, 'AGENTS.md'),
           'utf-8'
         )
-        expect(claudeMdContent).toContain(
+        expect(agentsMdContent).toContain(
           'root: ./node_modules/next/dist/docs'
         )
-        expect(claudeMdContent).toContain('01-installation.md')
+        expect(agentsMdContent).toContain('01-installation.md')
 
         const output = consoleOutput.join('\n')
         expect(output).toContain('bundled with Next.js')
@@ -390,17 +386,17 @@ This is my project documentation.
       process.chdir(testProjectDir)
 
       try {
-        await runAgentsMd({ version: '15.0.0', output: 'CLAUDE.md' })
+        await runAgentsMd({ version: '15.0.0', output: 'AGENTS.md' })
 
         expect(fs.existsSync(path.join(testProjectDir, '.next-docs'))).toBe(
           true
         )
 
-        const claudeMdContent = fs.readFileSync(
-          path.join(testProjectDir, 'CLAUDE.md'),
+        const agentsMdContent = fs.readFileSync(
+          path.join(testProjectDir, 'AGENTS.md'),
           'utf-8'
         )
-        expect(claudeMdContent).toContain('root: ./.next-docs')
+        expect(agentsMdContent).toContain('root: ./.next-docs')
 
         const output = consoleOutput.join('\n')
         expect(output).toContain('Downloading')

package/lib/agents-md.js

@@ -3,7 +3,7 @@
  * agents-md: Generate Next.js documentation index for AI coding agents.
  *
  * Downloads docs from GitHub via git sparse-checkout, builds a compact
- * index of all doc files, and injects it into CLAUDE.md or AGENTS.md.
+ * index of all doc files, and injects it into AGENTS.md.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -16,8 +16,8 @@ exports.getBundledDocsLinkPath = getBundledDocsLinkPath;
 exports.pullDocs = pullDocs;
 exports.collectDocFiles = collectDocFiles;
 exports.buildDocTree = buildDocTree;
-exports.generateClaudeMdIndex = generateClaudeMdIndex;
-exports.injectIntoClaudeMd = injectIntoClaudeMd;
+exports.generateAgentsMdIndex = generateAgentsMdIndex;
+exports.injectIntoAgentsMd = injectIntoAgentsMd;
 exports.ensureGitignoreEntry = ensureGitignoreEntry;
 const execa_1 = __importDefault(require("execa"));
 const fs_1 = __importDefault(require("fs"));
@@ -26,8 +26,7 @@ const os_1 = __importDefault(require("os"));
 const AGENT_RULES_START_MARKER = '<!-- BEGIN:nextjs-agent-rules -->';
 /**
  * After an upgrade, refresh the managed agent-rules block in
- * AGENTS.md / CLAUDE.md so its content matches the Next.js version
- * that is now installed.
+ * AGENTS.md so its content matches the Next.js version that is now installed.
  *
  * Delegates to the installed package's own generator
  * (`next/dist/server/lib/generate-agent-files`), so the block text is
@@ -39,17 +38,14 @@ const AGENT_RULES_START_MARKER = '<!-- BEGIN:nextjs-agent-rules -->';
  * (< 16.3).
  */
 function refreshAgentRulesBlock(cwd) {
-    const hostsBlock = ['AGENTS.md', 'CLAUDE.md'].some((file) => {
-        try {
-            return fs_1.default
-                .readFileSync(path_1.default.join(cwd, file), 'utf-8')
-                .includes(AGENT_RULES_START_MARKER);
-        }
-        catch {
-            return false;
-        }
-    });
-    if (!hostsBlock)
+    let agentsMdContent;
+    try {
+        agentsMdContent = fs_1.default.readFileSync(path_1.default.join(cwd, 'AGENTS.md'), 'utf-8');
+    }
+    catch {
+        return 'skipped';
+    }
+    if (!agentsMdContent.includes(AGENT_RULES_START_MARKER))
         return 'skipped';
     let writeAgentFiles;
     try {
@@ -62,9 +58,7 @@ function refreshAgentRulesBlock(cwd) {
         return 'skipped';
     }
     const result = writeAgentFiles(cwd);
-    return result.agentsMd === 'updated' || result.claudeMd === 'updated'
-        ? 'refreshed'
-        : 'current';
+    return result.agentsMd === 'updated' ? 'refreshed' : 'current';
 }
 function getNextjsVersion(cwd) {
     try {
@@ -263,13 +257,13 @@ function buildDocTree(files) {
     }
     return sortedSections;
 }
-function generateClaudeMdIndex(data) {
+function generateAgentsMdIndex(data) {
     const { docsPath, sections, outputFile } = data;
     const parts = [];
     parts.push('[Next.js Docs Index]');
     parts.push(`root: ${docsPath}`);
     parts.push('STOP. What you remember about Next.js is WRONG for this project. Always search docs and read before any task.');
-    const targetFile = outputFile || 'CLAUDE.md';
+    const targetFile = outputFile || 'AGENTS.md';
     parts.push(`If docs missing, run this command first: npx @next/codemod agents-md --output ${targetFile}`);
     const allFiles = collectAllFilesFromSections(sections);
     const grouped = groupByDirectory(allFiles);
@@ -312,17 +306,17 @@ function hasExistingIndex(content) {
 function wrapWithMarkers(content) {
     return `${START_MARKER}${content}${END_MARKER}`;
 }
-function injectIntoClaudeMd(claudeMdContent, indexContent) {
+function injectIntoAgentsMd(agentsMdContent, indexContent) {
     const wrappedContent = wrapWithMarkers(indexContent);
-    if (hasExistingIndex(claudeMdContent)) {
-        const startIdx = claudeMdContent.indexOf(START_MARKER);
-        const endIdx = claudeMdContent.indexOf(END_MARKER) + END_MARKER.length;
-        return (claudeMdContent.slice(0, startIdx) +
+    if (hasExistingIndex(agentsMdContent)) {
+        const startIdx = agentsMdContent.indexOf(START_MARKER);
+        const endIdx = agentsMdContent.indexOf(END_MARKER) + END_MARKER.length;
+        return (agentsMdContent.slice(0, startIdx) +
             wrappedContent +
-            claudeMdContent.slice(endIdx));
+            agentsMdContent.slice(endIdx));
     }
-    const separator = claudeMdContent.endsWith('\n') ? '\n' : '\n\n';
-    return claudeMdContent + separator + wrappedContent + '\n';
+    const separator = agentsMdContent.endsWith('\n') ? '\n' : '\n\n';
+    return agentsMdContent + separator + wrappedContent + '\n';
 }
 const GITIGNORE_ENTRY = '.next-docs/';
 function ensureGitignoreEntry(cwd) {

package/lib/handle-package.js

@@ -13,6 +13,7 @@ exports.addPackageDependency = addPackageDependency;
 const find_up_1 = __importDefault(require("find-up"));
 const execa_1 = __importDefault(require("execa"));
 const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 /**
  * Get the full version string for the given package manager.
@@ -57,6 +58,17 @@ function getPnpmMajorVersion() {
 }
 function getPkgManager(baseDir) {
     try {
+        // The app's declared manager takes precedence over the command launcher.
+        const manifestPath = (0, node_path_1.join)(baseDir, 'package.json');
+        if ((0, node_fs_1.existsSync)(manifestPath)) {
+            const { packageManager } = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, 'utf8'));
+            const match = typeof packageManager === 'string'
+                ? packageManager.match(/^(npm|pnpm|yarn|bun)@/)
+                : null;
+            if (match) {
+                return match[1];
+            }
+        }
         const userAgent = process.env.npm_config_user_agent;
         if (userAgent) {
             if (userAgent.startsWith('yarn')) {

package/lib/utils.js

@@ -3,11 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TRANSFORMER_INQUIRER_CHOICES = void 0;
+exports.TRANSFORMER_INQUIRER_CHOICES = exports.NEXT_CODEMOD_IGNORE_ERROR_PREFIX = exports.NEXT_CODEMOD_ERROR_PREFIX = void 0;
 exports.checkGitStatus = checkGitStatus;
 exports.onCancel = onCancel;
 const picocolors_1 = require("picocolors");
 const is_git_clean_1 = __importDefault(require("is-git-clean"));
+exports.NEXT_CODEMOD_ERROR_PREFIX = '@next-codemod-error';
+exports.NEXT_CODEMOD_IGNORE_ERROR_PREFIX = '@next-codemod-ignore';
 function checkGitStatus(force) {
     let clean = false;
     let errorMessage = 'Unable to determine if git directory is clean';
@@ -136,11 +138,13 @@ exports.TRANSFORMER_INQUIRER_CHOICES = [
         title: 'Add `export const instant = false` to App Router pages and layouts to ease Cache Components adoption',
         value: 'cache-components-instant-false',
         version: '16.3.0',
+        adoption: true,
     },
     {
         title: "Remove `export const prefetch = 'partial'` Route Segment Config from App Router pages and layouts after enabling `partialPrefetching` globally",
         value: 'remove-partial-prefetch',
         version: '16.3.0',
+        adoption: true,
     },
 ];
 //# sourceMappingURL=utils.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next/codemod",
-  "version": "16.4.0-canary.8",
+  "version": "16.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/transforms/cache-components-instant-false.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = transformer;
 const parser_1 = require("../lib/parser");
+const utils_1 = require("../lib/utils");
 /**
  * Blanket-inserts `export const instant = false` into every App Router `page`,
  * `layout`, and `default` file so they're marked as allowed to block when
@@ -19,7 +20,7 @@ const parser_1 = require("../lib/parser");
  */
 function transformer(file, _api) {
     if (process.env.NODE_ENV !== 'test' &&
-        !/(^|[/\\])app[/\\].*?(page|layout|default)\.[^/\\]+$/.test(file.path)) {
+        !/(^|[/\\])app[/\\](?:.*[/\\])?(page|layout|default)\.[^/\\]+$/.test(file.path)) {
         return file.source;
     }
     const j = (0, parser_1.createParserFromPath)(file.path);
@@ -86,15 +87,16 @@ function transformer(file, _api) {
     if (hasInstantBinding) {
         return file.source;
     }
-    // Build `export const instant = false`. The two `//` comments above it
-    // (TODO + See:) are attached as leading comments on the declaration so
+    // Build `export const instant = false`. The ignore reason, removal condition,
+    // and guide link are attached as leading comments on the declaration so
     // recast prints them right above it.
-    const todoComment = j.commentLine(' TODO: Cache Components adoption. Refactor this route so this opt-out can be removed.', true, false);
+    const ignoreComment = j.commentLine(` ${utils_1.NEXT_CODEMOD_IGNORE_ERROR_PREFIX} Cache Components adoption: this segment temporarily allows blocking.`, true, false);
+    const removalComment = j.commentLine(' Remove this opt-out after verifying the segment passes validation without it.', true, false);
     const seeComment = j.commentLine(' See: https://nextjs.org/docs/app/guides/migrating-to-cache-components', true, false);
     const instantExport = j.exportNamedDeclaration(j.variableDeclaration('const', [
         j.variableDeclarator(j.identifier('instant'), j.booleanLiteral(false)),
     ]));
-    instantExport.comments = [todoComment, seeComment];
+    instantExport.comments = [ignoreComment, removalComment, seeComment];
     // Insert after the last top-level import, or at the top of the module
     // if there are no imports.
     const body = program.body;
@@ -110,14 +112,19 @@ function transformer(file, _api) {
         // No imports. Inserting at index 0 would steal any file-level leading
         // comments (e.g. `// @ts-nocheck`) from `body[0]` because recast
         // attributes them to whatever is first. Move those leading comments
-        // off `body[0]` onto the new export *before* its TODO/See: lines, so
+        // off `body[0]` onto the new export *before* its adoption comments, so
         // they print in their original position.
         const first = body[0];
         const allComments = (first.comments ?? []);
         const firstLeading = allComments.filter((c) => c.leading === true);
         if (firstLeading.length > 0) {
             first.comments = allComments.filter((c) => c.leading !== true);
-            instantExport.comments = [...firstLeading, todoComment, seeComment];
+            instantExport.comments = [
+                ...firstLeading,
+                ignoreComment,
+                removalComment,
+                seeComment,
+            ];
         }
         body.unshift(instantExport);
     }

package/transforms/lib/async-request-api/next-async-dynamic-api.js

@@ -3,7 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.transformDynamicAPI = transformDynamicAPI;
 const utils_1 = require("./utils");
 const parser_1 = require("../../../lib/parser");
-const DYNAMIC_IMPORT_WARN_COMMENT = ` @next-codemod-error The APIs under 'next/headers' are async now, need to be manually awaited. `;
+const utils_2 = require("../../../lib/utils");
+const DYNAMIC_IMPORT_WARN_COMMENT = ` ${utils_2.NEXT_CODEMOD_ERROR_PREFIX} The APIs under 'next/headers' are async now, need to be manually awaited. `;
 function findDynamicImportsAndComment(root, j) {
     let modified = false;
     // find all the dynamic imports of `next/headers`,
@@ -146,12 +147,12 @@ function transformDynamicAPI(source, _api, filePath) {
                             needsReactUseImport = true;
                         }
                         else {
-                            const casted = castTypesOrAddComment(j, path, originRequestApiName, root, filePath, insertedTypes, ` ${utils_1.NEXT_CODEMOD_ERROR_PREFIX} Manually await this call and refactor the function to be async `);
+                            const casted = castTypesOrAddComment(j, path, originRequestApiName, root, filePath, insertedTypes, ` ${utils_2.NEXT_CODEMOD_ERROR_PREFIX} Manually await this call and refactor the function to be async `);
                             modified ||= casted;
                         }
                     }
                     else {
-                        const casted = castTypesOrAddComment(j, path, originRequestApiName, root, filePath, insertedTypes, ` ${utils_1.NEXT_CODEMOD_ERROR_PREFIX} please manually await this call, codemod cannot transform due to undetermined async scope `);
+                        const casted = castTypesOrAddComment(j, path, originRequestApiName, root, filePath, insertedTypes, ` ${utils_2.NEXT_CODEMOD_ERROR_PREFIX} please manually await this call, codemod cannot transform due to undetermined async scope `);
                         modified ||= casted;
                     }
                 }
@@ -227,6 +228,18 @@ function castTypesOrAddComment(j, path, originRequestApiName, root, filePath, in
           e.g. `<path>` is cookies(), convert it to `(<path> as unknown as UnsafeUnwrappedCookies)`
         */
         const targetType = API_CAST_TYPE_MAP[originRequestApiName];
+        const repairComment = ` ${utils_2.NEXT_CODEMOD_ERROR_PREFIX} Await this API and update its callers; remove the temporary ${targetType} cast after repairing the migration. `;
+        const parentCast = path.parentPath?.node;
+        const outerCast = path.parentPath?.parentPath?.node;
+        if (j.TSAsExpression.check(parentCast) &&
+            j.TSAsExpression.check(outerCast) &&
+            j.TSTypeReference.check(outerCast.typeAnnotation) &&
+            j.Identifier.check(outerCast.typeAnnotation.typeName) &&
+            outerCast.typeAnnotation.typeName.name === targetType) {
+            // Re-parsing attaches the leading marker to the outer cast.
+            return (0, utils_1.insertCommentOnce)(outerCast, j, repairComment);
+        }
+        (0, utils_1.insertCommentOnce)(path.node, j, repairComment);
         const newCastExpression = j.tsAsExpression(j.tsAsExpression(path.node, j.tsUnknownKeyword()), j.tsTypeReference(j.identifier(targetType)));
         // Replace the original expression with the new cast expression,
         // also wrap () around the new cast expression.

package/transforms/lib/async-request-api/next-async-dynamic-prop.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.transformDynamicProps = transformDynamicProps;
 const utils_1 = require("./utils");
 const parser_1 = require("../../../lib/parser");
+const utils_2 = require("../../../lib/utils");
 const PAGE_PROPS = 'props';
 // Find all the member access of the prop, and await them
 // e.g. If there's argument `props`, find all the member access of props.<name>.
@@ -40,7 +41,7 @@ function awaitMemberAccessOfProp(propIdName, path, j) {
             parentScopeOfMemberAccess.node !== path.node) {
             // If it's not able to convert, add a comment to the prop access to warn the user
             // e.g. the parent scope is sync, await keyword can't be applied
-            const comment = ` ${utils_1.NEXT_CODEMOD_ERROR_PREFIX} '${propIdName}.${memberProperty.name}' is accessed without awaiting.`;
+            const comment = ` ${utils_2.NEXT_CODEMOD_ERROR_PREFIX} '${propIdName}.${memberProperty.name}' is accessed without awaiting.`;
             (0, utils_1.insertCommentOnce)(member, j, comment);
             return;
         }
@@ -121,7 +122,7 @@ function commentOnMatchedReExports(root, j) {
                         specifier.exported.name === 'default')) {
                     if (j.Literal.check(path.value.source)) {
                         const localName = specifier.local.name;
-                        const commentInserted = (0, utils_1.insertCommentOnce)(specifier, j, ` ${utils_1.NEXT_CODEMOD_ERROR_PREFIX} \`${localName}\` export is re-exported. Check if this component uses \`params\` or \`searchParams\``);
+                        const commentInserted = (0, utils_1.insertCommentOnce)(specifier, j, ` ${utils_2.NEXT_CODEMOD_ERROR_PREFIX} \`${localName}\` export is re-exported. Check if this component uses \`params\` or \`searchParams\``);
                         modified ||= commentInserted;
                     }
                     else if (path.value.source === null) {
@@ -134,7 +135,7 @@ function commentOnMatchedReExports(root, j) {
                             return importPath.value.specifiers.some((importSpecifier) => importSpecifier.local.name === localName);
                         });
                         if (importDeclaration.size() > 0) {
-                            const commentInserted = (0, utils_1.insertCommentOnce)(specifier, j, ` ${utils_1.NEXT_CODEMOD_ERROR_PREFIX} \`${localName}\` export is re-exported. Check if this component uses \`params\` or \`searchParams\``);
+                            const commentInserted = (0, utils_1.insertCommentOnce)(specifier, j, ` ${utils_2.NEXT_CODEMOD_ERROR_PREFIX} \`${localName}\` export is re-exported. Check if this component uses \`params\` or \`searchParams\``);
                             modified ||= commentInserted;
                         }
                     }
@@ -410,7 +411,7 @@ function transformDynamicProps(source, _api, filePath) {
                     // find the argument `currentParam`
                     const args = callExpression.value.arguments;
                     const propPassedAsArg = args.find((arg) => j.Identifier.check(arg) && arg.name === argName);
-                    const comment = ` ${utils_1.NEXT_CODEMOD_ERROR_PREFIX} '${argName}' is passed as an argument. Any asynchronous properties of 'props' must be awaited when accessed. `;
+                    const comment = ` ${utils_2.NEXT_CODEMOD_ERROR_PREFIX} '${argName}' is passed as an argument. Any asynchronous properties of 'props' must be awaited when accessed. `;
                     const inserted = (0, utils_1.insertCommentOnce)(propPassedAsArg, j, comment);
                     modified ||= inserted;
                 });
@@ -750,7 +751,7 @@ function commentSpreadProps(path, propsIdentifierName, j) {
     const objSpreadProperties = functionBodyCollection.find(j.SpreadElement, {
         argument: { name: propsIdentifierName },
     });
-    const comment = ` ${utils_1.NEXT_CODEMOD_ERROR_PREFIX} '${propsIdentifierName}' is used with spread syntax (...). Any asynchronous properties of '${propsIdentifierName}' must be awaited when accessed. `;
+    const comment = ` ${utils_2.NEXT_CODEMOD_ERROR_PREFIX} '${propsIdentifierName}' is used with spread syntax (...). Any asynchronous properties of '${propsIdentifierName}' must be awaited when accessed. `;
     // Add comment before it
     jsxSpreadProperties.forEach((spread) => {
         const inserted = (0, utils_1.insertCommentOnce)(spread.value, j, comment);

package/transforms/lib/async-request-api/utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isReactHookName = exports.TARGET_PROP_NAMES = exports.TARGET_NAMED_EXPORTS = exports.TARGET_ROUTE_EXPORTS = exports.NEXT_CODEMOD_ERROR_PREFIX = exports.NEXTJS_ENTRY_FILES = void 0;
+exports.isReactHookName = exports.TARGET_PROP_NAMES = exports.TARGET_NAMED_EXPORTS = exports.TARGET_ROUTE_EXPORTS = exports.NEXTJS_ENTRY_FILES = void 0;
 exports.isFunctionType = isFunctionType;
 exports.isMatchedFunctionExported = isMatchedFunctionExported;
 exports.determineClientDirective = determineClientDirective;
@@ -19,8 +19,7 @@ exports.containsReactHooksCallExpressions = containsReactHooksCallExpressions;
 exports.isParentUseCallExpression = isParentUseCallExpression;
 exports.isParentPromiseAllCallExpression = isParentPromiseAllCallExpression;
 exports.NEXTJS_ENTRY_FILES = /([\\/]|^)(page|layout|route|default)\.(t|j)sx?$/;
-exports.NEXT_CODEMOD_ERROR_PREFIX = '@next-codemod-error';
-const NEXT_CODEMOD_IGNORE_ERROR_PREFIX = '@next-codemod-ignore';
+const utils_1 = require("../../../lib/utils");
 exports.TARGET_ROUTE_EXPORTS = new Set([
     'GET',
     'POST',
@@ -332,13 +331,13 @@ function wrapParentheseIfNeeded(hasChainAccess, j, expression) {
 function existsComment(comments, comment) {
     const isCodemodErrorComment = comment
         .trim()
-        .startsWith(exports.NEXT_CODEMOD_ERROR_PREFIX);
+        .startsWith(utils_1.NEXT_CODEMOD_ERROR_PREFIX);
     let hasIgnoreComment = false;
     let hasComment = false;
     if (comments) {
         comments.forEach((commentNode) => {
             const currentComment = commentNode.value;
-            if (currentComment.trim().startsWith(NEXT_CODEMOD_IGNORE_ERROR_PREFIX)) {
+            if (currentComment.trim().startsWith(utils_1.NEXT_CODEMOD_IGNORE_ERROR_PREFIX)) {
                 hasIgnoreComment = true;
             }
             if (currentComment === comment) {

package/transforms/new-link.js

@@ -4,7 +4,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = transformer;
 const parser_1 = require("../lib/parser");
-const utils_1 = require("./lib/async-request-api/utils");
+const utils_1 = require("../lib/utils");
 function transformer(file, _api) {
     const j = (0, parser_1.createParserFromPath)(file.path);
     const $j = j(file.source);

package/transforms/next-lint-to-eslint-cli.js

@@ -836,6 +836,13 @@ function transformer(files, options = {}) {
         console.error('Error: package.json not found in the specified directory');
         return;
     }
+    const packageJsonContent = (0, node_fs_1.readFileSync)(packageJsonPath, 'utf8');
+    const packageJson = JSON.parse(packageJsonContent);
+    const usesNextLint = Object.values(packageJson.scripts || {}).some((script) => typeof script === 'string' && script.includes('next lint'));
+    if (!usesNextLint) {
+        console.log('Skipping migration: no next lint script found in package.json.');
+        return;
+    }
     const isTypeScript = detectTypeScript(projectRoot);
     console.log('Migrating from next lint to the ESLint CLI...');
     // Check for existing ESLint config
@@ -897,7 +904,6 @@ function transformer(files, options = {}) {
             console.log('   Please manually ensure your ESLint config includes the Next.js configurations');
         }
     }
-    const packageJsonContent = (0, node_fs_1.readFileSync)(packageJsonPath, 'utf8');
     const result = updatePackageJsonScripts(packageJsonContent);
     if (result.updated) {
         try {