create-nextly-app 0.0.2-alpha.72 → 0.0.2-alpha.74

package/dist/{create-nextly-CyI8XgVc.mjs → create-nextly-ChHdzG83.mjs}

@@ -22842,6 +22842,7 @@ function nextlySource(options) {
 function isNextlyPackage(name) {
 	return name === "nextly" || name.startsWith("@nextlyhq/");
 }
+/** The package.json fields that declare a dependency, in the order read. */
 const DEPENDENCY_FIELDS$1 = [
 	"dependencies",
 	"devDependencies",
@@ -22917,6 +22918,10 @@ const EXACT_FLAG = {
 	yarn: "--exact",
 	bun: "--exact"
 };
+/**
+* How each package manager adds a dependency. Exported so every message that
+* tells the person what to install spells the command the same way.
+*/
 const ADD_COMMAND = {
 	npm: "npm install",
 	pnpm: "pnpm add",
@@ -42486,8 +42491,8 @@ var import_lib = (/* @__PURE__ */ __commonJSMin$1(((exports) => {
 	exports.parse = parse;
 })))();
 /**
-* Where Nextly explains why Cache Components is off and when it will be
-* supported: the same page `nextly` links from the error it stops with.
+* Where Nextly explains the Cache Components settings every app it makes or
+* joins carries, and why each one is there.
 */
 const CACHE_COMPONENTS_DOCS_URL = "https://nextlyhq.com/docs/getting-started/installation#cache-components";
 /**
@@ -42525,13 +42530,42 @@ function packageListLiteral(database) {
 	return JSON.stringify(getServerExternalPackages(database), null, 2).replace(/\n/g, "\n  ");
 }
 /**
-* The setting every config this writes carries, with its reason in the file:
-* the developer who finds it is the one deciding whether to change it.
+* Nextly's cache handlers, as the settings that install them. Under Cache
+* Components, Next.js's default cache serves a page's previous shell once
+* after a write expires its tags; these expire it at once.
+*/
+const HANDLER_SETTINGS = [
+	"cacheHandler",
+	"cacheMaxMemorySize",
+	"cacheHandlers"
+];
+const HANDLER_PROPERTIES = [
+	"cacheHandler: require.resolve(\"nextly/cache-handler\")",
+	"cacheMaxMemorySize: 0",
+	"cacheHandlers: { default: require.resolve(\"nextly/cache-handlers\") }"
+];
+const ON_OPTIONS = ["cacheComponents", "partialPrefetching"];
+/** Every setting Nextly needs, as lines of a config object. */
+const ON_LINES = [...ON_OPTIONS.map((option) => `${option}: true`), ...HANDLER_PROPERTIES].map((property) => `  ${property},`);
+/**
+* The settings every config this writes carries, with their reason in the
+* file: the developer who finds them is the one deciding whether to change
+* them.
 */
-const CACHE_COMPONENTS_OFF = `  // Nextly does not support Cache Components yet: it caches with
-  // unstable_cache, and Cache Components refuses \`runtime\` route exports.
+const CACHE_COMPONENTS_ON = `  // Nextly runs with Cache Components and Partial Prefetching on. Its cache
+  // handlers make the first read after a write show the new version, where
+  // Next.js's default cache would serve the previous page once more:
   // ${CACHE_COMPONENTS_DOCS_URL}
-  cacheComponents: false,`;
+${ON_LINES.join("\n")}`;
+/**
+* How an ES module config gets `require`, which Node defines only in
+* CommonJS, to resolve the handlers from the app's own node_modules.
+*/
+const REQUIRE_IMPORT = "import { createRequire } from \"node:module\";";
+/** The declaration, calling `createRequire` by the name the file has it under. */
+const requireDeclaration = (createRequireName) => `// Resolves Nextly's cache handlers from this app's node_modules.
+const require = ${createRequireName}(import.meta.url);`;
+const REQUIRE_DECLARATION = requireDeclaration("createRequire");
 /**
 * Render a complete next.config.ts file for the selected database.
 */
@@ -42539,7 +42573,7 @@ function buildNextConfigTemplate(database) {
 	return `import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
-${CACHE_COMPONENTS_OFF}
+${CACHE_COMPONENTS_ON}
   serverExternalPackages: ${packageListLiteral(database)},
 };
 
@@ -42548,9 +42582,13 @@ export default nextConfig;
 }
 /** The same config as a JavaScript module, for an app without TypeScript. */
 function buildNextConfigModule(database) {
-	return `/** @type {import("next").NextConfig} */
+	return `${REQUIRE_IMPORT}
+
+${REQUIRE_DECLARATION}
+
+/** @type {import("next").NextConfig} */
 const nextConfig = {
-${CACHE_COMPONENTS_OFF}
+${CACHE_COMPONENTS_ON}
   serverExternalPackages: ${packageListLiteral(database)},
 };
 
@@ -42568,9 +42606,19 @@ const CONFIG_FILES = [
 	"next.config.ts",
 	"next.config.mts"
 ];
-/** The first Next.js major whose option is the top-level `serverExternalPackages`. */
-const FIRST_TOP_LEVEL_MAJOR = 15;
 const PROPERTY = "serverExternalPackages";
+/**
+* The deprecated spelling of the list, under `experimental`. Supported
+* releases still read it, by copying it over the top-level list, so an app
+* that has it would lose the packages this adds there.
+*/
+const LEGACY_PROPERTY = "serverComponentsExternalPackages";
+/**
+* Why a config with the deprecated list is left alone. Named, so the advice
+* printed for it can say what to do with that list rather than the advice
+* for every other refusal, which says to keep the experimental keys there.
+*/
+const LEGACY_LIST_REASON = `it lists packages under experimental.${LEGACY_PROPERTY}, which Next.js copies over ${PROPERTY}, replacing the packages added there`;
 /** Where the line holding `offset` starts. */
 const lineStart = (source, offset) => source.lastIndexOf("\n", offset - 1) + 1;
 /** The whitespace a line opens with, for the line holding `offset`. */
@@ -42751,7 +42799,7 @@ const TOP_LEVEL_SETTINGS = [
 	"transpilePackages",
 	"experimental"
 ];
-const EXPERIMENTAL_SETTINGS = ["optimizePackageImports", "serverComponentsExternalPackages"];
+const EXPERIMENTAL_SETTINGS = ["optimizePackageImports", LEGACY_PROPERTY];
 /** Why an object might set one of `names` where this cannot read it, or null. */
 function hiddenSettings(object, names, where) {
 	return object.properties.some((property) => mayHide(property, names)) ? `${where} spreads another object or has a computed or accessor property, which may set ${names.join(", ")}` : null;
@@ -42809,41 +42857,43 @@ function fillEmptyList(source, array, entries) {
 * so the app's own properties keep their order and their comments.
 */
 function addListProperty(source, object, entries) {
+	return appendProperties(source, object, (indent, ownLines) => [ownLines ? `${PROPERTY}: [\n${entries.map((entry) => `${indent}  ${entry},\n`).join("")}${indent}]` : `${PROPERTY}: [${entries.join(", ")}]`]);
+}
+/**
+* Add properties after an object's last one, in the object's layout: on one
+* line, as `{ a: 1, b: 2 }`, when it is written that way, and otherwise one
+* per line at the indentation its properties use, before the closing brace,
+* with a comma put after the last property first when it has none.
+* `properties` gets that indentation, and whether each property has a line
+* of its own, so a property spanning lines can follow the same layout.
+*/
+function appendProperties(source, object, properties) {
 	const open = (object.start ?? 0) + 1;
 	const close = (object.end ?? 0) - 1;
-	return spansLines(source, open, close) ? listOnItsOwnLines(source, object, entries) : [listOnTheSameLine(object, entries)];
+	if (!spansLines(source, open, close)) return [appendOnTheSameLine(object, properties("", false).join(", "))];
+	const last = object.properties.at(-1);
+	const indent = last ? indentAt(source, last.start ?? 0) : `${indentAt(source, close)}  `;
+	const lines = properties(indent, true).map((property) => `${indent}${property},\n`).join("");
+	return [...last !== void 0 && !/^\s*,/.test(source.slice(last.end ?? 0, close)) ? [{
+		at: last.end ?? 0,
+		remove: 0,
+		text: ","
+	}] : [], beforeClosingBrace(source, close, lines)];
 }
-/** The list added to an object written on one line, as `{ a: 1, serverExternalPackages: [...] }`. */
-function listOnTheSameLine(object, entries) {
-	const property = `${PROPERTY}: [${entries.join(", ")}]`;
+/** Properties added to an object written on one line, as `{ a: 1, b: 2 }`. */
+function appendOnTheSameLine(object, text) {
 	const last = object.properties.at(-1);
 	const open = (object.start ?? 0) + 1;
 	return last ? {
 		at: last.end ?? 0,
 		remove: 0,
-		text: `, ${property}`
+		text: `, ${text}`
 	} : {
 		at: open,
 		remove: (object.end ?? 0) - 1 - open,
-		text: ` ${property} `
+		text: ` ${text} `
 	};
 }
-/**
-* The list added as the last property of an object written over several
-* lines, one entry per line at the indentation the object's properties use.
-* A comma goes after the last property first when it has none.
-*/
-function listOnItsOwnLines(source, object, entries) {
-	const close = (object.end ?? 0) - 1;
-	const last = object.properties.at(-1);
-	const indent = last ? indentAt(source, last.start ?? 0) : `${indentAt(source, close)}  `;
-	const list = `${indent}${PROPERTY}: [\n${entries.map((entry) => `${indent}  ${entry},\n`).join("")}${indent}],\n`;
-	return [...last !== void 0 && !/^\s*,/.test(source.slice(last.end ?? 0, close)) ? [{
-		at: last.end ?? 0,
-		remove: 0,
-		text: ","
-	}] : [], beforeClosingBrace(source, close, list)];
-}
 /** Text put before an object's closing brace: on the line above it when the brace has a line of its own. */
 function beforeClosingBrace(source, close, text) {
 	const closeLine = lineStart(source, close);
@@ -42931,7 +42981,7 @@ function conflictOf(object, required) {
 }
 /** Why the config's lists clash, given an `experimental` object it can read. */
 function experimentalConflict(object, experimental, required) {
-	if (propertyValue(experimental, "serverComponentsExternalPackages")) return `it lists packages under experimental.serverComponentsExternalPackages, which Next.js moves to ${PROPERTY}; keep a single list there`;
+	if (propertyValue(experimental, LEGACY_PROPERTY)) return LEGACY_LIST_REASON;
 	return clashReason("transpilePackages", object, "transpilePackages", required) ?? clashReason("experimental.optimizePackageImports", experimental, "optimizePackageImports", required);
 }
 /** The object literal the file exports as its config, or why there is none to edit. */
@@ -43001,58 +43051,6 @@ function editConfig(source, file, required) {
 		added: plan.added
 	};
 }
-/** The string at `keys` inside a parsed JSON file, or null. */
-function stringAt(json, keys) {
-	let value = json;
-	for (const key of keys) {
-		if (typeof value !== "object" || value === null || !(key in value)) return null;
-		value = value[key];
-	}
-	return typeof value === "string" ? value : null;
-}
-/** A JSON file of the app's, or null when it is missing or does not parse. */
-async function readJsonOrNull(file) {
-	try {
-		return await import_lib$1.default.readJson(file);
-	} catch {
-		return null;
-	}
-}
-/**
-* A version range that admits one major only, such as `^15.1.0`, `~16.0`,
-* `15.x` or `16.0.0-canary.3`, with the major it admits. A range such as
-* `>=14`, `14 || 15` or `latest` admits several, or names none.
-*/
-const SINGLE_MAJOR = /^[\^~]?(\d+)(?:\.(?:\d+|[xX*])){0,2}(?:-[\w.]+)?$/;
-/**
-* The major version of the app's Next.js: the installed one, read from its
-* own `node_modules`, or else the one its package.json range admits when
-* that range admits a single major. Null when neither tells, as when
-* dependencies are not installed yet and the range is `latest`.
-*/
-async function nextMajor(cwd) {
-	const installed = stringAt(await readJsonOrNull(path.join(cwd, "node_modules", "next", "package.json")), ["version"]);
-	const manifest = await readJsonOrNull(path.join(cwd, "package.json"));
-	const range = stringAt(manifest, ["dependencies", "next"]) ?? stringAt(manifest, ["devDependencies", "next"]);
-	const match = SINGLE_MAJOR.exec((installed ?? range ?? "").trim());
-	return match ? Number(match[1]) : null;
-}
-/**
-* Why the option cannot be written for the app's Next.js, and which spelling
-* to print instead, or null when it can. Next.js 14 reads the list under
-* another name, and an unknown version may be 14: writing the top-level list
-* there would report success and externalise nothing.
-*/
-function versionBlock(major) {
-	if (major === null) return {
-		reason: "the version of Next.js the app uses could not be read",
-		spelling: "either"
-	};
-	return major < FIRST_TOP_LEVEL_MAJOR ? {
-		reason: `the app runs Next.js ${major}, which reads the list as experimental.serverComponentsExternalPackages and runs instrumentation.ts only with experimental.instrumentationHook`,
-		spelling: "legacy"
-	} : null;
-}
 /**
 * The Next config file any advice about the app's config names: the one it
 * has, or, when it has none, the one to create. `.mjs` is ESM whatever the
@@ -43104,14 +43102,6 @@ async function createNextConfig(cwd, database) {
 async function patchNextConfig(cwd, database) {
 	const file = await findConfigFile(cwd);
 	const required = getServerExternalPackages(database);
-	const blocked = versionBlock(await nextMajor(cwd));
-	if (blocked) return {
-		kind: "manual",
-		file: file ?? await nextConfigFileToChange(cwd),
-		packages: required,
-		...blocked,
-		...file ? {} : { create: true }
-	};
 	if (!file) return createNextConfig(cwd, database);
 	const edited = editConfig(await import_lib$1.default.readFile(path.join(cwd, file), "utf-8"), file, required);
 	if ("reason" in edited) return {
@@ -43131,119 +43121,281 @@ async function patchNextConfig(cwd, database) {
 		added: edited.added
 	};
 }
-/** The setting Nextly needs off, and the one Next.js accepts only with it on. */
-const CACHE_COMPONENTS = "cacheComponents";
-const PARTIAL_PREFETCHING = "partialPrefetching";
 /**
-* Remove a property with the comma that separates it: the whole line when it
-* has one of its own, else the property and the comma after it, or before it
-* when it is the last one.
+* The exported config object, when every setting this edits can be read in
+* it; else why not. Not through a wrapper call: Next.js receives what the
+* wrapper returns, which may set an option again, so the literal passed in
+* says nothing final.
 */
-function removeProperty(source, property) {
-	const start = property.start ?? 0;
-	const end = property.end ?? 0;
-	const ownLine = /^\s*$/.test(source.slice(lineStart(source, start), start));
-	const rest = /^[ \t]*,?[ \t]*\n/.exec(source.slice(end));
-	if (ownLine && rest) {
-		const from = lineStart(source, start);
-		return {
-			at: from,
-			remove: end + rest[0].length - from,
-			text: ""
-		};
-	}
-	const after = /^\s*,\s*/.exec(source.slice(end));
-	if (after) return {
-		at: start,
-		remove: end - start + after[0].length,
-		text: ""
-	};
-	const before = /,\s*$/.exec(source.slice(0, start));
-	const from = before ? start - before[0].length : start;
+function cacheComponentsObject(body) {
+	const object = exportedConfig(body, false);
+	if (typeof object === "string") return object;
+	return hiddenSettings(object, [...ON_OPTIONS, ...HANDLER_SETTINGS], "it") ?? object;
+}
+/**
+* How to turn one option on: the `false` to flip, the property to add when the
+* config does not set it, nothing when it is on, or why the value cannot be
+* read.
+*/
+function optionStep(object, name) {
+	const value = propertyValue(object, name);
+	if (!value) return { add: `${name}: true` };
+	if (value.type !== "BooleanLiteral") return `its ${name} is not true or false written in place`;
+	if (value.value) return {};
+	return { flip: {
+		at: value.start ?? 0,
+		remove: (value.end ?? 0) - (value.start ?? 0),
+		text: "true"
+	} };
+}
+/**
+* Whether Node loads the config as an ES module, where `require` is not
+* defined: `.mjs` and `.mts` always, and `.js` when it imports or exports,
+* which a config in a package of `"type": "module"` must, and which Node
+* detects in any other. Next.js compiles `next.config.ts` to CommonJS.
+*/
+function loadsAsModule(file, body) {
+	if (/\.m[jt]s$/.test(file)) return true;
+	return file.endsWith(".js") && body.some((statement) => statement.type === "ImportDeclaration" || statement.type === "ExportDefaultDeclaration" || statement.type === "ExportNamedDeclaration" || statement.type === "ExportAllDeclaration");
+}
+/**
+* The name an ES module config imports `createRequire` under from
+* `node:module`, whatever it renamed it to, or null when it imports none.
+*/
+function createRequireImport(body) {
+	return body.flatMap((statement) => statement.type === "ImportDeclaration" && (statement.source.value === "node:module" || statement.source.value === "module") ? statement.specifiers : []).find((item) => item.type === "ImportSpecifier" && importedName(item) === "createRequire")?.local.name ?? null;
+}
+/** The name an import specifier takes from its module, written plain or quoted. */
+function importedName(specifier) {
+	const { imported } = specifier;
+	return imported.type === "Identifier" ? imported.name : imported.value;
+}
+/** Whether the file binds `require` at its top level, by a declaration or an import. */
+function declaresRequire(body) {
+	return body.some((statement) => importsRequire(statement) || declaresRequireVariable(statement));
+}
+/** Whether `statement` imports a binding named `require`: hoisted, so bound anywhere. */
+function importsRequire(statement) {
+	return statement.type === "ImportDeclaration" && statement.specifiers.some((specifier) => isNamed(specifier.local, "require"));
+}
+/** The declarators in `statement` that name a variable `require`, exported or not. */
+function requireDeclarators(statement) {
+	const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+	return declaration?.type === "VariableDeclaration" ? declaration.declarations.filter((declarator) => isNamed(declarator.id, "require")) : [];
+}
+/** Whether `statement` declares a variable named `require`, exported or not. */
+function declaresRequireVariable(statement) {
+	return requireDeclarators(statement).length > 0;
+}
+/**
+* Whether the file binds `require` only by a variable declared after `at`,
+* where the config object starts. The object's `require.resolve` runs when
+* the object is evaluated, while that declaration is still in its temporal dead
+* zone, so it would throw: the lines are printed rather than written.
+*/
+function declaresRequireAfter(body, at) {
+	if (body.some(importsRequire)) return false;
+	const declarators = body.flatMap(requireDeclarators);
+	return declarators.length > 0 && declarators.every((declarator) => (declarator.start ?? 0) >= at);
+}
+/**
+* What an ES module config needs at its top for the handlers' `require`:
+* nothing when it binds `require` already, the declaration alone, calling its
+* own `createRequire` by its name, when it imports one, and otherwise the
+* import and the declaration.
+*/
+function requireSetupFor(body) {
+	if (declaresRequire(body)) return null;
+	const imported = createRequireImport(body);
+	return imported ? requireDeclaration(imported) : `${REQUIRE_IMPORT}\n\n${REQUIRE_DECLARATION}`;
+}
+/**
+* The edit that gives an ES module config `require`, before the first
+* statement that runs, and before the comments that lead it, such as a
+* `@type` annotation. Imports are hoisted, so one written further down still
+* loads first; the declaration is not, and a `require.resolve` evaluated
+* above it would throw.
+*/
+function requireEdit(source, body, setup) {
+	const first = body.find((statement) => statement.type !== "ImportDeclaration");
 	return {
-		at: from,
-		remove: end - from,
-		text: ""
+		at: lineStart(source, first?.leadingComments?.[0]?.start ?? first?.start ?? 0),
+		remove: 0,
+		text: `${setup}\n\n`
 	};
 }
-/** The exported config object, when both settings in it can be read; else why not. */
-function cacheComponentsObject(source, file) {
-	const body = parseBody(source, file);
-	if (!body) return "it could not be parsed";
-	const object = exportedConfig(body, false);
-	if (typeof object === "string") return object;
-	return hiddenSettings(object, [CACHE_COMPONENTS, PARTIAL_PREFETCHING], "it") ?? object;
+/** Whether `node` is `require.resolve("<specifier>")`. */
+function resolvesTo(node, specifier) {
+	if (node?.type !== "CallExpression") return false;
+	const { callee, arguments: args } = node;
+	const [only] = args;
+	return callee.type === "MemberExpression" && isNamed(callee.object, "require") && isNamed(callee.property, "resolve") && args.length === 1 && only?.type === "StringLiteral" && only.value === specifier;
 }
-/** The `true` to flip, null when Cache Components is off or unset, or why the value cannot be read. */
-function enabledValue(object) {
-	const value = propertyValue(object, CACHE_COMPONENTS);
-	if (!value) return null;
-	if (value.type !== "BooleanLiteral") return `its ${CACHE_COMPONENTS} is not true or false written in place`;
-	return value.value ? value : null;
+/** Whether the config's cache settings are Nextly's handlers, as this writes them. */
+function hasNextlysHandlers(object) {
+	const handlers = propertyValue(object, "cacheHandlers");
+	const memory = propertyValue(object, "cacheMaxMemorySize");
+	return resolvesTo(propertyValue(object, "cacheHandler"), "nextly/cache-handler") && handlers?.type === "ObjectExpression" && resolvesTo(propertyValue(handlers, "default"), "nextly/cache-handlers") && memory?.type === "NumericLiteral" && memory.value === 0;
 }
-/** The edits that turn Cache Components off in a config, none when it is off, or why it cannot be changed. */
-function cacheComponentsPlan(source, file) {
-	const object = cacheComponentsObject(source, file);
-	if (typeof object === "string") return { reason: object };
-	const value = enabledValue(object);
-	if (typeof value === "string") return { reason: value };
-	if (!value) return {
+/** The settings that make a cache of the app's own: a handler for either cache. */
+const OWN_CACHE_SETTINGS = ["cacheHandler", "cacheHandlers"];
+/** Whether the config gives `name` a value: written, and not `undefined`. */
+function setsValue(object, name) {
+	const value = propertyValue(object, name);
+	return value !== void 0 && !isNamed(value, "undefined");
+}
+/**
+* Why Nextly's handlers cannot go into this config as it stands, or null when
+* they can. A setting written as `undefined` is a placeholder to fill, not a
+* value; a handler of the app's own is not replaced; and `cacheMaxMemorySize`
+* must be 0, so Next.js keeps no second copy of the handlers' entries.
+*/
+function handlerConflict(object) {
+	const placeholders = HANDLER_SETTINGS.filter((name) => propertyValue(object, name) !== void 0 && !setsValue(object, name));
+	if (placeholders.length > 0) return `it sets ${placeholders.join(", ")} to undefined`;
+	const own = OWN_CACHE_SETTINGS.filter((name) => setsValue(object, name));
+	if (own.length > 0) return `it has cache handlers of its own (${own.join(", ")}), which were kept`;
+	const memory = propertyValue(object, "cacheMaxMemorySize");
+	return memory && !(memory.type === "NumericLiteral" && memory.value === 0) ? "it sets cacheMaxMemorySize to a value other than 0, which Nextly's handlers need so that Next.js keeps no second copy of their entries" : null;
+}
+/**
+* How to install Nextly's cache handlers: the properties to add and any edit
+* that gives the file `require`, or why they are left out, with the lines to
+* put in place of the config's own settings.
+*/
+function handlerStep(source, object, body, esm) {
+	const none = {
+		add: [],
+		edits: []
+	};
+	if (hasNextlysHandlers(object)) return {
+		...none,
+		outcome: "present"
+	};
+	const setup = esm ? requireSetupFor(body) : null;
+	const conflict = esm && declaresRequireAfter(body, object.start ?? 0) ? "it declares require after its config object, so the handlers' require.resolve would run before require exists; move that declaration above the object" : handlerConflict(object);
+	if (conflict) return {
+		...none,
+		outcome: {
+			skipped: conflict,
+			lines: HANDLER_PROPERTIES,
+			requireSetup: setup
+		}
+	};
+	const memorySet = propertyValue(object, "cacheMaxMemorySize") !== void 0;
+	const add = HANDLER_PROPERTIES.filter((property) => !(memorySet && property.startsWith("cacheMaxMemorySize")));
+	if (setup === null) return {
+		add,
 		edits: [],
-		removed: []
+		outcome: "added"
 	};
-	const flip = {
-		at: value.start ?? 0,
-		remove: (value.end ?? 0) - (value.start ?? 0),
-		text: "false"
+	if (referenceCount("require", body) > 0 || createRequireImport(body) === null && referenceCount("createRequire", body) > 0) return {
+		...none,
+		outcome: {
+			skipped: "it is an ES module that uses require, or a createRequire not imported from node:module, without binding require, so the lines that define it could clash",
+			lines: add,
+			requireSetup: setup
+		}
+	};
+	return {
+		add,
+		edits: [requireEdit(source, body, setup)],
+		outcome: "added"
 	};
-	const prefetching = object.properties.filter((property) => isPropertyNamed(property, PARTIAL_PREFETCHING));
+}
+/** The edits that turn Cache Components on in a config, or why it cannot be changed. */
+function cacheComponentsPlan(source, file, esm) {
+	const body = parseBody(source, file);
+	if (!body) return { reason: "it could not be parsed" };
+	const object = cacheComponentsObject(body);
+	if (typeof object === "string") return { reason: object };
+	const options = optionsPlan(object);
+	if ("reason" in options) return options;
+	const handlers = handlerStep(source, object, body, esm);
+	const add = [...options.add, ...handlers.add];
+	const edits = [...options.flips, ...handlers.edits];
+	if (add.length > 0) edits.push(...appendProperties(source, object, () => add));
 	return {
-		edits: [flip, ...prefetching.map((property) => removeProperty(source, property))],
-		removed: prefetching.length > 0 ? [PARTIAL_PREFETCHING] : []
+		edits,
+		turnedOn: options.turnedOn,
+		handlers: handlers.outcome
 	};
 }
-/** Whether a config, read as code, still defines `partialPrefetching` anywhere in its exported object. */
-function definesPartialPrefetching(source, file) {
-	const object = cacheComponentsObject(source, file);
-	return typeof object !== "string" && object.properties.some((property) => isPropertyNamed(property, PARTIAL_PREFETCHING));
+/** How to turn both options on: the values to flip, the properties to add, and which options change. */
+function optionsPlan(object) {
+	const plan = {
+		flips: [],
+		add: [],
+		turnedOn: []
+	};
+	for (const option of ON_OPTIONS) {
+		const step = optionStep(object, option);
+		if (typeof step === "string") return { reason: step };
+		if (step.flip) plan.flips.push(step.flip);
+		if (step.add) plan.add.push(step.add);
+		if (step.flip || step.add) plan.turnedOn.push(option);
+	}
+	return plan;
 }
 /**
-* Turn Next.js Cache Components off in an existing app's config, which
-* Nextly does not support yet; `create-next-app` 16.4 turns it on by default.
+* Turn Next.js Cache Components and Partial Prefetching on in an existing
+* app's config, with Nextly's cache handlers: Nextly runs with both on.
+* Apps that an earlier Nextly release turned off are turned on again.
 *
-* Only `cacheComponents: true` written in place is changed, and
-* `partialPrefetching` goes with it, since Next.js refuses that option once
-* Cache Components is off. The edit is trusted only once the result parses
-* and reads as off; anything else is left as it was, with what to change.
+* Only settings written in place as `true` or `false`, or absent, are
+* changed; a value this cannot read leaves the file as it was, with what to
+* add. The edit is trusted only once the result parses and reads as on.
 */
-async function turnOffCacheComponents(cwd) {
-	const file = await findConfigFile(cwd);
-	if (!file) return { kind: "unchanged" };
-	const source = await import_lib$1.default.readFile(path.join(cwd, file), "utf-8");
-	const plan = cacheComponentsPlan(source, file);
+async function turnOnCacheComponents(cwd) {
+	const file = await nextConfigFileToChange(cwd);
+	const source = await import_lib$1.default.readFile(path.join(cwd, file), "utf-8").catch(() => null);
+	if (source === null) return {
+		kind: "manual",
+		file,
+		reason: "the app has no Next config",
+		requireSetup: loadsAsModule(file, []) ? requireSetupFor([]) : null
+	};
+	const body = parseBody(source, file);
+	if (!body) return {
+		kind: "manual",
+		file,
+		reason: "it could not be parsed",
+		requireSetup: loadsAsModule(file, []) ? requireSetupFor([]) : null
+	};
+	const esm = loadsAsModule(file, body);
+	const requireSetup = esm ? requireSetupFor(body) : null;
+	const plan = cacheComponentsPlan(source, file, esm);
 	if ("reason" in plan) return {
 		kind: "manual",
 		file,
-		reason: plan.reason
+		reason: plan.reason,
+		requireSetup
+	};
+	if (plan.edits.length === 0) return {
+		kind: "unchanged",
+		file,
+		handlers: plan.handlers
 	};
-	if (plan.edits.length === 0) return { kind: "unchanged" };
 	const text = applyEdits(source, plan.edits);
-	const recheck = cacheComponentsPlan(text, file);
-	if ("reason" in recheck || recheck.edits.length > 0 || definesPartialPrefetching(text, file)) return {
+	const recheck = cacheComponentsPlan(text, file, esm);
+	if ("reason" in recheck || recheck.edits.length > 0) return {
 		kind: "manual",
 		file,
-		reason: "the edit could not be confirmed"
+		reason: "the edit could not be confirmed",
+		requireSetup
 	};
 	await import_lib$1.default.writeFile(path.join(cwd, file), text, "utf-8");
 	return {
-		kind: "turned-off",
+		kind: "turned-on",
 		file,
-		removed: plan.removed
+		turnedOn: plan.turnedOn,
+		handlers: plan.handlers
 	};
 }
 /**
-* What turning Cache Components off did, for the run's report: the change and
-* a notice saying why, or, for a config it could not change, what to change.
+* What turning Cache Components on did, for the run's report: each change and
+* a notice saying why, or, for a config it could not change, the exact lines
+* to add.
 */
 function cacheComponentsFiles(patch) {
 	const files = {
@@ -43251,43 +43403,42 @@ function cacheComponentsFiles(patch) {
 		changed: [],
 		skipped: []
 	};
-	if (patch.kind === "turned-off") {
+	if (patch.kind === "manual") {
+		files.skipped.push({
+			path: patch.file,
+			why: `Cache Components was not turned on: ${patch.reason}. Nextly runs with Cache Components and Partial Prefetching on, with its cache handlers (${CACHE_COMPONENTS_DOCS_URL}); add these to the config object Next.js receives, in place of any value of theirs`,
+			toAdd: linesToAdd$1(ON_LINES, patch.requireSetup)
+		});
+		return files;
+	}
+	const handlersAdded = patch.handlers === "added";
+	if (patch.kind === "turned-on") {
 		files.changed.push({
 			path: patch.file,
-			added: [`${CACHE_COMPONENTS}: false`]
+			added: [...patch.turnedOn.map((option) => `${option}: true`), ...handlersAdded ? [...HANDLER_SETTINGS] : []]
 		});
-		const removed = patch.removed.length ? `, and removed ${patch.removed.join(", ")}, which Next.js accepts only with it on` : "";
-		files.notices = [`Turned Cache Components off in ${patch.file}: Nextly does not support it yet${removed}. Why, and the plan to support it: ${CACHE_COMPONENTS_DOCS_URL}`];
-	} else if (patch.kind === "manual") files.skipped.push({
+		const done = [...patch.turnedOn.length > 0 ? [`turned ${patch.turnedOn.join(" and ")} on`] : [], ...handlersAdded ? ["installed Nextly's cache handlers"] : []].join(" and ");
+		files.notices = [`In ${patch.file}, ${done}: Nextly runs with Cache Components and Partial Prefetching on. What each setting does: ${CACHE_COMPONENTS_DOCS_URL}`];
+	}
+	if (typeof patch.handlers === "object") files.skipped.push({
 		path: patch.file,
-		why: `Nextly could not confirm Cache Components is off: ${patch.reason}. Nextly does not support it yet (${CACHE_COMPONENTS_DOCS_URL}); make sure the config Next.js receives leaves it unset or sets it to false, with no ${PARTIAL_PREFETCHING}`,
-		toAdd: `  ${CACHE_COMPONENTS}: false,`
+		why: `Nextly's cache handlers were not added: ${patch.handlers.skipped}. Without them a page read right after a write can show the previous version once, and in production every cached public read refreshes within a minute of a visit, since a write from another instance, the CLI or a job reaches no other cache (${CACHE_COMPONENTS_DOCS_URL}); to use them, put these in place of the config's own cache settings`,
+		toAdd: linesToAdd$1(patch.handlers.lines.map((property) => `  ${property},`), patch.handlers.requireSetup)
 	});
 	return files;
 }
 /**
-* What to add by hand, in the spelling the app's Next.js reads.
-*
-* On Next.js 14 the package list and the instrumentation opt-in are keys of
-* one `experimental` object, so they are given as one: two `experimental`
-* properties, pasted as given, leave only the second. The instrumentation
-* hook Nextly starts from needs the opt-in there, and no other step says so.
-* `wrap` turns each spelling into what to paste: the key itself, or a whole
-* config file when the app has none.
-*/
-function optionText(packages, spelling, wrap = (option) => option) {
-	const list = packages.map((name) => JSON.stringify(name)).join(", ");
-	const current = wrap(`  ${PROPERTY}: [${list}],`);
-	const legacy = wrap(`  experimental: { instrumentationHook: true, serverComponentsExternalPackages: [${list}] },`);
-	if (spelling === "legacy") return legacy;
-	return spelling === "either" ? `On Next.js 15 or later:\n\n${current}\n\nOn Next.js 14:\n\n${legacy}` : current;
-}
-/**
-* A whole config holding `option`, for an app that has none. ESM in `.mjs`,
-* which loads whatever the package's own "type" says.
+* The config lines to add by hand. An ES module config with no `require`
+* also gets the lines that define it for the handlers, at the top of the file.
 */
-function wholeConfig(option) {
-	return `/** @type {import('next').NextConfig} */\nexport default {\n${option}\n};\n`;
+function linesToAdd$1(lines, requireSetup) {
+	const config = lines.join("\n");
+	return requireSetup ? `// At the top of the file:\n${requireSetup.replace("\n\n", "\n")}\n\n// In the config object:\n${config}` : config;
+}
+/** What to add by hand: the list, as the config's top-level option. */
+function optionText(packages) {
+	const list = packages.map((name) => JSON.stringify(name)).join(", ");
+	return `  ${PROPERTY}: [${list}],`;
 }
 /**
 * What a patch did, in the shape every existing-app step reports in: the
@@ -43311,109 +43462,14 @@ function nextConfigFiles(patch) {
 			files.written.push(patch.file);
 			break;
 		case "unchanged": break;
-		case "manual": files.skipped.push(patch.create ? {
+		case "manual": files.skipped.push({
 			path: patch.file,
-			why: `Nextly's packages were not added: ${patch.reason}, and the app has no Next.js config. Create ${patch.file} with:`,
-			toAdd: optionText(patch.packages, patch.spelling, wholeConfig)
-		} : {
-			path: patch.file,
-			why: `Nextly's packages were not added: ${patch.reason}. Add them to the config object it exports, keeping any packages and experimental keys already there`,
-			toAdd: optionText(patch.packages, patch.spelling)
+			why: patch.reason === LEGACY_LIST_REASON ? `Nextly's packages were not added: ${patch.reason}. Move the packages under experimental.${LEGACY_PROPERTY} into a top-level ${PROPERTY} list, add Nextly's to it, and delete experimental.${LEGACY_PROPERTY}, keeping the config's other experimental keys` : `Nextly's packages were not added: ${patch.reason}. Add them to the config object it exports, keeping any packages and experimental keys already there`,
+			toAdd: optionText(patch.packages)
 		});
 	}
 	return files;
 }
-// src/generators/page-extensions.ts
-/**
-* The page extension to name a new module file with, a hook or a route: a
-* TypeScript one first, since Nextly's files are TypeScript, then a
-* JavaScript one; never a content extension such as `mdx`, which Next.js
-* would compile as content, and never `cjs`, since the files are ES modules
-* and a `.cjs` file cannot hold one. Null when the list holds no extension a
-* module can be written in.
-*/
-function moduleExtension(extensions) {
-	const usable = writable(extensions);
-	return usable.find((extension) => /(^|\.)tsx?$/.test(extension)) ?? usable.find((extension) => /(^|\.)(js|jsx|mjs)$/.test(extension)) ?? null;
-}
-/**
-* The extensions a file with code in it can be written under: not a
-* declaration file's (`d.ts`, `d.mts`, `d.cts`), which TypeScript reads as
-* types only and refuses code in.
-*/
-function writable(extensions) {
-	return extensions.filter((extension) => !/(^|\.)d\.[cm]?tsx?$/.test(extension));
-}
-/**
-* The `pageExtensions` the app's Next.js config sets, as every existing-app
-* step that names a file Next.js routes reads it: the list; `"absent"` when
-* the config sets none, or there is no config; or null when it is set in a
-* way that cannot be read. Read from the config the app exports, as the Next
-* config step reads it, so a commented-out or nested `pageExtensions` sets
-* nothing. `configName` is the file it was read from, for the report.
-*/
-async function appPageExtensions(cwd) {
-	const nextConfig = await readNextConfig(cwd);
-	return {
-		configName: nextConfig?.name ?? "The Next.js config",
-		extensions: nextConfig ? configStringList(nextConfig.text, nextConfig.name, "pageExtensions") : "absent"
-	};
-}
-/**
-* The text of the app's Next.js config, or null when it has none, from the
-* file the Next config step reads and extends ({@link findConfigFile}).
-*/
-async function readNextConfig(cwd) {
-	const name = await findConfigFile(cwd);
-	return name === null ? null : {
-		name,
-		text: await import_lib$1.default.readFile(path.join(cwd, name), "utf-8")
-	};
-}
-/**
-* The page extension for a file of TypeScript with JSX, such as a page or a
-* layout: one ending in `tsx`. Null when the list holds none.
-*/
-function tsxExtension(extensions) {
-	return writable(extensions).find((extension) => /(^|\.)tsx$/.test(extension)) ?? null;
-}
-/** A JavaScript or TypeScript module without JSX, such as a route. */
-const MODULE_FILE = {
-	pick: moduleExtension,
-	holds: "a JavaScript or TypeScript extension"
-};
-/** TypeScript with JSX, such as a page or a layout. */
-const TSX_FILE = {
-	pick: tsxExtension,
-	holds: "an extension ending in tsx"
-};
-/**
-* The report for a file an app that sets `pageExtensions` gets in place of
-* the file: the name to create it under and its content. Next.js routes a
-* file there only under a name with one of the app's extensions, and the app
-* may already have the file under such a name, which the existing-app steps
-* do not look for, so nothing is written. A list that cannot be read, or that
-* holds no extension the content needs, gives a placeholder name and says
-* which.
-*
-* @param base the file's path without its extension, as reported, such as
-*   `app/admin/[[...params]]/page`
-*/
-function pageExtensionsSkip(base, text, pages, need) {
-	const { configName, extensions } = pages;
-	const extension = extensions === null ? null : need.pick(extensions);
-	const sets = `${configName} sets pageExtensions, and Next.js routes a file there only under a name with one of them, so none was written`;
-	if (extensions !== null && extension === null) return {
-		path: `${base}.<${need.holds} added to pageExtensions>`,
-		why: `${sets}, and none of them (${extensions.join(", ")}) is ${need.holds}; add one to pageExtensions, then, unless the app already has this file, create it under that name with this content`,
-		toAdd: text
-	};
-	return {
-		path: `${base}.${extension ?? "<one of your pageExtensions>"}`,
-		why: `${sets}; unless the app already has this file, create it under that name with this content`,
-		toAdd: text
-	};
-}
 // src/utils/detect-pm-from-user-agent.ts
 /**
 * Detect the package manager that invoked `create-nextly-app` by reading
@@ -45644,6 +45700,45 @@ function getDefaultApproach(name) {
 function shouldUseBundledTemplate(projectType, options) {
 	return BUNDLED_TEMPLATES.some((name) => name === projectType) && !options.localTemplatePath && !options.useYalc && options.branch === void 0;
 }
+// src/supported-versions.ts
+/**
+* The Next.js and React this release of Nextly supports, in one place.
+*
+* Two facts, deliberately kept apart:
+*
+* - `REVIEWED_VERSIONS` is the newest release of each package this Nextly
+*   release was reviewed against. A new app declares it as a `~` range
+*   ({@link scaffoldRange}): patch releases of that minor, never a newer minor
+*   or major that nobody has checked, and never whatever npm's `latest` names
+*   on the day of the scaffold.
+* - `SUPPORTED_RANGES` is every release Nextly works with: the `nextly`
+*   package's own peer ranges, inlined at build, so they are declared once.
+*   Every other package declares the same as its peers. Adding Nextly to an
+*   existing app refuses one whose Next.js, React or React DOM falls outside
+*   them, and a scaffolded plugin declares them as its own peers.
+*
+* Only a release review moves either: a newer Next.js or React is supported
+* once a Nextly release has been checked against it, not before.
+*/
+const REVIEWED_VERSIONS = {
+	next: "16.4.2",
+	"eslint-config-next": "16.4.2",
+	react: "19.3.1",
+	"react-dom": "19.3.1"
+};
+const SUPPORTED_RANGES = {
+	"next": "^16.4.1",
+	"react": "^19.3.0",
+	"react-dom": "^19.3.0"
+};
+/**
+* The range a new project declares for `pkg`: patch releases of the reviewed
+* minor only. Derived here rather than written out, so the reviewed version is
+* the one thing a release review edits.
+*/
+function scaffoldRange(pkg) {
+	return `~${REVIEWED_VERSIONS[pkg]}`;
+}
 // src/utils/package-manager-commands.ts
 /**
 * The prefix that runs a package.json script.
@@ -45671,37 +45766,35 @@ function binaryRunner(packageManager) {
 		case "bun": return "bunx";
 	}
 }
-// src/utils/plugin-node.ts
-/**
-* The Node versions a scaffolded plugin supports, and the check that refuses
-* to scaffold one on a Node it cannot build on.
-*
-* A plugin builds with tsdown and tests with Vitest, and each declares the
-* Node it runs on; the plugin's floor is where both agree. The repository's
-* packages have a lower floor, because only a plugin author runs these tools.
-* `scaffold-plugin.test.ts` derives this range from the installed tools' own
-* `engines`, so a version bump that moves either one fails there.
-*/
-const PLUGIN_NODE_ENGINES = "^22.18.0 || ^24.11.0 || >=26.0.0";
+// src/utils/version-range.ts
 function parseVersion$1(text) {
-	const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(text.trim());
-	if (!match) throw new Error(`not a Node version: ${text}`);
-	return [
+	const match = /^v?(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?/.exec(text.trim());
+	if (!match) throw new Error(`not a version: ${text}`);
+	return Object.assign([
 		Number(match[1]),
 		Number(match[2]),
 		Number(match[3])
-	];
+	], { prerelease: match[4] !== void 0 });
 }
+/** Older first; of two with the same numbers, a prerelease comes before its release, as in semver. */
 function compare(a, b) {
-	return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+	return a[0] - b[0] || a[1] - b[1] || a[2] - b[2] || Number(Boolean(b.prerelease)) - Number(Boolean(a.prerelease));
 }
 /**
-* Whether `version` satisfies one comparator. Only the two forms these tools
-* write are understood, `^X.Y.Z` and `>=X.Y.Z`; any other is refused rather
-* than read approximately, so a tool that starts declaring another form fails
+* Negative when `a` is older than `b`, positive when newer, 0 when equal.
+* A prerelease is older than its release: `16.4.1-canary.1` is below `16.4.1`.
+*/
+function compareVersions(a, b) {
+	return compare(parseVersion$1(a), parseVersion$1(b));
+}
+/**
+* Whether `version` satisfies one comparator. Only the two forms this CLI
+* writes are understood, `^X.Y.Z` and `>=X.Y.Z`; any other is refused rather
+* than read approximately, so a range that starts using another form fails
 * the test that reads it.
 */
 function satisfiesComparator(version, comparator) {
+	if (version.prerelease) return false;
 	const caret = /^\^(\d+\.\d+\.\d+)$/.exec(comparator);
 	if (caret) {
 		const floor = parseVersion$1(caret[1]);
@@ -45709,21 +45802,83 @@ function satisfiesComparator(version, comparator) {
 	}
 	const atLeast = /^>=(\d+\.\d+\.\d+)$/.exec(comparator);
 	if (atLeast) return compare(version, parseVersion$1(atLeast[1])) >= 0;
-	throw new Error(`unsupported Node range comparator: ${comparator}`);
+	throw new Error(`unsupported range comparator: ${comparator}`);
 }
 /** Whether `version` satisfies a `||` list of `^X.Y.Z` / `>=X.Y.Z` comparators. */
-function satisfiesNodeRange(version, range) {
+function satisfiesRange(version, range) {
 	const parsed = parseVersion$1(version);
 	return range.split("||").map((part) => part.trim()).some((comparator) => satisfiesComparator(parsed, comparator));
 }
 /**
-* Why the plugin template cannot be scaffolded on `nodeVersion`, or
-* `undefined` when it can. Checked before anything is written, since a plugin
-* scaffolded on an older Node would install and then fail its first build.
+* The lowest version a package.json dependency spec admits, as `X.Y.Z`, or
+* `undefined` when the spec names no lower bound this can read: a dist-tag
+* (`latest`, `canary`), a protocol (`workspace:*`, `file:`, a URL), `*`, or an
+* upper bound alone (`<17`). An exact version is its own lowest; `^`, `~`, `=`
+* and `>=` start at the version they name; a missing or wildcard minor or
+* patch (`15`, `15.x`) counts as 0; across `||` the lowest alternative wins.
 */
-function pluginNodeRefusal(nodeVersion) {
-	if (satisfiesNodeRange(nodeVersion, "^22.18.0 || ^24.11.0 || >=26.0.0")) return void 0;
-	return `The plugin template builds with tools that need Node ${PLUGIN_NODE_ENGINES}, and this is Node ${nodeVersion}. Install a supported Node (for example \`nvm install 24\`) and run create-nextly-app again.`;
+function lowestVersionIn(spec) {
+	let lowest;
+	for (const part of spec.split("||")) {
+		const match = /^\s*(?:\^|~|>=|=)?\s*v?(\d+)(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?/.exec(part);
+		if (!match) continue;
+		const number = (text) => text === void 0 || !/^\d+$/.test(text) ? 0 : Number(text);
+		const found = [
+			Number(match[1]),
+			number(match[2]),
+			number(match[3])
+		];
+		if (!lowest || compare(found, lowest) < 0) lowest = found;
+	}
+	return lowest ? lowest.join(".") : void 0;
+}
+/**
+* The highest major a package.json dependency spec admits, `Infinity` when it
+* has no upper bound (`>=16.4.1`, `*`, `x`), or `undefined` when no
+* alternative names one this can read (a dist-tag, a protocol). Across `||`
+* the highest alternative wins, since an install resolves the newest version
+* any of them admits. Within one alternative an upper bound (`<17`, `<=17.2`)
+* decides; otherwise the version a `^`, `~`, `=` or bare spec names.
+*/
+function highestMajorIn(spec) {
+	let highest;
+	for (const part of spec.split("||")) {
+		const found = majorReachedBy(part.trim());
+		if (found !== void 0 && (highest === void 0 || found > highest)) highest = found;
+	}
+	return highest;
+}
+/** The highest major one `||` alternative reaches, as `highestMajorIn` reads it. */
+function majorReachedBy(part) {
+	const upper = /<(=)?\s*v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(part);
+	if (upper) {
+		const [, inclusive, major, minor, patch] = upper;
+		return inclusive !== void 0 || Number(minor ?? 0) > 0 || Number(patch ?? 0) > 0 ? Number(major) : Number(major) - 1;
+	}
+	if (part === "" || /^(\*|[xX])$/.test(part) || part.startsWith(">")) return Infinity;
+	const named = /^(?:\^|~|=)?\s*v?(\d+)/.exec(part);
+	return named ? Number(named[1]) : void 0;
+}
+// src/utils/plugin-node.ts
+/**
+* The Node versions a scaffolded plugin supports, and the check that refuses
+* to scaffold one on a Node it cannot build on.
+*
+* A plugin builds with tsdown and tests with Vitest, and each declares the
+* Node it runs on; the plugin's floor is where both agree. The repository's
+* packages have a lower floor, because only a plugin author runs these tools.
+* `scaffold-plugin.test.ts` derives this range from the installed tools' own
+* `engines`, so a version bump that moves either one fails there.
+*/
+const PLUGIN_NODE_ENGINES = "^22.18.0 || ^24.11.0 || >=26.0.0";
+/**
+* Why the plugin template cannot be scaffolded on `nodeVersion`, or
+* `undefined` when it can. Checked before anything is written, since a plugin
+* scaffolded on an older Node would install and then fail its first build.
+*/
+function pluginNodeRefusal(nodeVersion) {
+	if (satisfiesRange(nodeVersion, "^22.18.0 || ^24.11.0 || >=26.0.0")) return void 0;
+	return `The plugin template builds with tools that need Node ${PLUGIN_NODE_ENGINES}, and this is Node ${nodeVersion}. Install a supported Node (for example \`nvm install 24\`) and run create-nextly-app again.`;
 }
 // src/utils/template.ts
 /**
@@ -45818,41 +45973,56 @@ const SEARCH_INDEX_SCRIPT = path.join("scripts", "build-search-index.mjs");
 async function projectHasSearchIndexScript(targetDir) {
 	return import_lib$1.default.pathExists(path.join(targetDir, SEARCH_INDEX_SCRIPT));
 }
-/**
-* The plugins a Nextly config registers, by package name: each binding it
-* imports from a `@nextlyhq/plugin-*` package (the SDK aside) that a
-* `plugins: [...]` list in it names, however deep in an element. Read with
-* the parser the Next config step uses, so nested brackets, either quote and
-* default or aliased imports are read as the compiler reads them. First-party
-* plugins register under their package name, which is what
-* `nextly plugins install` takes. Throws for a config that does not parse,
-* since every template's must.
-*
-* Exported for the test that holds every template's config to its build.
-*/
-function configuredPlugins(configText, file = "nextly.config.ts") {
-	let program;
+/** Parses a config, naming the file when it does not parse. */
+function parseConfigProgram(configText, file) {
 	try {
-		program = (0, import_lib.parse)(configText, {
+		return (0, import_lib.parse)(configText, {
 			sourceType: "module",
 			plugins: ["typescript", "jsx"]
 		}).program;
 	} catch (error) {
 		throw new Error(`${file} cannot be parsed (${error.message}), so the plugins its build must install cannot be read.`);
 	}
-	const fromPackage = /* @__PURE__ */ new Map();
+}
+/** Each binding imported from a module `matches` accepts, to that module's name. */
+function bindingsImportedFrom(program, matches) {
+	const bindings = /* @__PURE__ */ new Map();
 	for (const statement of program.body) {
 		if (statement.type !== "ImportDeclaration") continue;
-		const pkg = statement.source.value;
-		if (!pkg.startsWith("@nextlyhq/plugin-") || pkg === "@nextlyhq/plugin-sdk") continue;
-		for (const specifier of statement.specifiers) fromPackage.set(specifier.local.name, pkg);
+		if (!matches(statement.source.value)) continue;
+		for (const specifier of statement.specifiers) bindings.set(specifier.local.name, statement.source.value);
 	}
-	const found = [];
+	return bindings;
+}
+const isPluginPackage = (source) => source.startsWith("@nextlyhq/plugin-") && source !== "@nextlyhq/plugin-sdk";
+/** What a config's `plugins` lists hold: the packages, and whether a binding from its own source is among them. */
+function readPluginLists(configText, file) {
+	const program = parseConfigProgram(configText, file);
+	const fromPackage = bindingsImportedFrom(program, isPluginPackage);
+	const packages = /* @__PURE__ */ new Set();
 	for (const name of identifiersInPluginLists(program, file)) {
 		const pkg = fromPackage.get(name);
-		if (pkg !== void 0 && !found.includes(pkg)) found.push(pkg);
+		if (pkg !== void 0) packages.add(pkg);
 	}
-	return found;
+	const local = bindingsImportedFrom(program, (source) => source.startsWith("."));
+	const ownPlugin = namesInPluginEntries(program, file).some((name) => local.has(name) && !fromPackage.has(name));
+	return {
+		packages: [...packages],
+		ownPlugin
+	};
+}
+/**
+* The `nextly plugins install` steps a project's build runs, read from its
+* config. A plugin package is installed by name, and the build says which. A
+* plugin the site wrote itself has no package name to give, and a production
+* boot refuses it like any other when nothing has installed it, so a config
+* that lists one installs with `--all`, which reads the names from the config.
+* Exported for the test that holds every template's config to its build.
+*/
+function pluginInstallSteps(configText, file = "nextly.config.ts") {
+	const { packages, ownPlugin } = readPluginLists(configText, file);
+	if (ownPlugin) return ["nextly plugins install --all"];
+	return packages.map((pkg) => `nextly plugins install ${pkg}`);
 }
 /** Every identifier inside the value of each `plugins: [...]` property, in source order. */
 function identifiersInPluginLists(program, file) {
@@ -45866,6 +46036,20 @@ function identifiersInPluginLists(program, file) {
 	return names;
 }
 /**
+* The binding each entry of a `plugins: [...]` list is, as written: `seo` for
+* `seo` or `seo({ ... })`. Narrower than {@link identifiersInPluginLists},
+* which also sees the identifiers inside an entry's options.
+*/
+function namesInPluginEntries(program, file) {
+	const names = [];
+	walkNodes(program, (node) => {
+		if (!isPluginList(node, file) || node.value.type !== "ArrayExpression") return;
+		for (const element of node.value.elements) if (element?.type === "Identifier") names.push(element.name);
+		else if (element?.type === "CallExpression" && element.callee.type === "Identifier") names.push(element.callee.name);
+	});
+	return names;
+}
+/**
 * A `plugins: [...]` property, by an identifier or a string key. A `plugins`
 * property written any other way, such as a variable holding the list, a call
 * or a spread inside it, is
@@ -45897,16 +46081,15 @@ function isNode(value) {
 	return typeof value === "object" && value !== null && typeof value.type === "string";
 }
 /**
-* The plugins the scaffolded PROJECT's config registers, read from the
-* finished project as {@link projectHasSearchIndexScript} is: a template
-* offers more than one config (the blog's visual one registers none), so
-* only the file the copy wrote can say. None when there is no config, or
-* no project on disk to ask.
+* The plugin install steps the scaffolded PROJECT's build needs, read from
+* the finished project as {@link projectHasSearchIndexScript} is: a template
+* offers more than one config, so only the file the copy wrote can say. None
+* when there is no config, or no project on disk to ask.
 */
-async function projectPlugins(targetDir) {
+async function projectPluginInstalls(targetDir) {
 	if (targetDir === void 0) return [];
 	const config = path.join(targetDir, "nextly.config.ts");
-	return await import_lib$1.default.pathExists(config) ? configuredPlugins(await import_lib$1.default.readFile(config, "utf-8"), config) : [];
+	return await import_lib$1.default.pathExists(config) ? pluginInstallSteps(await import_lib$1.default.readFile(config, "utf-8"), config) : [];
 }
 /**
 * Every file under `root` that could carry an import specifier.
@@ -46367,14 +46550,12 @@ async function replacePlaceholders(dir, placeholders, skip = /* @__PURE__ */ new
 /**
 * Pinned dependency versions for generated projects.
 *
-* `next` and `eslint-config-next` are resolved at runtime from the npm
-* registry so that fresh projects always get the latest release without
-* needing to republish create-nextly-app.  The remaining versions use
-* wide semver ranges that rarely need updating.
+* `next`, `eslint-config-next`, `react` and `react-dom` are not here: they
+* come from `supported-versions`, the reviewed release of each, so a project
+* never declares a Next.js or React no Nextly release was checked against.
+* The remaining versions use wide semver ranges that rarely need updating.
 */
 const PINNED_VERSIONS = {
-	react: "^19.3.1",
-	"react-dom": "^19.3.1",
 	typescript: "^5",
 	"@types/node": "^22",
 	"@types/react": "^19",
@@ -46392,11 +46573,6 @@ const PINNED_VERSIONS = {
 */
 const CONFIG_TOOLING_DEV_DEPENDENCIES = [`esbuild@${PINNED_VERSIONS.esbuild}`];
 /**
-* Packages whose latest version is fetched from the npm registry at
-* runtime so the CLI always scaffolds with the newest release.
-*/
-const RUNTIME_RESOLVED_PACKAGES = ["next", "eslint-config-next"];
-/**
 * @nextlyhq packages whose latest version is fetched from npm at runtime.
 * This avoids having to republish create-nextly-app every time a
 * dependency package is updated.
@@ -46420,9 +46596,10 @@ const resolvedNextlyVersions = /* @__PURE__ */ new Map();
 * On any failure (non-OK response, timeout, missing tag, thrown error) it
 * returns the requested dist-tag NAME itself (e.g. "alpha") — a valid npm
 * install spec — so a project on the alpha line never silently drops to
-* `latest`.
+* `latest`. The channel has no default: only the Nextly packages are read
+* from the registry, always on a tag their caller names.
 */
-async function fetchLatestVersion(pkg, channel = "latest") {
+async function fetchLatestVersion(pkg, channel) {
 	try {
 		const res = await fetch(`https://registry.npmjs.org/-/package/${encodeURIComponent(pkg)}/dist-tags`, { signal: AbortSignal.timeout(5e3) });
 		if (!res.ok) return channel;
@@ -46456,26 +46633,6 @@ async function nextlyVersions(source) {
 	if (source.kind === "release") return Object.fromEntries(NEXTLY_PACKAGES.map((pkg) => [pkg, source.cliVersion]));
 	return resolveNextlyVersions("alpha");
 }
-/** Cache for runtime-resolved package versions (next, eslint-config-next). */
-let resolvedRuntimeVersions = null;
-/**
-* Resolve latest versions for Next.js ecosystem packages in parallel.
-* Falls back to a safe semver range if the registry is unreachable.
-*/
-async function resolveRuntimeVersions() {
-	if (resolvedRuntimeVersions) return resolvedRuntimeVersions;
-	const NEXT_FLOOR = "^16.4.1";
-	const FALLBACKS = {
-		next: NEXT_FLOOR,
-		"eslint-config-next": NEXT_FLOOR
-	};
-	const entries = await Promise.all(RUNTIME_RESOLVED_PACKAGES.map(async (pkg) => {
-		const version = await fetchLatestVersion(pkg);
-		return [pkg, version === "latest" ? FALLBACKS[pkg] : version];
-	}));
-	resolvedRuntimeVersions = Object.fromEntries(entries);
-	return resolvedRuntimeVersions;
-}
 /**
 * Generate a `package.json` string for a fresh Nextly project.
 *
@@ -46494,11 +46651,10 @@ async function resolveRuntimeVersions() {
 */
 async function generatePackageJson(projectName, database, source = nextlySource({ cliVersion: packageVersion() }), projectType = "blank", templateDirs = [], targetDir) {
 	if (projectType === "plugin") return generatePluginPackageJson(projectName, source);
-	const runtimeVersions = await resolveRuntimeVersions();
 	const dependencies = {
-		next: runtimeVersions.next,
-		react: PINNED_VERSIONS.react,
-		"react-dom": PINNED_VERSIONS["react-dom"]
+		next: scaffoldRange("next"),
+		react: scaffoldRange("react"),
+		"react-dom": scaffoldRange("react-dom")
 	};
 	dependencies["@tanstack/react-query"] = "^5.62.0";
 	dependencies["lucide-react"] = "^0.544.0";
@@ -46522,11 +46678,11 @@ async function generatePackageJson(projectName, database, source = nextlySource(
 		"@tailwindcss/postcss": PINNED_VERSIONS["@tailwindcss/postcss"],
 		tailwindcss: PINNED_VERSIONS.tailwindcss,
 		eslint: PINNED_VERSIONS.eslint,
-		"eslint-config-next": runtimeVersions["eslint-config-next"],
+		"eslint-config-next": scaffoldRange("eslint-config-next"),
 		esbuild: PINNED_VERSIONS.esbuild
 	};
 	const shipsSearchIndex = targetDir ? await projectHasSearchIndexScript(targetDir) : false;
-	const plugins = await projectPlugins(targetDir);
+	const pluginInstalls = await projectPluginInstalls(targetDir);
 	if (shipsSearchIndex) devDependencies.pagefind = "^1.1.0";
 	const pkg = {
 		name: projectName,
@@ -46536,7 +46692,7 @@ async function generatePackageJson(projectName, database, source = nextlySource(
 			dev: "next dev --turbopack",
 			build: [
 				"nextly migrate",
-				...plugins.map((plugin) => `nextly plugins install ${plugin}`),
+				...pluginInstalls,
 				"next build",
 				...shipsSearchIndex ? ["node scripts/build-search-index.mjs"] : []
 			].join(" && "),
@@ -46598,7 +46754,6 @@ async function resolvePluginNextlyRange(source) {
 */
 async function generatePluginPackageJson(projectName, source) {
 	const versions = await nextlyVersions(source);
-	const runtimeVersions = await resolveRuntimeVersions();
 	const range = (pkg) => versions[pkg] ?? "alpha";
 	const peerRange = (pkg) => pluginPeerRange(range(pkg), source.cliVersion);
 	const peerDependencies = {
@@ -46606,8 +46761,8 @@ async function generatePluginPackageJson(projectName, source) {
 		"@nextlyhq/admin": peerRange("@nextlyhq/admin"),
 		"@nextlyhq/plugin-sdk": peerRange("@nextlyhq/plugin-sdk"),
 		"@nextlyhq/ui": peerRange("@nextlyhq/ui"),
-		react: PINNED_VERSIONS.react,
-		"react-dom": PINNED_VERSIONS["react-dom"]
+		react: SUPPORTED_RANGES.react,
+		"react-dom": SUPPORTED_RANGES["react-dom"]
 	};
 	const devDependencies = {
 		nextly: range("nextly"),
@@ -46616,9 +46771,9 @@ async function generatePluginPackageJson(projectName, source) {
 		"@nextlyhq/plugin-sdk": range("@nextlyhq/plugin-sdk"),
 		"@nextlyhq/adapter-drizzle": range("@nextlyhq/adapter-drizzle"),
 		"@nextlyhq/adapter-sqlite": range("@nextlyhq/adapter-sqlite"),
-		next: runtimeVersions.next,
-		react: PINNED_VERSIONS.react,
-		"react-dom": PINNED_VERSIONS["react-dom"],
+		next: scaffoldRange("next"),
+		react: scaffoldRange("react"),
+		"react-dom": scaffoldRange("react-dom"),
 		"better-sqlite3": "^12.0.0",
 		"@types/node": PINNED_VERSIONS["@types/node"],
 		"@types/react": PINNED_VERSIONS["@types/react"],
@@ -46936,6 +47091,143 @@ async function copyPluginTemplate(opts) {
 	await writeScaffoldNpmrc(targetDir, packageManager);
 	await replacePlaceholders(targetDir, placeholders, alreadyRendered);
 }
+// src/generators/page-extensions.ts
+/**
+* The page extension to name a new module file with, a hook or a route: a
+* TypeScript one first, since Nextly's files are TypeScript, then a
+* JavaScript one; never a content extension such as `mdx`, which Next.js
+* would compile as content, and never `cjs`, since the files are ES modules
+* and a `.cjs` file cannot hold one. Null when the list holds no extension a
+* module can be written in.
+*/
+function moduleExtension(extensions) {
+	const usable = writable(extensions);
+	return usable.find((extension) => /(^|\.)tsx?$/.test(extension)) ?? usable.find((extension) => /(^|\.)(js|jsx|mjs)$/.test(extension)) ?? null;
+}
+/**
+* The extensions a file with code in it can be written under: not a
+* declaration file's (`d.ts`, `d.mts`, `d.cts`), which TypeScript reads as
+* types only and refuses code in.
+*/
+function writable(extensions) {
+	return extensions.filter((extension) => !/(^|\.)d\.[cm]?tsx?$/.test(extension));
+}
+/**
+* The `pageExtensions` the app's Next.js config sets, as every existing-app
+* step that names a file Next.js routes reads it: the list; `"absent"` when
+* the config sets none, or there is no config; or null when it is set in a
+* way that cannot be read. Read from the config the app exports, as the Next
+* config step reads it, so a commented-out or nested `pageExtensions` sets
+* nothing. `configName` is the file it was read from, for the report.
+*/
+async function appPageExtensions(cwd) {
+	const nextConfig = await readNextConfig(cwd);
+	return {
+		configName: nextConfig?.name ?? "The Next.js config",
+		extensions: nextConfig ? configStringList(nextConfig.text, nextConfig.name, "pageExtensions") : "absent"
+	};
+}
+/**
+* The text of the app's Next.js config, or null when it has none, from the
+* file the Next config step reads and extends ({@link findConfigFile}).
+*/
+async function readNextConfig(cwd) {
+	const name = await findConfigFile(cwd);
+	return name === null ? null : {
+		name,
+		text: await import_lib$1.default.readFile(path.join(cwd, name), "utf-8")
+	};
+}
+/**
+* The page extension for a file of TypeScript with JSX, such as a page or a
+* layout: one ending in `tsx`. Null when the list holds none.
+*/
+function tsxExtension(extensions) {
+	return writable(extensions).find((extension) => /(^|\.)tsx$/.test(extension)) ?? null;
+}
+/** A JavaScript or TypeScript module without JSX, such as a route. */
+const MODULE_FILE = {
+	pick: moduleExtension,
+	holds: "a JavaScript or TypeScript extension"
+};
+/** TypeScript with JSX, such as a page or a layout. */
+const TSX_FILE = {
+	pick: tsxExtension,
+	holds: "an extension ending in tsx"
+};
+/**
+* The report for a file an app that sets `pageExtensions` gets in place of
+* the file: the name to create it under and its content. Next.js routes a
+* file there only under a name with one of the app's extensions, and the app
+* may already have the file under such a name, which the existing-app steps
+* do not look for, so nothing is written. A list that cannot be read, or that
+* holds no extension the content needs, gives a placeholder name and says
+* which.
+*
+* @param base the file's path without its extension, as reported, such as
+*   `app/admin/[[...params]]/page`
+*/
+function pageExtensionsSkip(base, text, pages, need) {
+	const { configName, extensions } = pages;
+	const extension = extensions === null ? null : need.pick(extensions);
+	const sets = `${configName} sets pageExtensions, and Next.js routes a file there only under a name with one of them, so none was written`;
+	if (extensions !== null && extension === null) return {
+		path: `${base}.<${need.holds} added to pageExtensions>`,
+		why: `${sets}, and none of them (${extensions.join(", ")}) is ${need.holds}; add one to pageExtensions, then, unless the app already has this file, create it under that name with this content`,
+		toAdd: text
+	};
+	return {
+		path: `${base}.${extension ?? "<one of your pageExtensions>"}`,
+		why: `${sets}; unless the app already has this file, create it under that name with this content`,
+		toAdd: text
+	};
+}
+// src/generators/write-new.ts
+/**
+* Writes `text` to `relative` (a project-relative path, written with `/`)
+* only where nothing is, and records which it was.
+*
+* The file is created exclusively (`wx`), so a file the app already has, a
+* link included, is never replaced, whatever appeared since any earlier
+* check. One that is there is reported as skipped, with why and, when given,
+* what to add to it by hand. `wx` guards only the file's own name, so a
+* folder on its path that is a symbolic link, which would take the write
+* wherever it points, is found first, as the media routes find it, and
+* nothing is written through it.
+*/
+async function writeNew(cwd, relative, text, files, ifThere) {
+	const file = path.join(cwd, ...relative.split("/"));
+	const link = await linkedFolder(cwd, file);
+	if (link !== null) {
+		const folder = path.relative(cwd, link.folder).split(path.sep).join("/");
+		files.skipped.push({
+			path: relative,
+			why: link.unreadable ? `${folder} cannot be read, so whether a folder in it is a symbolic link is unknown; nothing was written there` : `${folder} ${THROUGH_A_LINK}`,
+			toAdd: ifThere.toAdd
+		});
+		return;
+	}
+	await import_lib$1.default.ensureDir(path.dirname(file));
+	try {
+		await import_lib$1.default.writeFile(file, text, {
+			encoding: "utf-8",
+			flag: "wx"
+		});
+		files.written.push(relative);
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		files.skipped.push({
+			path: relative,
+			...ifThere
+		});
+	}
+}
+/** A step's report before it has done anything. */
+const nothingYet = () => ({
+	written: [],
+	changed: [],
+	skipped: []
+});
 // src/generators/routes.ts
 const API_ROUTE_TEMPLATE = `// Imported from \`nextly/runtime\` (not the package root) so the
 // Next.js-coupled handler factory stays out of Node-only code paths
@@ -47046,8 +47338,31 @@ const UPLOADS_ROUTE = {
 	importsConfig: true,
 	role: (file) => `Nextly's uploads route at ${file} serves files stored on local disk at /uploads, which a production server otherwise answers 404 for until it restarts`
 };
-/** Every route the existing-app path writes, read from the templates together. */
-const ALL_ROUTES = [...ROUTES, UPLOADS_ROUTE];
+/**
+* The admin's layout, which `generateAdminPage` writes beside the admin page.
+* Read with the routes, from the template a new project gets, so an app Nextly
+* is added to renders its admin the same way: its shell prerendered, and its
+* request work beneath a Suspense boundary.
+*/
+const ADMIN_LAYOUT = {
+	path: "admin/[[...params]]/layout.tsx",
+	importsConfig: true
+};
+/**
+* The admin component map's two generated files, under the app's source root,
+* as the base template commits them: the admin layout imports the list, and
+* the admin page imports the map that registers the components. Read with the
+* routes, so an app Nextly is added to starts from the template's own empty
+* map rather than a second one written out here, and `next dev` rewrites them
+* as plugins are added.
+*/
+const ADMIN_COMPONENT_MAP_FILES = ["types/generated/plugin-admin-components.generated.ts", "types/generated/plugin-admin-imports.generated.ts"];
+/** Every file the existing-app path writes from the templates, read together. */
+const ALL_ROUTES = [
+	...ROUTES,
+	UPLOADS_ROUTE,
+	ADMIN_LAYOUT
+];
 /**
 * The import that brings in the Nextly config: the template spells it through
 * the `@nextly-config` alias or a path relative to its own layout, neither of
@@ -47147,6 +47462,15 @@ async function readMediaRouteTemplates(templatesDir = resolveTemplatePath()) {
 		if (route.importsConfig && !CONFIG_IMPORT.test(text)) throw new Error(`The template's ${route.path} does not import the Nextly config, so no route that finds it can be written. Nothing was installed or written.`);
 		texts.set(route.path, text);
 	}
+	for (const file of ADMIN_COMPONENT_MAP_FILES) {
+		const relative = `base/src/${file}`;
+		try {
+			texts.set(file, await import_lib$1.default.readFile(path.join(templatesDir, relative), "utf-8"));
+		} catch (error) {
+			const code = error.code ?? "unreadable";
+			throw new Error(`The templates at ${templatesDir} have no readable ${relative} (${code}), so Nextly's admin component map cannot be added. Nothing was installed or written; check the --local-template path if one was given.`);
+		}
+	}
 	return texts;
 }
 /**
@@ -47597,56 +47921,71 @@ function skipped(cwd, left, target, text, role, reason) {
 function toPosix(p) {
 	return p.split(path.sep).join("/");
 }
-// src/generators/write-new.ts
+// src/generators/types.ts
 /**
-* Writes `text` to `relative` (a project-relative path, written with `/`)
-* only where nothing is, and records which it was.
-*
-* The file is created exclusively (`wx`), so a file the app already has, a
-* link included, is never replaced, whatever appeared since any earlier
-* check. One that is there is reported as skipped, with why and, when given,
-* what to add to it by hand. `wx` guards only the file's own name, so a
-* folder on its path that is a symbolic link, which would take the write
-* wherever it points, is found first, as the media routes find it, and
-* nothing is written through it.
+* Where the generated types file goes, relative to the project root: under
+* src/ when the app keeps its code there, at the root when it does not. The
+* config names this path and the types step creates it, so both read it here.
 */
-async function writeNew(cwd, relative, text, files, ifThere) {
-	const file = path.join(cwd, ...relative.split("/"));
-	const link = await linkedFolder(cwd, file);
-	if (link !== null) {
-		const folder = path.relative(cwd, link.folder).split(path.sep).join("/");
-		files.skipped.push({
-			path: relative,
-			why: link.unreadable ? `${folder} cannot be read, so whether a folder in it is a symbolic link is unknown; nothing was written there` : `${folder} ${THROUGH_A_LINK}`,
-			toAdd: ifThere.toAdd
-		});
-		return;
-	}
-	await import_lib$1.default.ensureDir(path.dirname(file));
-	try {
-		await import_lib$1.default.writeFile(file, text, {
-			encoding: "utf-8",
-			flag: "wx"
-		});
-		files.written.push(relative);
-	} catch (error) {
-		if (error.code !== "EEXIST") throw error;
-		files.skipped.push({
-			path: relative,
-			...ifThere
-		});
+function typesOutputFile(projectInfo) {
+	return `${projectInfo.srcDir ? "./src" : "."}/types/generated/nextly-types.ts`;
+}
+/**
+* The folder the generated files go in, relative to the project root, as
+* {@link typesOutputFile} names it: the admin layout and page import the
+* component map from here.
+*/
+function typesOutputFolder(projectInfo) {
+	return path.posix.dirname(path.posix.normalize(typesOutputFile(projectInfo)));
+}
+/**
+* Create the types directory structure for generated TypeScript types.
+* This mirrors what `nextly init` does - creates the directory and a placeholder file.
+* The actual types are generated when running `next dev` (which boots Nextly
+* and emits types lazily) or `npx nextly generate:types`.
+*/
+async function generateTypesDirectory(cwd, projectInfo, templates) {
+	const files = nothingYet();
+	const typesFile = path.posix.normalize(typesOutputFile(projectInfo));
+	const typesDir = typesOutputFolder(projectInfo);
+	await writeNew(cwd, `${typesDir}/.gitkeep`, "", files, { why: "it is already there" });
+	await writeNew(cwd, typesFile, `/**
+ * Nextly Generated Types
+ *
+ * This file will be auto-generated when you run:
+ *   next dev          (Nextly emits types on first boot)
+ *   npx nextly generate:types
+ *
+ * Do not edit this file manually - it will be overwritten.
+ */
+
+// Types will be generated here after running next dev
+export {};
+`, files, { why: "it is already there; Nextly writes the types into it when they are generated" });
+	for (const file of ADMIN_COMPONENT_MAP_FILES) {
+		const text = templates.get(file);
+		if (text === void 0) throw new Error(`The templates read for this app hold no ${file}, so Nextly's admin component map cannot be written.`);
+		await writeNew(cwd, `${typesDir}/${path.posix.basename(file)}`, text, files, { why: "it is already there; `next dev` and `nextly generate:types` keep it current" });
 	}
+	return files;
 }
-/** A step's report before it has done anything. */
-const nothingYet = () => ({
-	written: [],
-	changed: [],
-	skipped: []
-});
 // src/generators/admin.ts
-const ADMIN_PAGE_TEMPLATE = `"use client";
+/**
+* The generated component map's two files, by the name a module imports them
+* as: the list the layout reads, and the map the page loads to register the
+* components.
+*/
+const COMPONENT_LIST = "plugin-admin-components.generated";
+const COMPONENT_MAP = "plugin-admin-imports.generated";
+/** How the file at `target` imports `name` from the app's generated types folder. */
+function generatedImport(cwd, target, projectInfo, name) {
+	const relative = path.relative(path.dirname(target), path.join(cwd, typesOutputFolder(projectInfo), name)).split(path.sep).join("/");
+	return relative.startsWith(".") ? relative : `./${relative}`;
+}
+const adminPageTemplate = (componentMap) => `"use client";
 
 import "@nextlyhq/admin/style.css";
+import "${componentMap}";
 import { RootLayout, QueryProvider, ErrorBoundary } from "@nextlyhq/admin";
 
 export default function AdminPage() {
@@ -47664,92 +48003,42 @@ export default function AdminPage() {
 }
 `;
 /**
-* Generate the layout template with the correct relative import path
-* to nextly.config based on whether the project uses a src/ directory.
-*
-* With src/:    src/app/admin/[[...params]]/layout.tsx → ../../../../nextly.config
-* Without src:  app/admin/[[...params]]/layout.tsx     → ../../../nextly.config
+* The admin layout, as the base template holds it, with its config import
+* pointing at the project's `nextly.config`, and its component-list import at
+* the app's generated types folder, from where the layout is written. One
+* source with a new project's layout, so an app Nextly is added to gets the
+* same per-request admin.
 */
-function getAdminLayoutTemplate(srcDir) {
-	return `import { getBrandingCss } from "nextly/config";
-
-import config from "${srcDir ? "../../../../nextly.config" : "../../../nextly.config"}";
-
-const brandingCss = getBrandingCss(config.admin?.branding);
-
-export default function AdminLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  return (
-    <>
-      {brandingCss && (
-        <style dangerouslySetInnerHTML={{ __html: brandingCss }} />
-      )}
-      {children}
-    </>
-  );
-}
-`;
+function adminLayout(cwd, adminDir, projectInfo, templates) {
+	const text = templates.get(ADMIN_LAYOUT.path);
+	if (text === void 0) throw new Error(`The templates read for this app hold no ${ADMIN_LAYOUT.path}, so Nextly's admin layout cannot be written.`);
+	const target = path.join(cwd, adminDir, "layout.tsx");
+	return withRelativeConfigImport(text, cwd, target, ADMIN_LAYOUT.path).replace(new RegExp(`"[^"]*/${COMPONENT_LIST.replaceAll(".", "\\.")}"`), `"${generatedImport(cwd, target, projectInfo, COMPONENT_LIST)}"`);
 }
 /**
 * Generate the admin panel page and layout.
 * Uses [[...params]] to match the expected route pattern.
 */
-async function generateAdminPage(cwd, projectInfo) {
+async function generateAdminPage(cwd, projectInfo, templates) {
 	const files = nothingYet();
 	const adminDir = `${projectInfo.appDir}/admin/[[...params]]`;
-	const layout = getAdminLayoutTemplate(projectInfo.srcDir);
+	const layout = adminLayout(cwd, adminDir, projectInfo, templates);
+	const page = adminPageTemplate(generatedImport(cwd, path.join(cwd, adminDir, "page.tsx"), projectInfo, COMPONENT_MAP));
 	const pages = await appPageExtensions(cwd);
 	if (pages.extensions !== "absent") {
 		const { configName, extensions } = pages;
-		for (const [name, text] of [["page", ADMIN_PAGE_TEMPLATE], ["layout", layout]]) files.skipped.push(pageExtensionsSkip(`${adminDir}/${name}`, text, {
+		for (const [name, text] of [["page", page], ["layout", layout]]) files.skipped.push(pageExtensionsSkip(`${adminDir}/${name}`, text, {
 			configName,
 			extensions
 		}, TSX_FILE));
 		return files;
 	}
-	for (const [name, text] of [["page.tsx", ADMIN_PAGE_TEMPLATE], ["layout.tsx", layout]]) await writeNew(cwd, `${adminDir}/${name}`, text, files, {
+	for (const [name, text] of [["page.tsx", page], ["layout.tsx", layout]]) await writeNew(cwd, `${adminDir}/${name}`, text, files, {
 		why: `the app already has one; Nextly's admin needs its own ${name}, which is`,
 		toAdd: text
 	});
 	return files;
 }
-// src/generators/types.ts
-/**
-* Where the generated types file goes, relative to the project root: under
-* src/ when the app keeps its code there, at the root when it does not. The
-* config names this path and the types step creates it, so both read it here.
-*/
-function typesOutputFile(projectInfo) {
-	return `${projectInfo.srcDir ? "./src" : "."}/types/generated/nextly-types.ts`;
-}
-/**
-* Create the types directory structure for generated TypeScript types.
-* This mirrors what `nextly init` does - creates the directory and a placeholder file.
-* The actual types are generated when running `next dev` (which boots Nextly
-* and emits types lazily) or `npx nextly generate:types`.
-*/
-async function generateTypesDirectory(cwd, projectInfo) {
-	const files = nothingYet();
-	const typesFile = path.posix.normalize(typesOutputFile(projectInfo));
-	await writeNew(cwd, `${path.posix.dirname(typesFile)}/.gitkeep`, "", files, { why: "it is already there" });
-	await writeNew(cwd, typesFile, `/**
- * Nextly Generated Types
- *
- * This file will be auto-generated when you run:
- *   next dev          (Nextly emits types on first boot)
- *   npx nextly generate:types
- *
- * Do not edit this file manually - it will be overwritten.
- */
-
-// Types will be generated here after running next dev
-export {};
-`, files, { why: "it is already there; Nextly writes the types into it when they are generated" });
-	return files;
-}
 // src/generators/config.ts
 /**
 * Base templates for project types that use inline config generation.
@@ -47830,8 +48119,9 @@ function startNextly(configImport) {
   const { createRegister } = await import("nextly");
   const { default: config } = await import("${configImport}");
   // Next.js writes its Cache Components setting into this file as it builds
-  // it. Nextly, loaded from node_modules, cannot read that for itself, and
-  // warns when Cache Components is on, which it does not support yet.
+  // it. Nextly, loaded from node_modules, cannot read that for itself. With
+  // it off, Nextly warns at start; with it on, a cached read that finds no
+  // "use cache" read function says so.
   await createRegister(config, {
     cacheComponents: process.env.__NEXT_CACHE_COMPONENTS,
   })();`;
@@ -47929,10 +48219,7 @@ function pageExtensionsAdvice(dir, configImport, configName, extensions) {
 * never rewritten; it is reported as skipped with what to add. So is the case
 * where the app sets \`pageExtensions\`: Next.js then reads the hook only under a
 * name with one of those extensions, which this does not guess. The config file
-* itself is never edited here. Next.js 14 runs the hook only with
-* `experimental.instrumentationHook`, which the Next config step gives in the
-* same `experimental` object as Nextly's packages (`patchNextConfig`), so two
-* steps never hand the developer two objects for one key.
+* itself is never edited here.
 */
 async function generateInstrumentation(cwd, projectInfo) {
 	const dir = projectInfo.srcDir ? "src" : "";
@@ -47980,13 +48267,13 @@ async function generateIntoExistingApp(cwd, projectType, projectInfo, database,
 	return [
 		await generateConfig(cwd, projectType, projectInfo),
 		await generateRoutes(cwd, projectInfo),
-		await generateAdminPage(cwd, projectInfo),
+		await generateAdminPage(cwd, projectInfo, templates),
 		await generateMediaRoutes(cwd, projectInfo, templates),
 		await generateUploadsRoute(cwd, projectInfo, templates),
 		await generateInstrumentation(cwd, projectInfo),
-		await generateTypesDirectory(cwd, projectInfo),
+		await generateTypesDirectory(cwd, projectInfo, templates),
 		nextConfigFiles(await patchNextConfig(cwd, database)),
-		cacheComponentsFiles(await turnOffCacheComponents(cwd))
+		cacheComponentsFiles(await turnOnCacheComponents(cwd))
 	];
 }
 // src/generators/report.ts
@@ -50643,7 +50930,7 @@ var hr = Symbol("entry");
 var cs = Symbol("entryOpt");
 var ui = Symbol("writeEntryClass");
 var lr = Symbol("write");
-var fs$6 = Symbol("ondrain");
+var fs$7 = Symbol("ondrain");
 var wt = class extends A {
 	sync = !1;
 	opt;
@@ -50677,8 +50964,8 @@ var wt = class extends A {
 			if ((t.gzip ? 1 : 0) + (t.brotli ? 1 : 0) + (t.zstd ? 1 : 0) > 1) throw new TypeError("gzip, brotli, zstd are mutually exclusive");
 			if (t.gzip && (typeof t.gzip != "object" && (t.gzip = {}), this.portable && (t.gzip.portable = !0), this.zip = new ze(t.gzip)), t.brotli && (typeof t.brotli != "object" && (t.brotli = {}), this.zip = new We(t.brotli)), t.zstd && (typeof t.zstd != "object" && (t.zstd = {}), this.zip = new Ye(t.zstd)), !this.zip) throw new Error("impossible");
 			let e = this.zip;
-			e.on("data", (i) => super.write(i)), e.on("end", () => super.end()), e.on("drain", () => this[fs$6]()), this.on("resume", () => e.resume());
-		} else this.on("drain", this[fs$6]);
+			e.on("data", (i) => super.write(i)), e.on("end", () => super.end()), e.on("drain", () => this[fs$7]()), this.on("resume", () => e.resume());
+		} else this.on("drain", this[fs$7]);
 		this.noDirRecurse = !!t.noDirRecurse, this.follow = !!t.follow, this.noMtime = !!t.noMtime, t.mtime && (this.mtime = t.mtime), this.filter = typeof t.filter == "function" ? t.filter : () => !0, this[W] = new hi(), this[G] = 0, this.jobs = Number(t.jobs) || 4, this[Ee] = !1, this[me] = !1;
 	}
 	[lr](t) {
@@ -50806,7 +51093,7 @@ var wt = class extends A {
 			this.emit("error", e);
 		}
 	}
-	[fs$6]() {
+	[fs$7]() {
 		this[Et] && this[Et].entry && this[Et].entry.resume();
 	}
 	[di](t) {
@@ -51873,6 +52160,126 @@ async function cleanupDownload(source) {
 		await import_lib$1.default.remove(extractionRoot).catch(() => {});
 	}
 }
+// src/lib/framework-versions.ts
+/**
+* Whether an existing app's Next.js, React and React DOM are ones this
+* release of Nextly supports, and what to change when they are not.
+*
+* Nextly is reviewed against one Next.js major and one React major
+* (`SUPPORTED_RANGES`). An app below the floor or on a newer major would
+* install Nextly and then fail at build or at run time, so adding Nextly to
+* it stops before anything is written, saying what was found and the way on.
+*/
+/** The first spec the app's package.json gives `name`, in field order. */
+function declaredSpec(manifest, name) {
+	const fields = ["optionalDependencies", ...DEPENDENCY_FIELDS$1.filter((field) => field !== "optionalDependencies")];
+	for (const field of fields) {
+		const deps = manifest[field];
+		if (!deps || typeof deps !== "object") continue;
+		const spec = deps[name];
+		if (typeof spec === "string") return spec;
+	}
+}
+/**
+* The version an app is headed for, the one judged against the range: the
+* installed copy, unless the app's declaration points past it.
+*/
+function judgedVersion(installed, declared, supported) {
+	const lowestDeclared = declared !== void 0 ? lowestVersionIn(declared) : void 0;
+	const floor = lowestVersionIn(supported);
+	if (floor === void 0) return installed ?? lowestDeclared;
+	if (lowestDeclared !== void 0 && compareVersions(lowestDeclared, floor) > 0 && !satisfiesRange(lowestDeclared, supported)) return lowestDeclared;
+	const highest = declared !== void 0 ? highestMajorIn(declared) : void 0;
+	if (installed === void 0 && highest !== void 0 && highest > major(floor)) return `${major(floor) + 1}.0.0`;
+	return installed ?? lowestDeclared;
+}
+/**
+* Too new only on a later major than the range covers; anything else outside
+* it (below the floor, or a prerelease within the major) needs a supported
+* release of the same major. A range without a floor leaves nothing to
+* compare, and the version is then reported as too new.
+*/
+function directionOf(judged, supported) {
+	const floor = lowestVersionIn(supported);
+	return floor === void 0 || major(judged) > major(floor) ? "too-new" : "too-old";
+}
+/**
+* Every supported framework package the app at `cwd` has outside its range.
+*
+* The version judged is the one the app is headed for (`judgedVersion`): the
+* installed copy, read from the `node_modules` Node would load it from,
+* unless the app's package.json declaration points past it; with none
+* installed, what an install of that declaration could resolve to. A package
+* the app neither has installed nor declares in a form that names a version
+* (a dist-tag, `workspace:*`) is not judged.
+*/
+async function frameworkVersionProblems(cwd) {
+	const manifest = await import_lib$1.default.readJson(path.join(cwd, "package.json")).catch(() => ({}));
+	const problems = [];
+	for (const name of Object.keys(SUPPORTED_RANGES)) {
+		const supported = SUPPORTED_RANGES[name];
+		const installed = await installedVersion(cwd, name);
+		const declared = declaredSpec(manifest, name);
+		const judged = judgedVersion(installed, declared, supported);
+		if (judged === void 0 || satisfiesRange(judged, supported)) continue;
+		const direction = directionOf(judged, supported);
+		problems.push({
+			name,
+			installed,
+			declared,
+			supported,
+			judged,
+			direction
+		});
+	}
+	return problems;
+}
+const LABEL = {
+	next: "Next.js",
+	react: "React",
+	"react-dom": "React"
+};
+const major = (version) => Number(version.split(".")[0]);
+/** What `fix` reads from a problem: the supported major and the version found. */
+function majorsOf(problem) {
+	const floor = lowestVersionIn(problem.supported) ?? problem.supported;
+	return {
+		supportedMajor: major(floor),
+		foundMajor: major(problem.judged)
+	};
+}
+/** A version past the supported major: install that major, or wait for Nextly. */
+function tooNewFix(problem, add) {
+	const { supportedMajor, foundMajor } = majorsOf(problem);
+	const label = LABEL[problem.name];
+	return `This release of Nextly supports ${label} up to the ${supportedMajor}.x line. Install ${label} ${supportedMajor}, or wait for a Nextly release that supports ${label} ${foundMajor}:\n    ${add} ${problem.name === "next" ? `next@${supportedMajor}` : `react@${supportedMajor} react-dom@${supportedMajor}`}`;
+}
+/** A version below the supported floor: the codemod across a Next.js major, an install otherwise. */
+function tooOldFix(problem, add) {
+	const { supportedMajor, foundMajor } = majorsOf(problem);
+	if (problem.name === "next" && foundMajor < supportedMajor) return `Upgrade Next.js to ${REVIEWED_VERSIONS.next} with its codemod:\n    npx @next/codemod@latest upgrade ${REVIEWED_VERSIONS.next}`;
+	const install = problem.name === "next" ? `next@${problem.supported}` : `react@${SUPPORTED_RANGES.react} react-dom@${SUPPORTED_RANGES["react-dom"]}`;
+	return `Upgrade ${LABEL[problem.name]} to ${problem.supported}:\n    ${add} ${install}`;
+}
+/** The one step that brings `problem` into range, as a sentence and a command. */
+function fix(problem, pm) {
+	const add = ADD_COMMAND[pm];
+	return problem.direction === "too-new" ? tooNewFix(problem, add) : tooOldFix(problem, add);
+}
+/**
+* Why the run stopped: each package found, the range it falls outside, and
+* the change that brings it in. React and React DOM move together, so a
+* problem with both gives one command.
+*/
+function frameworkVersionMessage(problems, pm) {
+	const lines = problems.map(({ name, installed, declared, supported }) => {
+		return `  ${name}: ${[installed !== void 0 ? `installed ${installed}` : void 0, declared !== void 0 ? `declared ${declared}` : void 0].filter(Boolean).join(", ")}; supported ${supported}`;
+	});
+	const fixes = [...new Set(problems.map((problem) => fix(problem, pm)))];
+	return `This app's Next.js or React is outside what this release of Nextly supports:
+${lines.join("\n")}\n\nNothing was changed. Change the app as follows, then run create-nextly-app again:
+` + fixes.map((line) => `  ${line}`).join("\n");
+}
 // src/prompts/approach.ts
 /**
 * Labels shown in the CLI select prompt for each approach.
@@ -52313,6 +52720,16 @@ async function createNextly(options = {}) {
 	const existingProject = options.projectType !== "plugin" && await isExistingNextProject(cwd);
 	if (existingProject) {
 		R.success(`${import_picocolors.default.green("Next.js")} project detected`);
+		const frameworkProblems = await frameworkVersionProblems(cwd);
+		if (frameworkProblems.length > 0) {
+			capture("scaffold_failed", {
+				stage: "detect",
+				error_code: "unknown",
+				duration_ms: Date.now() - overallStartedAt
+			});
+			Nt$1(frameworkVersionMessage(frameworkProblems, await detectAppPackageManager(cwd)));
+			process.exit(1);
+		}
 		if (!defaults) {
 			const shouldInstall = await Rt$1({
 				message: "Install Nextly in this project?",
@@ -52655,4 +53072,4 @@ async function createNextly(options = {}) {
 }
 export { getAvailableTemplateNames as a, init as c, __require as d, __toESM$1 as f, validateTemplateName as i, shutdown as l, resolveProjectArg as n, packageVersion as o, validateProjectName as r, capture as s, createNextly as t, __commonJSMin$1 as u };
 
-//# sourceMappingURL=create-nextly-CyI8XgVc.mjs.map
+//# sourceMappingURL=create-nextly-ChHdzG83.mjs.map