@next/codemod 16.3.0-canary.8 → 16.3.0-canary.80

package/bin/agents-md.js

@@ -59,8 +59,17 @@ async function runAgentsMd(options) {
         targetFile = promptedOptions.targetFile;
     }
     const claudeMdPath = path_1.default.join(cwd, targetFile);
-    const docsPath = path_1.default.join(cwd, DOCS_DIR_NAME);
-    const docsLinkPath = `./${DOCS_DIR_NAME}`;
+    // 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.
+    const bundledDocs = (0, agents_md_1.getBundledDocsInfo)(cwd);
+    const useBundledDocs = bundledDocs !== null && bundledDocs.version === nextjsVersion;
+    const docsPath = useBundledDocs
+        ? bundledDocs.docsPath
+        : path_1.default.join(cwd, DOCS_DIR_NAME);
+    const docsLinkPath = useBundledDocs
+        ? (0, agents_md_1.getBundledDocsLinkPath)(cwd, bundledDocs.docsPath)
+        : `./${DOCS_DIR_NAME}`;
     let sizeBefore = 0;
     let isNewFile = true;
     let existingContent = '';
@@ -69,14 +78,19 @@ async function runAgentsMd(options) {
         sizeBefore = Buffer.byteLength(existingContent, 'utf-8');
         isNewFile = false;
     }
-    console.log(`\nDownloading Next.js ${picocolors_1.default.cyan(nextjsVersion)} documentation to ${picocolors_1.default.cyan(DOCS_DIR_NAME)}...`);
-    const pullResult = await (0, agents_md_1.pullDocs)({
-        cwd,
-        version: nextjsVersion,
-        docsDir: docsPath,
-    });
-    if (!pullResult.success) {
-        throw new shared_1.BadInput(`Failed to pull docs: ${pullResult.error}`);
+    if (useBundledDocs) {
+        console.log(`\nUsing the docs bundled with Next.js ${picocolors_1.default.cyan(nextjsVersion)} at ${picocolors_1.default.cyan(docsLinkPath)} (no download needed).`);
+    }
+    else {
+        console.log(`\nDownloading Next.js ${picocolors_1.default.cyan(nextjsVersion)} documentation to ${picocolors_1.default.cyan(DOCS_DIR_NAME)}...`);
+        const pullResult = await (0, agents_md_1.pullDocs)({
+            cwd,
+            version: nextjsVersion,
+            docsDir: docsPath,
+        });
+        if (!pullResult.success) {
+            throw new shared_1.BadInput(`Failed to pull docs: ${pullResult.error}`);
+        }
     }
     const docFiles = (0, agents_md_1.collectDocFiles)(docsPath);
     const sections = (0, agents_md_1.buildDocTree)(docFiles);
@@ -88,13 +102,15 @@ async function runAgentsMd(options) {
     const newContent = (0, agents_md_1.injectIntoClaudeMd)(existingContent, indexContent);
     fs_1.default.writeFileSync(claudeMdPath, newContent, 'utf-8');
     const sizeAfter = Buffer.byteLength(newContent, 'utf-8');
-    const gitignoreResult = (0, agents_md_1.ensureGitignoreEntry)(cwd);
+    // .next-docs only exists on the download path; bundled docs live in
+    // node_modules, which is already ignored.
+    const gitignoreResult = useBundledDocs ? null : (0, agents_md_1.ensureGitignoreEntry)(cwd);
     const action = isNewFile ? 'Created' : 'Updated';
     const sizeInfo = isNewFile
         ? formatSize(sizeAfter)
         : `${formatSize(sizeBefore)} → ${formatSize(sizeAfter)}`;
     console.log(`${picocolors_1.default.green('✓')} ${action} ${picocolors_1.default.bold(targetFile)} (${sizeInfo})`);
-    if (gitignoreResult.updated) {
+    if (gitignoreResult?.updated) {
         console.log(`${picocolors_1.default.green('✓')} Added ${picocolors_1.default.bold(DOCS_DIR_NAME)} to .gitignore`);
     }
     console.log('');

package/bin/next-codemod.js

@@ -43,6 +43,7 @@ program
     .argument('[revision]', 'Specify the upgrade type ("patch", "minor", "major"), an NPM dist tag (e.g. "latest", "canary", "rc"), or an exact version (e.g. "15.0.0"). Defaults to "minor".')
     .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)
     .action(async (revision, options) => {
     try {
         await (0, upgrade_1.runUpgrade)(revision, options);

package/bin/upgrade.js

@@ -114,6 +114,10 @@ function resolveSemanticRevision(revision, installedVersion) {
 }
 async function runUpgrade(revision, options) {
     const { verbose } = options;
+    const nonInteractive = options.yes === true || !process.stdin.isTTY;
+    if (nonInteractive) {
+        console.log(`  Running in non-interactive mode. Every prompt will accept its default.`);
+    }
     const appPackageJsonPath = path_1.default.resolve(cwd, 'package.json');
     let appPackageJson = JSON.parse(fs_1.default.readFileSync(appPackageJsonPath, 'utf8'));
     const installedNextVersion = getInstalledNextVersion();
@@ -189,18 +193,24 @@ async function runUpgrade(revision, options) {
         // 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.
         !isPureAppRouter) {
-        const shouldStayOnReact18Res = await (0, prompts_1.default)({
-            type: 'confirm',
-            name: 'shouldStayOnReact18',
-            message: `Do you prefer to stay on React 18?` +
-                (isMixedApp
-                    ? " Since you're using both pages/ and app/, we recommend upgrading React to use a consistent version throughout your app."
-                    : ''),
-            initial: false,
-            active: 'Yes',
-            inactive: 'No',
-        }, { onCancel: utils_1.onCancel });
-        shouldStayOnReact18 = shouldStayOnReact18Res.shouldStayOnReact18;
+        if (nonInteractive) {
+            // Default: upgrade React past 18.
+            shouldStayOnReact18 = false;
+        }
+        else {
+            const shouldStayOnReact18Res = await (0, prompts_1.default)({
+                type: 'confirm',
+                name: 'shouldStayOnReact18',
+                message: `Do you prefer to stay on React 18?` +
+                    (isMixedApp
+                        ? " Since you're using both pages/ and app/, we recommend upgrading React to use a consistent version throughout your app."
+                        : ''),
+                initial: false,
+                active: 'Yes',
+                inactive: 'No',
+            }, { onCancel: utils_1.onCancel });
+            shouldStayOnReact18 = shouldStayOnReact18Res.shouldStayOnReact18;
+        }
     }
     // We're resolving a specific version here to avoid including "ugly" version queries
     // in the manifest.
@@ -212,9 +222,9 @@ async function runUpgrade(revision, options) {
         : 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);
+        await suggestTurbopack(appPackageJson, targetNextVersion, nonInteractive);
     }
-    const codemods = await suggestCodemods(installedNextVersion, targetNextVersion);
+    const codemods = await suggestCodemods(installedNextVersion, targetNextVersion, nonInteractive);
     const packageManager = (0, handle_package_1.getPkgManager)(cwd);
     let shouldRunReactCodemods = false;
     let shouldRunReactTypesCodemods = false;
@@ -223,8 +233,9 @@ async function runUpgrade(revision, options) {
     if (!shouldStayOnReact18 &&
         (0, semver_1.compare)(targetReactVersion, '19.0.0-0') >= 0 &&
         (0, semver_1.compare)(installedReactVersion, '19.0.0-0') < 0) {
-        shouldRunReactCodemods = await suggestReactCodemods();
-        shouldRunReactTypesCodemods = await suggestReactTypesCodemods();
+        shouldRunReactCodemods = await suggestReactCodemods(nonInteractive);
+        shouldRunReactTypesCodemods =
+            await suggestReactTypesCodemods(nonInteractive);
         execCommand = getNpxCommand(packageManager);
     }
     fs_1.default.writeFileSync(appPackageJsonPath, JSON.stringify(appPackageJson, null, 2));
@@ -284,6 +295,37 @@ async function runUpgrade(revision, options) {
             };
         }
     }
+    // Bump `eslint` alongside `eslint-config-next` so the install doesn't fail
+    // on a peer-dep mismatch. e.g. `eslint-config-next@16.x` requires
+    // `eslint@>=9`, but a project upgrading from Next 15 will still have
+    // `eslint@^8` from create-next-app. Skip silently if anything goes wrong;
+    // the worst case is the user hits the same peer-dep error they would have
+    // without this bump.
+    //
+    // 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']) {
+        try {
+            const eslintConfigNextPeerDepsJSON = (0, child_process_1.execSync)(`npm --silent view "eslint-config-next@${targetNextVersion}" peerDependencies --json`, { encoding: 'utf-8' });
+            const eslintConfigNextPeerDeps = eslintConfigNextPeerDepsJSON.trim() === ''
+                ? {}
+                : JSON.parse(eslintConfigNextPeerDepsJSON);
+            const eslintRange = eslintConfigNextPeerDeps?.eslint;
+            if (eslintRange) {
+                const targetEslintVersion = await loadHighestNPMVersionMatching(`eslint@${eslintRange}`);
+                versionMapping['eslint'] = {
+                    version: targetEslintVersion,
+                    required: false,
+                };
+            }
+        }
+        catch (e) {
+            if (verbose) {
+                console.warn(`  Could not determine eslint peer range from eslint-config-next@${targetNextVersion}. Leaving eslint version alone.`, e);
+            }
+        }
+    }
     // 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 = {};
@@ -320,10 +362,11 @@ async function runUpgrade(revision, options) {
     // understanding of the codemods, we run all of the applicable codemods.
     if (shouldRunReactCodemods) {
         // https://react.dev/blog/2024/04/25/react-19-upgrade-guide#run-all-react-19-codemods
-        (0, child_process_1.execSync)(
         // `--no-interactive` skips the interactive prompt that asks for confirmation
         // https://github.com/codemod-com/codemod/blob/c0cf00d13161a0ec0965b6cc6bc5d54076839cc8/apps/cli/src/flags.ts#L160
-        `${execCommand} codemod@latest react/19/migration-recipe --no-interactive`, { stdio: 'inherit' });
+        // `--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' });
     }
     if (shouldRunReactTypesCodemods) {
         // https://react.dev/blog/2024/04/25/react-19-upgrade-guide#typescript-changes
@@ -383,7 +426,7 @@ function isUsingAppDir(projectPath) {
  * 3. Otherwise, we ask the user to manually add `--turbopack` to their dev command,
  *    showing the current dev command as the initial value.
  */
-async function suggestTurbopack(packageJson, targetNextVersion) {
+async function suggestTurbopack(packageJson, targetNextVersion, nonInteractive) {
     const devScript = packageJson.scripts?.['dev'];
     // Turbopack flag was changed from `--turbo` to `--turbopack` in v15.0.1-canary.3
     // PR: https://github.com/vercel/next.js/pull/71657
@@ -406,19 +449,28 @@ async function suggestTurbopack(packageJson, targetNextVersion) {
             }
             return;
         }
-        const responseTurbopack = await (0, prompts_1.default)({
-            type: 'confirm',
-            name: 'enable',
-            message: `Enable Turbopack for ${picocolors_1.default.bold('next dev')}?`,
-            initial: true,
-        }, { onCancel: utils_1.onCancel });
-        if (!responseTurbopack.enable) {
+        let enable = true;
+        if (!nonInteractive) {
+            const responseTurbopack = await (0, prompts_1.default)({
+                type: 'confirm',
+                name: 'enable',
+                message: `Enable Turbopack for ${picocolors_1.default.bold('next dev')}?`,
+                initial: true,
+            }, { onCancel: utils_1.onCancel });
+            enable = responseTurbopack.enable;
+        }
+        if (!enable) {
             return;
         }
         packageJson.scripts['dev'] = devScript.replace('next dev', `next dev ${turboPackFlag}`);
         return;
     }
     console.log(`${picocolors_1.default.yellow('⚠')} Could not find "${picocolors_1.default.bold('next dev')}" in your dev script.`);
+    if (nonInteractive) {
+        // Without a TTY we can't ask the user for a replacement script.
+        // Keep the existing dev script untouched.
+        return;
+    }
     const responseCustomDevScript = await (0, prompts_1.default)({
         type: 'text',
         name: 'customDevScript',
@@ -428,7 +480,7 @@ async function suggestTurbopack(packageJson, targetNextVersion) {
     packageJson.scripts['dev'] =
         responseCustomDevScript.customDevScript || devScript;
 }
-async function suggestCodemods(initialNextVersion, targetNextVersion) {
+async function suggestCodemods(initialNextVersion, targetNextVersion, nonInteractive) {
     // example:
     // codemod version: 15.0.0-canary.45
     // 14.3             -> 15.0.0-canary.45: apply
@@ -451,6 +503,13 @@ async function suggestCodemods(initialNextVersion, targetNextVersion) {
     if (relevantCodemods.length === 0) {
         return [];
     }
+    if (nonInteractive) {
+        // Default: apply every recommended codemod, matching `selected: true` below.
+        const all = relevantCodemods.map(({ value }) => value);
+        console.log(`  Applying all ${picocolors_1.default.blue('codemods')} recommended for your upgrade:\n` +
+            all.map((value) => `    - ${value}`).join('\n'));
+        return all;
+    }
     const { codemods } = await (0, prompts_1.default)({
         type: 'multiselect',
         name: 'codemods',
@@ -466,7 +525,10 @@ async function suggestCodemods(initialNextVersion, targetNextVersion) {
     }, { onCancel: utils_1.onCancel });
     return codemods;
 }
-async function suggestReactCodemods() {
+async function suggestReactCodemods(nonInteractive) {
+    if (nonInteractive) {
+        return true;
+    }
     const { runReactCodemod } = await (0, prompts_1.default)({
         type: 'confirm',
         name: 'runReactCodemod',
@@ -475,7 +537,10 @@ async function suggestReactCodemods() {
     }, { onCancel: utils_1.onCancel });
     return runReactCodemod;
 }
-async function suggestReactTypesCodemods() {
+async function suggestReactTypesCodemods(nonInteractive) {
+    if (nonInteractive) {
+        return true;
+    }
     const { runReactTypesCodemod } = await (0, prompts_1.default)({
         type: 'confirm',
         name: 'runReactTypesCodemod',
@@ -500,6 +565,16 @@ function writeOverridesField(packageJson, packageManager, overrides) {
         }
     }
     else if (packageManager === 'pnpm') {
+        // pnpm v11 silently ignores `pnpm.overrides` in package.json. The
+        // canonical location moved to `pnpm-workspace.yaml#overrides`.
+        // See https://pnpm.io/settings and https://github.com/pnpm/pnpm/issues/11536.
+        // When the version cannot be detected, assume the current (v11+) layout
+        // since that's the surface where silently-dropped overrides hurt most.
+        const pnpmMajorVersion = (0, handle_package_1.getPnpmMajorVersion)();
+        if (pnpmMajorVersion === null || pnpmMajorVersion >= 11) {
+            writePnpmWorkspaceOverrides(overrides);
+            return;
+        }
         // pnpm supports pnpm.overrides and pnpm.resolutions
         if (packageJson.resolutions) {
             for (const [key, value] of entries) {
@@ -545,6 +620,28 @@ function writeOverridesField(packageJson, packageManager, overrides) {
         }
     }
 }
+function writePnpmWorkspaceOverrides(overrides) {
+    // Deferred require so `js-yaml` is only loaded when we hit the pnpm v11+
+    // branch (i.e. not for npm/yarn/bun/pnpm-v10 upgrades). The package is CJS,
+    // so a sync `require()` keeps this function synchronous.
+    const yaml = require('js-yaml');
+    const filePath = path_1.default.join(cwd, 'pnpm-workspace.yaml');
+    let doc = {};
+    if (fs_1.default.existsSync(filePath)) {
+        const existing = fs_1.default.readFileSync(filePath, 'utf8');
+        const parsed = yaml.load(existing);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            doc = parsed;
+        }
+    }
+    if (!doc.overrides || typeof doc.overrides !== 'object') {
+        doc.overrides = {};
+    }
+    for (const [key, value] of Object.entries(overrides)) {
+        doc.overrides[key] = value;
+    }
+    fs_1.default.writeFileSync(filePath, yaml.dump(doc));
+}
 function warnDependenciesOutOfRange(appPackageJson, versionMapping) {
     const allDirectDependencies = {
         ...appPackageJson.dependencies,

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

@@ -293,6 +293,123 @@ This is my project documentation.
     }
   }, 30000) // Increase timeout for git clone
 
+  describe('bundled docs (Next.js >= 16.2.0)', () => {
+    // Simulate an install of a Next.js version that ships docs inside the
+    // published package at node_modules/next/dist/docs.
+    function setupBundledNext(projectDir, version) {
+      const nextDir = path.join(projectDir, 'node_modules', 'next')
+      const gettingStartedDir = path.join(
+        nextDir,
+        'dist',
+        'docs',
+        '01-app',
+        '01-getting-started'
+      )
+      fs.mkdirSync(gettingStartedDir, { recursive: true })
+      fs.writeFileSync(
+        path.join(nextDir, 'package.json'),
+        JSON.stringify({ name: 'next', version })
+      )
+      fs.writeFileSync(
+        path.join(nextDir, 'dist', 'docs', 'index.md'),
+        '# Next.js Docs'
+      )
+      fs.writeFileSync(
+        path.join(gettingStartedDir, '01-installation.md'),
+        '# Installation'
+      )
+      fs.writeFileSync(
+        path.join(gettingStartedDir, '02-project-structure.md'),
+        '# Project Structure'
+      )
+    }
+
+    it('indexes bundled docs instead of downloading when installed Next.js ships them', async () => {
+      setupBundledNext(testProjectDir, '16.2.0')
+
+      const originalCwd = process.cwd()
+      process.chdir(testProjectDir)
+
+      try {
+        await runAgentsMd({ output: 'CLAUDE.md' })
+
+        // No .next-docs copy and no .gitignore entry for it
+        expect(fs.existsSync(path.join(testProjectDir, '.next-docs'))).toBe(
+          false
+        )
+        expect(fs.existsSync(path.join(testProjectDir, '.gitignore'))).toBe(
+          false
+        )
+
+        const claudeMdContent = fs.readFileSync(
+          path.join(testProjectDir, 'CLAUDE.md'),
+          'utf-8'
+        )
+        expect(claudeMdContent).toContain(
+          'root: ./node_modules/next/dist/docs'
+        )
+        expect(claudeMdContent).toContain('01-installation.md')
+
+        const output = consoleOutput.join('\n')
+        expect(output).toContain('bundled with Next.js')
+        expect(output).not.toContain('Downloading')
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it('uses bundled docs when --version matches the installed version', async () => {
+      setupBundledNext(testProjectDir, '16.2.0')
+
+      const originalCwd = process.cwd()
+      process.chdir(testProjectDir)
+
+      try {
+        await runAgentsMd({ version: '16.2.0', output: 'AGENTS.md' })
+
+        expect(fs.existsSync(path.join(testProjectDir, '.next-docs'))).toBe(
+          false
+        )
+
+        const agentsMdContent = fs.readFileSync(
+          path.join(testProjectDir, 'AGENTS.md'),
+          'utf-8'
+        )
+        expect(agentsMdContent).toContain(
+          'root: ./node_modules/next/dist/docs'
+        )
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it('falls back to downloading when --version differs from the installed version', async () => {
+      setupBundledNext(testProjectDir, '16.2.0')
+
+      const originalCwd = process.cwd()
+      process.chdir(testProjectDir)
+
+      try {
+        await runAgentsMd({ version: '15.0.0', output: 'CLAUDE.md' })
+
+        expect(fs.existsSync(path.join(testProjectDir, '.next-docs'))).toBe(
+          true
+        )
+
+        const claudeMdContent = fs.readFileSync(
+          path.join(testProjectDir, 'CLAUDE.md'),
+          'utf-8'
+        )
+        expect(claudeMdContent).toContain('root: ./.next-docs')
+
+        const output = consoleOutput.join('\n')
+        expect(output).toContain('Downloading')
+      } finally {
+        process.chdir(originalCwd)
+      }
+    }, 30000) // Increase timeout for git clone
+  })
+
   describe('getNextjsVersion', () => {
     const fixturesDir = path.join(__dirname, 'fixtures/agents-md')
 

package/lib/agents-md.js

@@ -10,6 +10,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNextjsVersion = getNextjsVersion;
+exports.getBundledDocsInfo = getBundledDocsInfo;
+exports.getBundledDocsLinkPath = getBundledDocsLinkPath;
 exports.pullDocs = pullDocs;
 exports.collectDocFiles = collectDocFiles;
 exports.buildDocTree = buildDocTree;
@@ -45,6 +47,36 @@ function getNextjsVersion(cwd) {
         };
     }
 }
+/**
+ * Next.js ships its documentation inside the published package (at
+ * `dist/docs`) since 16.2.0. When the install resolved from `cwd` has
+ * bundled docs, the index can point at them directly instead of
+ * downloading a copy into `.next-docs`.
+ */
+function getBundledDocsInfo(cwd) {
+    try {
+        const nextPkgPath = require.resolve('next/package.json', { paths: [cwd] });
+        const pkg = JSON.parse(fs_1.default.readFileSync(nextPkgPath, 'utf-8'));
+        const docsPath = path_1.default.join(path_1.default.dirname(nextPkgPath), 'dist', 'docs');
+        if (!pkg.version || collectDocFiles(docsPath).length === 0) {
+            return null;
+        }
+        return { docsPath, version: pkg.version };
+    }
+    catch {
+        return null;
+    }
+}
+function getBundledDocsLinkPath(cwd, docsPath) {
+    // Prefer the conventional path when it resolves from the project
+    // (covers hoisted installs; pnpm exposes next via a node_modules symlink).
+    const conventional = path_1.default.join(cwd, 'node_modules', 'next', 'dist', 'docs');
+    if (fs_1.default.existsSync(conventional)) {
+        return './node_modules/next/dist/docs';
+    }
+    const relative = path_1.default.relative(cwd, docsPath).replace(/\\/g, '/');
+    return relative.startsWith('.') ? relative : `./${relative}`;
+}
 function versionToGitHubTag(version) {
     return version.startsWith('v') ? version : `v${version}`;
 }

package/lib/handle-package.js

@@ -3,6 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPackageManagerVersion = getPackageManagerVersion;
+exports.getPnpmMajorVersion = getPnpmMajorVersion;
 exports.getPkgManager = getPkgManager;
 exports.uninstallPackage = uninstallPackage;
 exports.installPackages = installPackages;
@@ -10,7 +12,49 @@ exports.runInstallation = runInstallation;
 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_path_1 = require("node:path");
+/**
+ * Get the full version string for the given package manager.
+ *
+ * First tries to parse from `npm_config_user_agent` (e.g., "pnpm/9.13.2 npm/? ..."),
+ * then falls back to spawning `<packageManager> --version`.
+ *
+ * Returns null if unable to determine the version.
+ *
+ * Mirrors `packages/create-next-app/helpers/get-pkg-manager.ts`.
+ */
+function getPackageManagerVersion(packageManager) {
+    const userAgent = process.env.npm_config_user_agent || '';
+    const userAgentMatch = userAgent.match(new RegExp(`${packageManager}/([\\d.]+[\\w.-]*)`));
+    if (userAgentMatch) {
+        return userAgentMatch[1];
+    }
+    try {
+        const version = (0, node_child_process_1.execSync)(`${packageManager} --version`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        }).trim();
+        if (/^\d+\.\d+\.\d+/.test(version)) {
+            return version;
+        }
+    }
+    catch {
+        // package manager not available or failed to run
+    }
+    return null;
+}
+/**
+ * Get the major version of pnpm being used.
+ * Returns null if unable to determine the version.
+ */
+function getPnpmMajorVersion() {
+    const version = getPackageManagerVersion('pnpm');
+    if (!version)
+        return null;
+    const major = parseInt(version.split('.')[0], 10);
+    return Number.isNaN(major) ? null : major;
+}
 function getPkgManager(baseDir) {
     try {
         const lockFile = find_up_1.default.sync([

package/lib/utils.js

@@ -132,5 +132,10 @@ exports.TRANSFORMER_INQUIRER_CHOICES = [
         value: 'remove-experimental-ppr',
         version: '16.0.0-canary.11',
     },
+    {
+        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',
+    },
 ];
 //# sourceMappingURL=utils.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next/codemod",
-  "version": "16.3.0-canary.8",
+  "version": "16.3.0-canary.80",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,6 +14,7 @@
     "find-up": "4.1.0",
     "globby": "11.0.1",
     "is-git-clean": "1.1.0",
+    "js-yaml": "4.2.0",
     "jscodeshift": "17.0.0",
     "picocolors": "1.0.0",
     "prompts": "2.4.2",
@@ -27,19 +28,19 @@
     "lib/**/*.js",
     "lib/cra-to-next/gitignore"
   ],
-  "scripts": {
-    "build": "pnpm tsc -d -p tsconfig.json",
-    "prepublishOnly": "cd ../../ && turbo run build",
-    "dev": "pnpm tsc -d -w -p tsconfig.json",
-    "test": "jest",
-    "test:upgrade-fixture": "./scripts/test-upgrade-fixture.sh"
-  },
   "bin": "./bin/next-codemod.js",
   "devDependencies": {
     "@types/find-up": "4.0.0",
+    "@types/js-yaml": "4.0.9",
     "@types/jscodeshift": "0.11.0",
     "@types/prompts": "2.4.2",
     "@types/semver": "7.3.1",
     "typescript": "6.0.2"
+  },
+  "scripts": {
+    "build": "pnpm tsc -d -p tsconfig.json",
+    "dev": "pnpm tsc -d -w -p tsconfig.json",
+    "test": "jest",
+    "test:upgrade-fixture": "./scripts/test-upgrade-fixture.sh"
   }
-}
+}

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

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = transformer;
+const parser_1 = require("../lib/parser");
+/**
+ * Blanket-inserts `export const instant = false` into every App Router `page`,
+ * `layout`, and `default` file so they're marked as allowed to block when
+ * `cacheComponents` is enabled. Each opt-out is meant to be walked back, one
+ * route at a time, using the companion adoption skill.
+ *
+ * - Skips files that already declare or export `instant` in any form (never
+ *   overrides existing config or appends a duplicate binding).
+ * - Skips Client/Server Component modules (`"use client"` / `"use server"`):
+ *   `instant` is a Server Component route segment config, so exporting it from
+ *   those modules is a build error.
+ * - Targets `page` / `layout` / `default` only (not `route` — `instant` does
+ *   not apply to route handlers). `default.tsx` is the parallel-route fallback,
+ *   a server segment that accepts route segment config like the other two.
+ */
+function transformer(file, _api) {
+    if (process.env.NODE_ENV !== 'test' &&
+        !/(^|[/\\])app[/\\].*?(page|layout|default)\.[^/\\]+$/.test(file.path)) {
+        return file.source;
+    }
+    const j = (0, parser_1.createParserFromPath)(file.path);
+    const root = j(file.source);
+    // Bail on Client/Server Component modules. `instant` is a Server Component
+    // route segment config; exporting it from a `"use client"` (or `"use server"`)
+    // module fails the build. Parsers represent the directive either in
+    // `program.directives` or as a leading string-literal `ExpressionStatement`.
+    const program = root.get().node.program;
+    const isClientOrServerDirective = (value) => value === 'use client' || value === 'use server';
+    let hasModuleDirective = (program.directives ?? []).some((d) => isClientOrServerDirective(d?.value?.value));
+    if (!hasModuleDirective) {
+        for (const node of program.body) {
+            if (node.type !== 'ExpressionStatement' ||
+                (node.expression?.type !== 'StringLiteral' &&
+                    node.expression?.type !== 'Literal')) {
+                // Directives must lead the module; stop at the first non-directive.
+                break;
+            }
+            if (isClientOrServerDirective(node.expression.value)) {
+                hasModuleDirective = true;
+                break;
+            }
+        }
+    }
+    if (hasModuleDirective) {
+        return file.source;
+    }
+    // Bail if `instant` already exists in any form, so we never append a
+    // duplicate declaration (which would be a `SyntaxError`). This covers:
+    //   export const instant = ...
+    //   export const a = 1, instant = ...   (any declarator position)
+    //   const instant = ...                 (local binding)
+    //   const { instant } = ...             (destructured binding)
+    //   export { instant }
+    //   export { foo as instant }
+    //   export function instant() {} / export class instant {}
+    const bindsInstant = (node) => {
+        switch (node?.type) {
+            case 'Identifier':
+                return node.name === 'instant';
+            case 'ObjectPattern':
+                return node.properties.some((prop) => prop.type === 'RestElement'
+                    ? bindsInstant(prop.argument)
+                    : bindsInstant(prop.value ?? prop.argument));
+            case 'ArrayPattern':
+                return node.elements.some((el) => el != null && bindsInstant(el));
+            case 'AssignmentPattern':
+                return bindsInstant(node.left);
+            case 'RestElement':
+                return bindsInstant(node.argument);
+            default:
+                return false;
+        }
+    };
+    const hasInstantBinding = root
+        .find(j.VariableDeclarator)
+        .filter((p) => bindsInstant(p.node.id))
+        .size() > 0 ||
+        root.find(j.ExportSpecifier, { exported: { name: 'instant' } }).size() >
+            0 ||
+        root.find(j.FunctionDeclaration, { id: { name: 'instant' } }).size() > 0 ||
+        root.find(j.ClassDeclaration, { id: { name: 'instant' } }).size() > 0;
+    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
+    // 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 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];
+    // Insert after the last top-level import, or at the top of the module
+    // if there are no imports.
+    const body = program.body;
+    let lastImportIndex = -1;
+    for (let i = 0; i < body.length; i++) {
+        if (body[i].type === 'ImportDeclaration')
+            lastImportIndex = i;
+    }
+    if (lastImportIndex !== -1) {
+        body.splice(lastImportIndex + 1, 0, instantExport);
+    }
+    else if (body.length > 0) {
+        // 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
+        // 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];
+        }
+        body.unshift(instantExport);
+    }
+    else {
+        body.push(instantExport);
+    }
+    return root.toSource();
+}
+//# sourceMappingURL=cache-components-instant-false.js.map

package/transforms/next-experimental-turbo-to-turbopack.js

@@ -4,8 +4,12 @@
  * the new top-level `turbopack` configuration.
  *
  * It moves most properties from experimental.turbo to the top-level turbopack
- * property, with special handling for certain properties like memoryLimit, minify,
+ * property, with special handling for certain properties like minify,
  * treeShaking, and sourceMaps which become experimental.turbopack* properties instead.
+ *
+ * The `memoryLimit` option is no longer supported, so it is removed entirely in
+ * both its old location (`experimental.turbo.memoryLimit`) and the location the
+ * previous version of this codemod produced (`experimental.turbopackMemoryLimit`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = transformer;
@@ -13,11 +17,15 @@ const parser_1 = require("../lib/parser");
 const utils_1 = require("./lib/utils");
 // Properties that need to be moved to experimental.turbopack*
 const RENAMED_EXPERIMENTAL_PROPERTIES = {
-    memoryLimit: 'turbopackMemoryLimit',
     minify: 'turbopackMinify',
     treeShaking: 'turbopackTreeShaking',
     sourceMaps: 'turbopackSourceMaps',
 };
+// `memoryLimit` is no longer supported and is removed entirely. We drop it under
+// both its old `experimental.turbo.*` name and the `experimental.*` name produced
+// by the previous version of this codemod.
+const REMOVED_TURBO_PROPERTY = 'memoryLimit';
+const REMOVED_EXPERIMENTAL_PROPERTY = 'turbopackMemoryLimit';
 function transformer(file, _api, options) {
     const j = (0, parser_1.createParserFromPath)(file.path);
     const root = j(file.source);
@@ -56,6 +64,13 @@ function transformer(file, _api, options) {
         const regularProps = [];
         const specialProps = [];
         turboObj.properties.forEach((prop) => {
+            if (isStaticProperty(prop) &&
+                prop.key &&
+                prop.key.type === 'Identifier' &&
+                prop.key.name === REMOVED_TURBO_PROPERTY) {
+                // Drop: `memoryLimit` is no longer supported.
+                return;
+            }
             if (isStaticProperty(prop) &&
                 prop.key &&
                 prop.key.type === 'Identifier' &&
@@ -71,7 +86,10 @@ function transformer(file, _api, options) {
         const existingProps = experimentalObj.properties.filter((prop) => !(isStaticProperty(prop) &&
             prop.key &&
             prop.key.type === 'Identifier' &&
-            prop.key.name === 'turbo'));
+            // Drop the `turbo` object (moved above) and a pre-existing
+            // `turbopackMemoryLimit` (no longer supported).
+            (prop.key.name === 'turbo' ||
+                prop.key.name === REMOVED_EXPERIMENTAL_PROPERTY)));
         experimentalObj.properties = [...existingProps, ...specialProps];
         // If experimental has no properties, remove it
         if (experimentalObj.properties.length === 0) {
@@ -132,7 +150,13 @@ function transformer(file, _api, options) {
         else {
             return;
         }
-        // For special properties like memoryLimit, minify, etc.
+        // `memoryLimit` is no longer supported: remove the assignment entirely.
+        if (propName === REMOVED_TURBO_PROPERTY) {
+            j(path).remove();
+            hasChanges = true;
+            return;
+        }
+        // For special properties like minify, treeShaking, etc.
         if (propName && RENAMED_EXPERIMENTAL_PROPERTIES[propName]) {
             const newAssignment = j.assignmentExpression('=', j.memberExpression(j.memberExpression(j.identifier(varName), j.identifier('experimental')), j.identifier(RENAMED_EXPERIMENTAL_PROPERTIES[propName])), path.node.right);
             j(path).replaceWith(newAssignment);
@@ -195,6 +219,26 @@ function transformer(file, _api, options) {
             hasChanges = true;
         }
     });
+    // Remove `config.experimental.turbopackMemoryLimit = value` assignments left
+    // behind by the previous version of this codemod (no longer supported).
+    root
+        .find(j.AssignmentExpression, {
+        left: {
+            type: 'MemberExpression',
+            object: {
+                type: 'MemberExpression',
+                property: { type: 'Identifier', name: 'experimental' },
+            },
+            property: {
+                type: 'Identifier',
+                name: REMOVED_EXPERIMENTAL_PROPERTY,
+            },
+        },
+    })
+        .forEach((path) => {
+        j(path).remove();
+        hasChanges = true;
+    });
     // Only return a string if we changed the AST, otherwise return the original source
     return hasChanges ? root.toSource(options) : file.source;
 }