@depup/nuxt__kit 4.4.2-depup.0 → 4.5.0-depup.0

package/dist/index.mjs

@@ -4,6 +4,10 @@ import { applyDefaults } from "untyped";
 import { consola } from "consola";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { getContext } from "unctx";
+import { createConsoleReporter, defineDiagnostics } from "nostics";
+import process from "node:process";
+import { ansiFormatter } from "nostics/formatters/ansi";
+import { colors } from "consola/utils";
 import satisfies from "semver/functions/satisfies.js";
 import { readPackageJSON, resolvePackageJSON } from "pkg-types";
 import { existsSync, lstatSync, promises, readFileSync } from "node:fs";
@@ -16,11 +20,10 @@ import { isRelative, withTrailingSlash, withoutTrailingSlash } from "ufo";
 import { read, update } from "rc9";
 import semver, { gte } from "semver";
 import { captureStackTrace } from "errx";
-import process from "node:process";
 import { glob } from "tinyglobby";
 import { resolveAlias as resolveAlias$1, reverseResolveAlias } from "pathe/utils";
 import ignore from "ignore";
-import { loadConfig } from "c12";
+import { loadConfig, setupDotenv } from "c12";
 import destr from "destr";
 import { kebabCase, pascalCase, snakeCase } from "scule";
 import { klona } from "klona";
@@ -32,6 +35,123 @@ function useLogger(tag, options = {}) {
 	return tag ? logger.create(options).withTag(tag) : logger;
 }
 //#endregion
+//#region src/diagnostics/_shared.ts
+/**
+* Resolve the docs URL for a stable `NUXT_B<NNNN>` code.
+*
+* Codes with a dedicated docs page pass this as their `see:` URL; codes whose
+* inline why+fix is self-sufficient opt out with `docs: false`.
+*/
+const docsBase = (code) => `https://nuxt.com/docs/4.x/errors/${code.replace("NUXT_", "").toLowerCase()}`;
+const reporters = [/* @__PURE__ */ createConsoleReporter(process.env.NODE_ENV === "test" ? void 0 : { formatter: ansiFormatter(colors) })];
+//#endregion
+//#region src/diagnostics/kit-api.ts
+/**
+* B8xxx
+* Kit API diagnostics.
+*/
+const kitDiagnostics = /* #__PURE__ */ defineDiagnostics({
+	docsBase,
+	reporters,
+	codes: {
+		NUXT_B8001: {
+			why: "The active Nuxt instance is unavailable in the current context.",
+			fix: "Call this within a Nuxt module `setup()` function, or inside a `nuxt.hook()` callback.",
+			docs: false
+		},
+		NUXT_B8002: {
+			why: "The `base` argument to `createResolver(base)` is missing.",
+			fix: "Pass `import.meta.url` or a directory path as the `base` argument to `createResolver()`.",
+			docs: false
+		},
+		NUXT_B8003: {
+			why: "Nitro is not initialized yet: `useNitro()` was called before the `ready` hook ran.",
+			fix: "Move the `useNitro()` call inside a hook that runs after initialization, such as `nuxt.hook('ready', () => { ... })`.",
+			docs: false
+		},
+		NUXT_B8004: {
+			why: (p) => `Nuxt compatibility issues were found:\n${p.issues}`,
+			fix: "Update the module to support the current Nuxt version, or check if a newer version of the module is available.",
+			docs: false
+		},
+		NUXT_B8005: {
+			why: "The Nuxt version cannot be determined: no current instance was passed.",
+			fix: "Pass a valid Nuxt instance to `getNuxtVersion()`, or ensure `useNuxt()` is available in the current context.",
+			docs: false
+		},
+		NUXT_B8006: {
+			why: (p) => `No Nuxt version could be found from \`${p.cwd}\`.`,
+			fix: "Run `npm install nuxt` in your project directory to install Nuxt.",
+			docs: false
+		},
+		NUXT_B8007: {
+			why: (p) => `The type template filename \`${p.template}\` is invalid.`,
+			fix: "Rename the template filename to end with `.d.ts`.",
+			docs: false
+		},
+		NUXT_B8008: {
+			why: (p) => `The template value is invalid: ${p.template}.`,
+			fix: "Pass a valid template object or a string path to `addTemplate()`.",
+			docs: false
+		},
+		NUXT_B8009: {
+			why: (p) => `The template was not found at \`${p.template}\`.`,
+			fix: "Check that the `src` path exists and is an absolute path or resolvable from the module directory.",
+			docs: false
+		},
+		NUXT_B8010: {
+			why: (p) => `The template \`${p.template}\` provides neither \`getContents\` nor \`src\`.`,
+			fix: "Add a `getContents` function or a `src` path to the template object.",
+			docs: false
+		},
+		NUXT_B8011: {
+			why: (p) => `The template is missing a \`filename\`: ${p.template}.`,
+			fix: "Add a `filename` property to the template object, or provide a `src` path so the filename can be derived from it.",
+			docs: false
+		},
+		NUXT_B8012: {
+			why: (p) => `\`${p.name}\` was used outside of a Nuxt context.`,
+			fix: "Register this module in the `modules` array of `nuxt.config` rather than calling it directly.",
+			docs: false
+		},
+		NUXT_B8013: {
+			why: (p) => p.message,
+			fix: "Update the module to a version that supports the current Nuxt version, or set `experimental.enforceModuleCompatibility` to `true` to make this a fatal error.",
+			docs: false
+		},
+		NUXT_B8014: {
+			why: (p) => `Module \`${p.name}\` was slow to set up, taking \`${p.time}ms\`.`,
+			fix: "Defer expensive operations to a later hook (e.g. `build:before`) to reduce startup time.",
+			docs: false
+		},
+		NUXT_B8015: {
+			why: (p) => `A Nuxt module must be a function or a string to import. Received: \`${p.received}\`.`,
+			fix: "Pass a module function or a string package name to the `modules` array in `nuxt.config`.",
+			docs: false
+		},
+		NUXT_B8016: {
+			why: (p) => `The Nuxt module \`${p.module}\` is not a function.`,
+			fix: "Ensure the module has a default export that is a function, using `defineNuxtModule()` to create a valid module.",
+			docs: false
+		},
+		NUXT_B8017: {
+			why: (p) => `The module \`${p.module}\` could not be loaded. It may not be installed.`,
+			fix: (p) => `Run \`npm install ${p.module}\` to install it.`,
+			docs: false
+		},
+		NUXT_B8018: {
+			why: (p) => `An error occurred while importing the module \`${p.module}\`: ${p.error}.`,
+			fix: "A sub-dependency of this module is missing. Install it, or check that the module is compatible with the current environment.",
+			docs: false
+		},
+		NUXT_B8019: {
+			why: (p) => `An error occurred while executing the ${p.phase} hook for module \`${p.name}\`: ${p.error}.`,
+			fix: "Check the module's install/upgrade hook implementation, or report this issue to the module author.",
+			docs: false
+		}
+	}
+});
+//#endregion
 //#region src/context.ts
 /**
 * Direct access to the Nuxt global context - see https://github.com/unjs/unctx.
@@ -56,7 +176,7 @@ const getNuxtCtx = () => asyncNuxtStorage.tryUse();
 */
 function useNuxt() {
 	const instance = asyncNuxtStorage.tryUse() || nuxtCtx.tryUse();
-	if (!instance) throw new Error("Nuxt instance is unavailable!");
+	if (!instance) throw kitDiagnostics.NUXT_B8001();
 	return instance;
 }
 /**
@@ -136,7 +256,7 @@ async function checkNuxtCompatibility(constraints, nuxt = useNuxt()) {
 */
 async function assertNuxtCompatibility(constraints, nuxt = useNuxt()) {
 	const issues = await checkNuxtCompatibility(constraints, nuxt);
-	if (issues.length) throw new Error("Nuxt compatibility issues found:\n" + issues.toString());
+	if (issues.length) throw kitDiagnostics.NUXT_B8004({ issues: issues.toString() });
 	return true;
 }
 /**
@@ -170,7 +290,7 @@ const NUXT_VERSION_RE = /^v/g;
 */
 function getNuxtVersion(nuxt = useNuxt()) {
 	const rawVersion = nuxt?._version || nuxt?.version || nuxt?.constructor?.version;
-	if (typeof rawVersion !== "string") throw new TypeError("Cannot determine nuxt version! Is current instance passed?");
+	if (typeof rawVersion !== "string") throw kitDiagnostics.NUXT_B8005();
 	return rawVersion.replace(NUXT_VERSION_RE, "");
 }
 //#endregion
@@ -194,7 +314,7 @@ function _defineNuxtModule(definition) {
 		return module.moduleDependencies;
 	}
 	async function normalizedModule(inlineOptions, nuxt = tryUseNuxt()) {
-		if (!nuxt) throw new TypeError(`Cannot use ${module.meta.name || "module"} outside of Nuxt context`);
+		if (!nuxt) throw kitDiagnostics.NUXT_B8012({ name: module.meta.name || "module" });
 		const uniqueKey = module.meta.name || module.meta.configKey;
 		if (uniqueKey) {
 			nuxt.options._requiredModules ||= {};
@@ -210,7 +330,7 @@ function _defineNuxtModule(definition) {
 					error.name = "ModuleCompatibilityError";
 					throw error;
 				}
-				logger.warn(errorMessage);
+				kitDiagnostics.NUXT_B8013({ message: errorMessage });
 				return;
 			}
 		}
@@ -219,7 +339,7 @@ function _defineNuxtModule(definition) {
 		const moduleName = uniqueKey || module.meta.name || "<no name>";
 		nuxt._perf?.startPhase(`module:${moduleName}`);
 		const start = performance.now();
-		let res = {};
+		let res;
 		try {
 			res = await module.setup?.call(null, _options, nuxt) ?? {};
 		} finally {
@@ -227,7 +347,10 @@ function _defineNuxtModule(definition) {
 		}
 		const perf = performance.now() - start;
 		const setupTime = Math.round(perf * 100) / 100;
-		if (setupTime > 5e3 && uniqueKey !== "@nuxt/telemetry") logger.warn(`Slow module \`${moduleName}\` took \`${setupTime}ms\` to setup.`);
+		if (setupTime > 5e3 && uniqueKey !== "@nuxt/telemetry") kitDiagnostics.NUXT_B8014({
+			name: moduleName,
+			time: setupTime
+		});
 		else if (nuxt.options.debug && nuxt.options.debug.modules) logger.info(`Module \`${moduleName}\` took \`${setupTime}ms\` to setup.`);
 		if (res === false) return false;
 		return defu(res, { timings: { setup: setupTime } });
@@ -303,6 +426,7 @@ function withTrailingSlash$2(dir) {
 function createIsIgnored(nuxt = tryUseNuxt()) {
 	return (pathname, stats) => isIgnored(pathname, stats, nuxt);
 }
+const layerRootsCache = /* @__PURE__ */ new WeakMap();
 /**
 * Return a filter function to filter an array of paths
 */
@@ -312,7 +436,16 @@ function isIgnored(pathname, _stats, nuxt = tryUseNuxt()) {
 		nuxt._ignore = ignore(nuxt.options.ignoreOptions);
 		nuxt._ignore.add(resolveIgnorePatterns());
 	}
-	const relativePath = relative(getLayerDirectories(nuxt).map((dirs) => dirs.root).sort((a, b) => b.length - a.length).find((cwd) => pathname.startsWith(cwd)) ?? nuxt.options.rootDir, pathname);
+	let cwds = layerRootsCache.get(nuxt);
+	if (!cwds) {
+		cwds = getLayerDirectories(nuxt).map((dirs) => dirs.root).sort((a, b) => b.length - a.length);
+		layerRootsCache.set(nuxt, cwds);
+	}
+	for (const cwd of cwds) if (pathname.startsWith(cwd)) {
+		const relativePath = pathname.slice(cwd.length);
+		return !!(relativePath && nuxt._ignore.ignores(relativePath));
+	}
+	const relativePath = relative(nuxt.options.rootDir, pathname);
 	if (relativePath[0] === "." && relativePath[1] === ".") return false;
 	return !!(relativePath && nuxt._ignore.ignores(relativePath));
 }
@@ -392,11 +525,12 @@ async function resolvePath(path, opts = {}) {
 */
 async function findPath(paths, opts, pathType = "file") {
 	for (const path of toArray(paths)) {
+		const type = opts?.type || pathType;
 		const res = await _resolvePathGranularly(path, {
 			...opts,
-			type: opts?.type || pathType
+			type
 		});
-		if (!res.type || pathType && res.type !== pathType) continue;
+		if (!res.type || res.type !== type) continue;
 		if (res.virtual || await existsSensitive(res.path)) return res.path;
 	}
 	return null;
@@ -412,7 +546,7 @@ function resolveAlias(path, alias) {
 * Create a relative resolver
 */
 function createResolver(base) {
-	if (!base) throw new Error("`base` argument is missing for createResolver(base)!");
+	if (!base) throw kitDiagnostics.NUXT_B8002();
 	base = base.toString();
 	if (base.startsWith("file://")) base = dirname(fileURLToPath(base));
 	return {
@@ -449,17 +583,12 @@ async function _resolvePathType(path, opts = {}, skipFs = false) {
 		virtual: true
 	};
 	if (skipFs) return;
-	const fd = await promises.open(path, "r").catch(() => null);
-	try {
-		const stats = await fd?.stat();
-		if (stats) return {
-			path,
-			type: stats.isFile() ? "file" : "dir",
-			virtual: false
-		};
-	} finally {
-		fd?.close();
-	}
+	const stats = await promises.stat(path).catch(() => null);
+	if (stats) return {
+		path,
+		type: stats.isFile() ? "file" : "dir",
+		virtual: false
+	};
 }
 function normalizeExtension(ext) {
 	return ext.startsWith(".") ? ext : `.${ext}`;
@@ -585,7 +714,7 @@ function tryRequireModule(id, opts) {
 //#endregion
 //#region src/module/install.ts
 const NODE_MODULES_RE = /[/\\]node_modules[/\\]/;
-const ignoredConfigKeys = new Set([
+const ignoredConfigKeys = /* @__PURE__ */ new Set([
 	"components",
 	"imports",
 	"pages",
@@ -605,6 +734,8 @@ async function installModules(modulesToInstall, resolvedModulePaths, nuxt = useN
 	nuxt._moduleOptionsFunctions ||= /* @__PURE__ */ new Map();
 	const resolvedModules = [];
 	const modulesByMetaName = /* @__PURE__ */ new Map();
+	const moduleLoadCache = /* @__PURE__ */ new Map();
+	for (const [key] of modulesToInstall) moduleLoadCache.set(key, loadNuxtModuleInstance(key, nuxt));
 	const inlineConfigKeys = new Set(await Promise.all([...modulesToInstall].map(async ([mod]) => {
 		if (typeof mod === "string") return;
 		const meta = await Promise.resolve(mod.getMeta?.());
@@ -617,7 +748,7 @@ async function installModules(modulesToInstall, resolvedModulePaths, nuxt = useN
 	let error;
 	const dependencyMap = /* @__PURE__ */ new Map();
 	for (const [key, options] of modulesToInstall) {
-		const res = await loadNuxtModuleInstance(key, nuxt).catch((err) => {
+		const res = await (moduleLoadCache.get(key) || loadNuxtModuleInstance(key, nuxt)).catch((err) => {
 			if (dependencyMap.has(key) && typeof key === "string") err.cause = `Could not resolve \`${key}\` (specified as a dependency of ${dependencyMap.get(key)}).`;
 			throw err;
 		});
@@ -667,7 +798,7 @@ async function installModules(modulesToInstall, resolvedModulePaths, nuxt = useN
 	if (error) throw error;
 	for (const { nuxtModule, meta = {}, moduleToInstall, buildTimeModuleMeta, resolvedModulePath, inlineOptions } of resolvedModules) {
 		const configKey = meta.configKey;
-		const optionsFns = new Set([
+		const optionsFns = /* @__PURE__ */ new Set([
 			...nuxt._moduleOptionsFunctions.get(moduleToInstall) || [],
 			...meta?.name ? nuxt._moduleOptionsFunctions.get(meta.name) || [] : [],
 			...configKey ? nuxt._moduleOptionsFunctions.get(configKey) || [] : []
@@ -762,14 +893,24 @@ function resolveModuleWithOptions(definition, nuxt) {
 		options
 	};
 }
+let _jitiCache;
+function getSharedJiti(nuxt) {
+	_jitiCache ||= /* @__PURE__ */ new WeakMap();
+	let jiti = _jitiCache.get(nuxt);
+	if (!jiti) {
+		jiti = createJiti(nuxt.options.rootDir, { alias: nuxt.options.alias });
+		_jitiCache.set(nuxt, jiti);
+	}
+	return jiti;
+}
 async function loadNuxtModuleInstance(nuxtModule, nuxt = useNuxt()) {
 	let buildTimeModuleMeta = {};
 	if (typeof nuxtModule === "function") return {
 		nuxtModule,
 		buildTimeModuleMeta
 	};
-	if (typeof nuxtModule !== "string") throw new TypeError(`Nuxt module should be a function or a string to import. Received: ${nuxtModule}.`);
-	const jiti = createJiti(nuxt.options.rootDir, { alias: nuxt.options.alias });
+	if (typeof nuxtModule !== "string") throw kitDiagnostics.NUXT_B8015({ received: `${typeof nuxtModule} (${JSON.stringify(nuxtModule)})` });
+	const jiti = getSharedJiti(nuxt);
 	nuxtModule = resolveAlias(nuxtModule, nuxt.options.alias);
 	if (isRelative(nuxtModule)) nuxtModule = resolve(nuxt.options.rootDir, nuxtModule);
 	try {
@@ -794,7 +935,7 @@ async function loadNuxtModuleInstance(nuxtModule, nuxt = useNuxt()) {
 		});
 		const resolvedModulePath = fileURLToPath(src);
 		const resolvedNuxtModule = await jiti.import(src, { default: true });
-		if (typeof resolvedNuxtModule !== "function") throw new TypeError(`Nuxt module should be a function: ${nuxtModule}.`);
+		if (typeof resolvedNuxtModule !== "function") throw kitDiagnostics.NUXT_B8016({ module: nuxtModule });
 		const moduleMetadataPath = new URL("module.json", src);
 		if (existsSync(moduleMetadataPath)) buildTimeModuleMeta = JSON.parse(await promises.readFile(moduleMetadataPath, "utf-8"));
 		return {
@@ -804,13 +945,20 @@ async function loadNuxtModuleInstance(nuxtModule, nuxt = useNuxt()) {
 		};
 	} catch (error) {
 		const code = error.code;
-		if (code === "ERR_PACKAGE_PATH_NOT_EXPORTED" || code === "ERR_UNSUPPORTED_DIR_IMPORT" || code === "ENOTDIR") throw new TypeError(`Could not load \`${nuxtModule}\`. Is it installed?`);
+		if (code === "ERR_PACKAGE_PATH_NOT_EXPORTED" || code === "ERR_UNSUPPORTED_DIR_IMPORT" || code === "ENOTDIR") throw kitDiagnostics.NUXT_B8017({
+			module: nuxtModule,
+			cause: error
+		});
 		if (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") {
 			const module = MissingModuleMatcher.exec(error.message)?.[1];
-			if (module && !module.includes(nuxtModule)) throw new TypeError(`Error while importing module \`${nuxtModule}\`: ${error}`);
+			if (module && !module.includes(nuxtModule)) throw kitDiagnostics.NUXT_B8018({
+				module: nuxtModule,
+				error: String(error),
+				cause: error
+			});
 		}
 	}
-	throw new TypeError(`Could not load \`${nuxtModule}\`. Is it installed?`);
+	throw kitDiagnostics.NUXT_B8017({ module: nuxtModule });
 }
 function getDirectory(p) {
 	try {
@@ -837,7 +985,11 @@ async function callLifecycleHooks(nuxtModule, meta = {}, inlineOptions, nuxt = u
 			name: ".nuxtrc"
 		});
 	} catch (e) {
-		logger.error(`Error while executing ${!previousVersion ? "install" : "upgrade"} hook for module \`${meta.name}\`: ${e}`);
+		kitDiagnostics.NUXT_B8019({
+			phase: !previousVersion ? "install" : "upgrade",
+			name: meta.name,
+			error: String(e)
+		});
 	}
 }
 async function callModule(nuxt, nuxtModule, moduleOptions = {}, options) {
@@ -926,6 +1078,11 @@ async function loadNuxtConfig(opts) {
 		cwd: opts.cwd || process.cwd()
 	})).map((d) => withTrailingSlash(d)).sort((a, b) => b.localeCompare(a));
 	opts.overrides = defu(opts.overrides, { _extends: localLayers });
+	if (opts.dotenv !== false) await setupDotenv({
+		cwd: opts.cwd || process.cwd(),
+		...typeof opts.dotenv === "object" ? opts.dotenv : {}
+	});
+	const schemaPromise = loadNuxtSchema(opts.cwd || process.cwd());
 	const { configFile, layers = [], cwd, config: nuxtConfig, meta } = await withDefineNuxtConfig(() => loadConfig({
 		name: "nuxt",
 		configFile: "nuxt.config",
@@ -935,15 +1092,16 @@ async function loadNuxtConfig(opts) {
 			"_extends",
 			"extends"
 		] },
-		dotenv: true,
 		globalRc: true,
 		merger,
-		...opts
+		...opts,
+		dotenv: false
 	}));
 	nuxtConfig.rootDir ||= cwd;
 	nuxtConfig._nuxtConfigFile = configFile;
 	nuxtConfig._nuxtConfigFiles = [configFile];
 	nuxtConfig._loadOptions = opts;
+	if (typeof opts.envName === "string") nuxtConfig.envName = opts.envName;
 	nuxtConfig.alias ||= {};
 	if (meta?.name) {
 		const alias = `#layers/${meta.name}`;
@@ -951,7 +1109,7 @@ async function loadNuxtConfig(opts) {
 	}
 	const defaultBuildDir = join(nuxtConfig.rootDir, ".nuxt");
 	if (!opts.overrides?._prepare && !nuxtConfig.dev && !nuxtConfig.buildDir && existsSync(defaultBuildDir)) nuxtConfig.buildDir = join(nuxtConfig.rootDir, "node_modules/.cache/nuxt/.nuxt");
-	const NuxtConfigSchema = await loadNuxtSchema(nuxtConfig.rootDir || cwd || process.cwd());
+	const NuxtConfigSchema = await schemaPromise;
 	const layerSchemaKeys = [
 		"future",
 		"srcDir",
@@ -1045,7 +1203,7 @@ async function loadNuxt(opts) {
 		});
 		return path && path.length > resolvedPath.length ? path : resolvedPath;
 	}, "");
-	if (!resolvedPath) throw new Error(`Cannot find any nuxt version from ${opts.cwd}`);
+	if (!resolvedPath) throw kitDiagnostics.NUXT_B8006({ cwd: opts.cwd });
 	const { loadNuxt } = await import(pathToFileURL(resolvedPath).href).then((r) => interopDefault(r));
 	return await loadNuxt(opts);
 }
@@ -1078,6 +1236,16 @@ function addImportsSources(presets) {
 	});
 }
 //#endregion
+//#region src/app-config.ts
+/**
+* Update Nuxt app configuration.
+* @since 4.5.0
+*/
+function updateAppConfig(appConfig) {
+	const nuxt = useNuxt();
+	Object.assign(nuxt.options.appConfig, defu(appConfig, nuxt.options.appConfig));
+}
+//#endregion
 //#region src/nitro.ts
 const HANDLER_METHOD_RE = /\.(get|head|patch|post|put|delete|connect|options|trace)(\.\w+)*$/;
 /**
@@ -1141,7 +1309,7 @@ function addPrerenderRoutes(routes) {
 */
 function useNitro() {
 	const nuxt = useNuxt();
-	if (!nuxt._nitro) throw new Error("Nitro is not initialized yet. You can call `useNitro()` only after `ready` hook.");
+	if (!nuxt._nitro) throw kitDiagnostics.NUXT_B8003();
 	return nuxt._nitro;
 }
 /**
@@ -1342,6 +1510,91 @@ function addBuildPlugin(pluginFactory, options) {
 	if (pluginFactory.webpack) addWebpackPlugin(pluginFactory.webpack, options);
 	if (pluginFactory.rspack) addRspackPlugin(pluginFactory.rspack, options);
 }
+/**
+* Set the build output for the given key. See {@link NuxtBuildOutputs}.
+*/
+function setBuildOutput(key, provider, nuxt = useNuxt()) {
+	nuxt.buildOutputs[key] = provider;
+}
+//#endregion
+//#region src/diagnostics/components.ts
+/**
+* B3xxx
+* Component diagnostics.
+*
+* @internal
+*/
+const componentDiagnostics = /* #__PURE__ */ defineDiagnostics({
+	docsBase,
+	reporters,
+	codes: {
+		NUXT_B3001: {
+			why: (p) => `Components directory not found: \`${p.dirPath}\`.`,
+			fix: "If this is intentional, remove it from `components.dirs` in your `nuxt.config`.",
+			docs: false
+		},
+		NUXT_B3002: {
+			why: (p) => `Using server component \`${p.component}\` with \`ssr: false\` is not supported with auto-detected component islands.`,
+			fix: "Set `experimental.componentIslands` to `true` in your `nuxt.config`, or convert the component to a client component.",
+			docs: false
+		},
+		NUXT_B3003: {
+			why: (p) => `Standalone server components (\`${p.component}\`) are not yet supported without enabling \`experimental.componentIslands\`.`,
+			fix: "Set `experimental.componentIslands` to `true` in your `nuxt.config`.",
+			docs: false
+		},
+		NUXT_B3004: {
+			why: (p) => `\`${p.file}\` is using \`${p.component}\` which requires \`${p.requiredModule}\`.`,
+			fix: (p) => `Run \`npx nuxt add ${p.requiredModule}\` to install it.`,
+			docs: false
+		},
+		NUXT_B3005: {
+			why: (p) => `Multiple hydration strategies are not supported in the same component \`<${p.component}>\` in \`${p.file}\`.`,
+			fix: "Use only one hydration strategy attribute (e.g. `hydrate-on-visible` or `hydrate-on-idle`) per component.",
+			docs: false
+		},
+		NUXT_B3006: {
+			why: (p) => `Component \`<${p.component}>\` (used in \`${p.file}\`) has lazy-hydration props but is not declared as a lazy component.`,
+			fix: (p) => `Rename it to \`<${p.lazyName} />\` or remove the lazy-hydration props.`,
+			docs: false
+		},
+		NUXT_B3007: {
+			why: (p) => `Using the \`nuxt-client\` attribute (in \`${p.file}\`) to render client components within islands requires \`experimental.componentIslands.selectiveClient\` to be enabled.`,
+			fix: "Set `experimental.componentIslands.selectiveClient` to `true` in your `nuxt.config`.",
+			docs: false
+		},
+		NUXT_B3008: {
+			why: (p) => `Components not scanned from \`${p.scannedPath}\`, likely due to a directory casing mismatch.`,
+			fix: (p) => `Rename the directory from \`${p.scannedPath}\` to \`${p.expectedPath}\` to match the expected casing.`,
+			docs: false
+		},
+		NUXT_B3009: {
+			why: (p) => `The component \`${p.component}\` (in \`${p.filePath}\`) is using the reserved "Lazy" prefix used for dynamic imports, which may cause it to break at runtime.`,
+			fix: "Rename the component to avoid the `Lazy` prefix.",
+			docs: false
+		},
+		NUXT_B3010: {
+			why: (p) => `Component did not resolve to a file name in \`${p.filePath}\`.`,
+			fix: "Rename the component file to something other than `index` (e.g. `MyComponent.vue`).",
+			docs: false
+		},
+		NUXT_B3011: {
+			why: (p) => `Two component files resolving to the same name \`${p.component}\`:\n\n - ${p.filePath}\n - ${p.duplicatePath}`,
+			fix: "Rename one of the files or adjust the `components.dirs` prefix settings in your `nuxt.config`.",
+			docs: false
+		},
+		NUXT_B3012: {
+			why: (p) => `Overriding ${p.name} component.`,
+			fix: "Specify a `priority` option when calling `addComponent` to avoid this warning.",
+			docs: false
+		},
+		NUXT_B3013: {
+			why: (p) => `Rendering client components within islands via the \`nuxt-client\` attribute (in \`${p.file}\`) is only supported with the Vite builder.`,
+			fix: "Switch to the Vite builder with `builder: 'vite'` in your `nuxt.config`.",
+			docs: false
+		}
+	}
+});
 //#endregion
 //#region src/components.ts
 /**
@@ -1391,7 +1644,7 @@ function addComponents(addedComponents) {
 				if (newPriority < existingPriority) continue;
 				if (newPriority === existingPriority) {
 					const name = existingComponent.pascalName || existingComponent.kebabName;
-					logger.warn(`Overriding ${name} component. You can specify a \`priority\` option when calling \`addComponent\` to avoid this warning.`);
+					componentDiagnostics.NUXT_B3012({ name });
 				}
 				components.splice(existingComponentIndex, 1, component);
 			} else components.push(component);
@@ -1419,6 +1672,174 @@ function normalizeComponent(opts) {
 	};
 }
 //#endregion
+//#region src/diagnostics/pages.ts
+/**
+* B4xxx
+* Pages / routing diagnostics.
+*
+* @internal
+*/
+const pageDiagnostics = /* #__PURE__ */ defineDiagnostics({
+	docsBase,
+	reporters,
+	codes: {
+		NUXT_B4001: {
+			why: (p) => `The file \`${p.pathname}\` is empty, so it cannot be a valid page.`,
+			fix: "Add a `<template>` block to the page file, or remove the empty file from the `pages/` directory.",
+			docs: false
+		},
+		NUXT_B4002: {
+			why: "An `await` expression is used in a variable referenced by `definePageMeta`, which runs synchronously.",
+			fix: (p) => `Move the \`await\` outside of variables referenced in \`definePageMeta\`, or use a static value instead (near offset ${p.offset}): ${p.codeSnippet}`,
+			docs: false
+		},
+		NUXT_B4003: {
+			why: (p) => `\`definePageMeta()\` is called ${p.callCount} times in \`${p.file}\`, but only one call is allowed.`,
+			fix: "Merge all `definePageMeta()` calls into a single call.",
+			docs: false
+		},
+		NUXT_B4004: {
+			why: (p) => `The route name generated for \`${p.file}\` collides with the one already generated for \`${p.existingFile}\`.`,
+			fix: "Set a custom name using `definePageMeta` within one of the page files.",
+			docs: false
+		},
+		NUXT_B4005: {
+			why: (p) => `\`${p.fnName}\` was called with a \`${p.receivedType}\` instead of an object literal (reading \`${p.file}\`).`,
+			fix: (p) => `Pass a plain object literal to \`${p.fnName}()\`, e.g. \`${p.fnName}({ ... })\`. Variables and function calls are not supported.`,
+			docs: false
+		},
+		NUXT_B4006: {
+			why: (p) => `\`${p.fnName}\` was called with a non-serializable object literal (reading \`${p.file}\`).`,
+			fix: "Use only JSON-serializable values (strings, numbers, booleans, arrays, plain objects) in `defineRouteRules()`.",
+			docs: false
+		},
+		NUXT_B4008: {
+			why: "Server pages with `ssr: false` are not supported while component islands are auto-detected.",
+			fix: "Set `experimental.componentIslands` to `true`.",
+			docs: false
+		},
+		NUXT_B4009: {
+			why: (p) => `No layout name could be resolved for \`${p.file}\` (\`index\` is ignored for the purpose of creating a layout name).`,
+			fix: "Rename the layout file to something other than `index` (e.g. `layouts/default.vue`).",
+			docs: false
+		},
+		NUXT_B4010: {
+			why: (p) => `No middleware name could be resolved for \`${p.file}\` (\`index\` is ignored for the purpose of creating a middleware name).`,
+			fix: "Rename the middleware file to something other than `index` (e.g. `middleware/auth.ts`).",
+			docs: false
+		},
+		NUXT_B4011: {
+			why: (p) => `While building the page tree: ${p.message}`,
+			fix: "Check the page file naming and directory structure for issues.",
+			docs: false
+		},
+		NUXT_B4012: {
+			why: (p) => `The incremental route update for \`${p.event}\` on \`${p.path}\` failed, so a full rebuild was performed.`,
+			fix: "This is usually harmless: the full rebuild will recover. If it happens repeatedly, check for unusual file naming in `pages/`.",
+			docs: false
+		},
+		NUXT_B4013: {
+			why: (p) => `A \`${p.name}\` middleware already exists at \`${p.foundPath}\`.`,
+			fix: "Set `override: true` to replace it.",
+			docs: false
+		},
+		NUXT_B4014: {
+			why: (p) => `Layout \`${p.layoutName}\` is already provided by \`${p.existingPath}\` and was not overridden with \`${p.newPath}\`.`,
+			fix: "Rename one of the layouts, or remove the duplicate layout registration.",
+			docs: false
+		}
+	}
+});
+//#endregion
+//#region src/types.ts
+const TYPE_RESOLVE_OPTIONS = {
+	conditions: [
+		"types",
+		"import",
+		"require"
+	],
+	extensions: [
+		".js",
+		".mjs",
+		".cjs",
+		".ts",
+		".mts",
+		".cts"
+	]
+};
+const STRIPPABLE_EXT_RE = /\b\.(?:d\.ts|tsx?|jsx?)$/;
+const RUNTIME_EXT_RE = /(?<!\.d)\.([cm])(?:ts|js)$/;
+function isFile(path) {
+	return promises.stat(path).then((s) => s.isFile(), () => false);
+}
+/**
+* Rewrite a resolved module path to the declaration file TypeScript will load for it.
+*
+* A `.d.ts` / `.d.mts` / `.d.cts` or `.ts` / `.tsx` path is returned unchanged (or with
+* the extension stripped, where TypeScript's extensionless `paths` retry will find it).
+* A `.mjs` / `.cjs` / `.mts` / `.cts` runtime path is rewritten to an adjacent declaration
+* sibling when one exists; otherwise it is returned as-is for the caller to handle.
+*/
+async function resolveDeclarationPath(absolutePath) {
+	const stripped = absolutePath.replace(STRIPPABLE_EXT_RE, "");
+	if (stripped !== absolutePath) return stripped;
+	const runtimeMatch = absolutePath.match(RUNTIME_EXT_RE);
+	if (runtimeMatch) {
+		const base = absolutePath.slice(0, -runtimeMatch[0].length);
+		if (await isFile(`${base}.d.ts`)) return base;
+		const declaration = `${base}.d.${runtimeMatch[1]}ts`;
+		if (await isFile(declaration)) return declaration;
+	}
+	return absolutePath;
+}
+/** Extract the package name (including scope) from a (possibly subpath) module specifier. */
+function packageName(specifier) {
+	const segments = specifier.split("/");
+	return specifier[0] === "@" ? segments.slice(0, 2).join("/") : segments[0];
+}
+const rootCache = /* @__PURE__ */ new Map();
+function resolveRoot(basePkg, from) {
+	const cacheKey = `${basePkg}\0${from.map(String).join("\0")}`;
+	if (rootCache.has(cacheKey)) return rootCache.get(cacheKey);
+	const promise = (async () => {
+		try {
+			return dirname(await resolvePackageJSON(resolveModulePath(basePkg, {
+				from,
+				...TYPE_RESOLVE_OPTIONS
+			})));
+		} catch {
+			return;
+		}
+	})();
+	rootCache.set(cacheKey, promise);
+	return promise;
+}
+/**
+* Resolve auto-import / `tsConfig.paths` entries to the path TypeScript should load types from.
+*
+* A bare package resolves to its package root, so TypeScript follows the package's own
+* `exports` / `types` (which may differ from the file its `.` export condition points at).
+* A subpath export resolves to its entry's declaration sibling when one exists, otherwise to
+* the resolved file itself.
+*
+* Returns `[specifier, absolutePath]` pairs, omitting any specifier that cannot be resolved.
+*/
+async function resolveTypePaths(packages, searchPaths) {
+	const from = searchPaths.map((d) => directoryToURL(d));
+	return (await Promise.allSettled(packages.map(async (pkg) => {
+		if (pkg === packageName(pkg)) {
+			const root = await resolveRoot(pkg, from);
+			return root ? [pkg, root] : void 0;
+		}
+		const resolved = resolveModulePath(pkg, {
+			from,
+			try: true,
+			...TYPE_RESOLVE_OPTIONS
+		});
+		return resolved ? [pkg, await resolveDeclarationPath(resolved)] : void 0;
+	}))).flatMap((result) => result.status === "fulfilled" && result.value ? [result.value] : []);
+}
+//#endregion
 //#region src/template.ts
 /**
 * Renders given template during build into the virtual file system (and optionally to disk in the project `buildDir`)
@@ -1458,7 +1879,7 @@ function addServerTemplate(template) {
 function addTypeTemplate(_template, context) {
 	const nuxt = useNuxt();
 	const template = addTemplate(_template);
-	if (!template.filename.endsWith(".d.ts")) throw new Error(`Invalid type template. Filename must end with .d.ts : "${template.filename}"`);
+	if (!template.filename.endsWith(".d.ts")) throw kitDiagnostics.NUXT_B8007({ template: template.filename });
 	if (!context || context.nuxt) nuxt.hook("prepare:types", (payload) => {
 		payload.references ||= [];
 		payload.references.push({ path: template.dst });
@@ -1482,19 +1903,19 @@ function addTypeTemplate(_template, context) {
 * Normalize a nuxt template object
 */
 function normalizeTemplate(template, buildDir) {
-	if (!template) throw new Error("Invalid template: " + JSON.stringify(template));
+	if (!template) throw kitDiagnostics.NUXT_B8008({ template: JSON.stringify(template) });
 	if (typeof template === "string") template = { src: template };
 	else template = { ...template };
 	if (template.src) {
-		if (!existsSync(template.src)) throw new Error("Template not found: " + template.src);
+		if (!existsSync(template.src)) throw kitDiagnostics.NUXT_B8009({ template: template.src });
 		if (!template.filename) {
 			const srcPath = parse(template.src);
 			template.filename = template.fileName || `${basename(srcPath.dir)}.${srcPath.name}.${hash(template.src).replace(/-/g, "_")}${srcPath.ext}`;
 		}
 	}
-	if (!template.src && !template.getContents) throw new Error("Invalid template. Either `getContents` or `src` should be provided: " + JSON.stringify(template));
-	if (!template.filename) throw new Error("Invalid template. `filename` must be provided: " + JSON.stringify(template));
-	if (template.filename.endsWith(".d.ts")) template.write = true;
+	if (!template.src && !template.getContents) throw kitDiagnostics.NUXT_B8010({ template: template.filename || template.src || JSON.stringify(template) });
+	if (!template.filename) throw kitDiagnostics.NUXT_B8011({ template: JSON.stringify(template) });
+	if (template.filename.endsWith(".d.ts") || template.filename.endsWith(".d.mts") || template.filename.endsWith(".d.cts")) template.write = true;
 	template.dst ||= resolve(buildDir ?? useNuxt().options.buildDir, template.filename);
 	return template;
 }
@@ -1531,7 +1952,8 @@ function resolveLayerPaths(dirs, projectBuildDir) {
 			join(relativeRootDir, `.config/nuxt.*`),
 			join(relativeRootDir, `layers/*/nuxt.config.*`),
 			join(relativeRootDir, `layers/*/.config/nuxt.*`),
-			join(relativeRootDir, `layers/*/modules/**/*`)
+			join(relativeRootDir, `layers/*/modules/*.*`),
+			join(relativeRootDir, `layers/*/modules/*/*.*`)
 		],
 		shared: [
 			join(relativeSharedDir, `**/*`),
@@ -1546,13 +1968,15 @@ function resolveLayerPaths(dirs, projectBuildDir) {
 		globalDeclarations: [join(relativeRootDir, `*.d.ts`), join(relativeRootDir, `layers/*/*.d.ts`)]
 	};
 }
-const EXTENSION_RE = /\b(?:\.d\.[cm]?ts|\.\w+)$/g;
+async function getPathSubstitution(absolutePath, buildDir) {
+	return relativeWithDot(buildDir, await resolveDeclarationPath(absolutePath));
+}
 const excludedAlias = [/^@vue\/.*$/, /^#internal\/nuxt/];
 async function _generateTypes(nuxt) {
-	const include = new Set(["./nuxt.d.ts"]);
-	const nodeInclude = new Set(["./nuxt.node.d.ts"]);
-	const sharedInclude = new Set(["./nuxt.shared.d.ts"]);
-	const legacyInclude = new Set([...include, ...nodeInclude]);
+	const include = /* @__PURE__ */ new Set(["./nuxt.d.ts"]);
+	const nodeInclude = /* @__PURE__ */ new Set(["./nuxt.node.d.ts"]);
+	const sharedInclude = /* @__PURE__ */ new Set(["./nuxt.shared.d.ts"]);
+	const legacyInclude = /* @__PURE__ */ new Set([...include, ...nodeInclude]);
 	const exclude = /* @__PURE__ */ new Set();
 	const nodeExclude = /* @__PURE__ */ new Set();
 	const sharedExclude = /* @__PURE__ */ new Set();
@@ -1628,7 +2052,7 @@ async function _generateTypes(nuxt) {
 		legacyExclude.add(join(relative, "dist/runtime/server"));
 	}
 	const nestedModulesDirs = [];
-	for (const dir of [...nuxt.options.modulesDir].sort()) {
+	for (const dir of nuxt.options.modulesDir.toSorted()) {
 		const withSlash = withTrailingSlash$1(dir);
 		if (nestedModulesDirs.every((d) => !d.startsWith(withSlash))) nestedModulesDirs.push(withSlash);
 	}
@@ -1636,12 +2060,15 @@ async function _generateTypes(nuxt) {
 	for (const parent of nestedModulesDirs) hasTypescriptVersionWithModulePreserve ??= await readPackageJSON("typescript", { parent }).then((r) => r?.version && gte(r.version, "5.4.0")).catch(() => void 0);
 	hasTypescriptVersionWithModulePreserve ??= true;
 	const useDecorators = Boolean(nuxt.options.experimental?.decorators);
+	const isV5OrHigher = (nuxt.options.future?.compatibilityVersion ?? 4) >= 5;
+	const userExclude = nuxt.options.typescript?.tsConfig?.exclude ?? [];
 	const tsConfig = defu(nuxt.options.typescript?.tsConfig, {
 		compilerOptions: {
 			esModuleInterop: true,
 			skipLibCheck: true,
 			target: "ESNext",
 			allowJs: true,
+			allowImportingTsExtensions: true,
 			resolveJsonModule: true,
 			moduleDetection: "force",
 			isolatedModules: true,
@@ -1651,6 +2078,7 @@ async function _generateTypes(nuxt) {
 			noUncheckedIndexedAccess: true,
 			forceConsistentCasingInFileNames: true,
 			noImplicitOverride: true,
+			...isV5OrHigher ? { noUncheckedSideEffectImports: true } : {},
 			...useDecorators ? { experimentalDecorators: false } : {},
 			module: hasTypescriptVersionWithModulePreserve ? "preserve" : "ESNext",
 			noEmit: true,
@@ -1661,6 +2089,7 @@ async function _generateTypes(nuxt) {
 				"dom.iterable",
 				"webworker"
 			],
+			libReplacement: false,
 			jsx: "preserve",
 			jsxImportSource: "vue",
 			types: [],
@@ -1679,6 +2108,7 @@ async function _generateTypes(nuxt) {
 			skipLibCheck: tsConfig.compilerOptions?.skipLibCheck,
 			target: tsConfig.compilerOptions?.target,
 			allowJs: tsConfig.compilerOptions?.allowJs,
+			allowImportingTsExtensions: tsConfig.compilerOptions?.allowImportingTsExtensions,
 			resolveJsonModule: tsConfig.compilerOptions?.resolveJsonModule,
 			moduleDetection: tsConfig.compilerOptions?.moduleDetection,
 			isolatedModules: tsConfig.compilerOptions?.isolatedModules,
@@ -1706,6 +2136,7 @@ async function _generateTypes(nuxt) {
 			skipLibCheck: tsConfig.compilerOptions?.skipLibCheck,
 			target: tsConfig.compilerOptions?.target,
 			allowJs: tsConfig.compilerOptions?.allowJs,
+			allowImportingTsExtensions: tsConfig.compilerOptions?.allowImportingTsExtensions,
 			resolveJsonModule: tsConfig.compilerOptions?.resolveJsonModule,
 			moduleDetection: tsConfig.compilerOptions?.moduleDetection,
 			isolatedModules: tsConfig.compilerOptions?.isolatedModules,
@@ -1732,6 +2163,7 @@ async function _generateTypes(nuxt) {
 	tsConfig.compilerOptions ||= {};
 	tsConfig.compilerOptions.paths ||= {};
 	tsConfig.include ||= [];
+	tsConfig.exclude ||= [];
 	const importPaths = nuxt.options.modulesDir.map((d) => directoryToURL(d));
 	for (const alias in aliases) {
 		if (excludedAlias.some((re) => re.test(alias))) continue;
@@ -1758,7 +2190,7 @@ async function _generateTypes(nuxt) {
 			tsConfig.compilerOptions.paths[alias] = [relativePath];
 			tsConfig.compilerOptions.paths[`${alias}/*`] = [`${relativePath}/*`];
 		} else {
-			const path = stats?.isFile() ? relativePath.replace(EXTENSION_RE, "") : aliases[alias];
+			const path = stats?.isFile() ? await getPathSubstitution(absolutePath, nuxt.options.buildDir) : aliases[alias];
 			tsConfig.compilerOptions.paths[alias] = [path];
 		}
 	}
@@ -1791,18 +2223,18 @@ async function _generateTypes(nuxt) {
 	const legacyTsConfig = defu({}, {
 		...tsConfig,
 		include: [...tsConfig.include, ...legacyInclude],
-		exclude: [...legacyExclude]
+		exclude: [...userExclude, ...legacyExclude]
 	});
+	const nonRootLayerDirs = layerDirs.map((dirs) => dirs.root).filter((root) => !rootDirWithSlash.startsWith(root));
 	async function resolveConfig(tsConfig) {
 		for (const alias in tsConfig.compilerOptions.paths) {
 			const paths = tsConfig.compilerOptions.paths[alias];
 			tsConfig.compilerOptions.paths[alias] = [...new Set(await Promise.all(paths.map(async (path) => {
 				if (!isAbsolute(path)) return path;
-				const stats = await promises.stat(path).catch(() => null);
-				return relativeWithDot(nuxt.options.buildDir, stats?.isFile() ? path.replace(EXTENSION_RE, "") : path);
+				return (await promises.stat(path).catch(() => null))?.isFile() ? getPathSubstitution(path, nuxt.options.buildDir) : relativeWithDot(nuxt.options.buildDir, path);
 			})))];
 		}
-		sortTsPaths(tsConfig.compilerOptions.paths);
+		tsConfig.compilerOptions.paths = sortTsPaths(tsConfig.compilerOptions.paths, nonRootLayerDirs, nuxt.options.buildDir, nuxt.options.typescript?.hoist ?? []);
 		tsConfig.include = [...new Set(tsConfig.include.map((p) => isAbsolute(p) ? relativeWithDot(nuxt.options.buildDir, p) : p))];
 		tsConfig.exclude = [...new Set(tsConfig.exclude.map((p) => isAbsolute(p) ? relativeWithDot(nuxt.options.buildDir, p) : p))];
 	}
@@ -1860,12 +2292,48 @@ async function writeTypes(nuxt) {
 		promises.writeFile(sharedDeclarationPath, sharedDeclaration)
 	]);
 }
-function sortTsPaths(paths) {
-	for (const pathKey in paths) if (pathKey.startsWith("#build")) {
-		const pathValue = paths[pathKey];
-		delete paths[pathKey];
-		paths[pathKey] = pathValue;
+/**
+* Sort the paths in the tsconfig.json file, so
+* - Hoisted package paths stay at the top (`typescript.hoist`)
+* - Custom layer aliases follow, then generic `#layers/*` aliases
+* - Generic `~`/`@` aliases come after layer aliases
+* - `#build` alias is at the bottom (https://github.com/nuxt/nuxt/issues/30325)
+*/
+function sortTsPaths(paths, layerDirs, buildDir, hoist) {
+	const hoistKeys = new Set(hoist);
+	const hoistPaths = {};
+	const customLayerPaths = {};
+	const genericLayerPaths = {};
+	const otherPaths = {};
+	const buildPaths = {};
+	for (const pathKey in paths) {
+		if (pathKey.startsWith("#build")) {
+			buildPaths[pathKey] = paths[pathKey];
+			continue;
+		}
+		if (isHoistPathKey(pathKey, hoistKeys)) {
+			hoistPaths[pathKey] = paths[pathKey];
+			continue;
+		}
+		if (layerDirs.length && paths[pathKey].some((target) => isPathUnderLayerDirs(target, buildDir, layerDirs))) if (pathKey.startsWith("#layers")) genericLayerPaths[pathKey] = paths[pathKey];
+		else customLayerPaths[pathKey] = paths[pathKey];
+		else otherPaths[pathKey] = paths[pathKey];
 	}
+	return {
+		...hoistPaths,
+		...customLayerPaths,
+		...genericLayerPaths,
+		...otherPaths,
+		...buildPaths
+	};
+}
+const PATH_WILDCARD_RE = /\/?\*$/;
+function isHoistPathKey(pathKey, hoistKeys) {
+	return hoistKeys.has(pathKey.replace(PATH_WILDCARD_RE, ""));
+}
+function isPathUnderLayerDirs(target, buildDir, layerDirs) {
+	const absolute = withTrailingSlash$1(resolve(buildDir, target.replace(PATH_WILDCARD_RE, "")));
+	return layerDirs.some((dir) => absolute.startsWith(dir));
 }
 function renderReference(ref, baseDir) {
 	return `/// <reference ${"path" in ref ? `path="${isAbsolute(ref.path) ? relative(baseDir, ref.path) : ref.path}"` : `types="${ref.types}"`} />`;
@@ -1890,7 +2358,12 @@ function addLayout(template, name) {
 				...nuxt?.options.alias || {},
 				...strippedAtAliases
 			}).pop() || app.layouts[layoutName].file;
-			return logger.warn(`Not overriding \`${layoutName}\` (provided by \`${relativePath}\`) with \`${src || filename}\`.`);
+			pageDiagnostics.NUXT_B4014({
+				layoutName,
+				existingPath: relativePath,
+				newPath: src || filename
+			});
+			return;
 		}
 		app.layouts[layoutName] = {
 			file: join("#build", filename),
@@ -1924,13 +2397,85 @@ function addRouteMiddleware(input, options = {}) {
 				const foundPath = app.middleware[find].path;
 				if (foundPath === middleware.path) continue;
 				if (options.override === true) app.middleware[find] = { ...middleware };
-				else logger.warn(`'${middleware.name}' middleware already exists at '${foundPath}'. You can set \`override: true\` to replace it.`);
+				else pageDiagnostics.NUXT_B4013({
+					name: middleware.name,
+					foundPath
+				});
 			} else if (options.prepend === true) app.middleware.unshift({ ...middleware });
 			else app.middleware.push({ ...middleware });
 		}
 	});
 }
 //#endregion
+//#region src/diagnostics/plugins.ts
+/**
+* B2xxx
+* Plugin diagnostics (`addPlugin`, plugin metadata, plugin ordering).
+*
+* @internal
+*/
+const pluginDiagnostics = /* #__PURE__ */ defineDiagnostics({
+	docsBase,
+	reporters,
+	codes: {
+		NUXT_B2001: {
+			why: (p) => `The second argument to \`${p.name}\` is a \`${p.type}\`, not an object literal.`,
+			fix: "Pass an object literal as the second argument, e.g. `defineNuxtPlugin(() => {}, { name: 'my-plugin' })`.",
+			docs: false
+		},
+		NUXT_B2002: {
+			why: "Plugin options contain spread elements or computed keys, which are not supported.",
+			fix: "Use static properties instead.",
+			docs: false
+		},
+		NUXT_B2003: {
+			why: "`dependsOn` is not an array of string literals.",
+			fix: "Use string literals in the `dependsOn` array, e.g. `dependsOn: ['my-plugin']`.",
+			docs: false
+		},
+		NUXT_B2004: {
+			why: (p) => `Plugin \`${p.src}\` has no content.`,
+			fix: "Add content to the plugin file, or remove it from the `plugins/` directory.",
+			docs: false
+		},
+		NUXT_B2005: {
+			why: (p) => `Plugin \`${p.src}\` has no default export and will be ignored at build time.`,
+			fix: "Add `export default defineNuxtPlugin(() => {})` to your plugin.",
+			docs: false
+		},
+		NUXT_B2006: {
+			why: (p) => `Error parsing plugin \`${p.src}\`.`,
+			fix: "Check the plugin file for syntax errors.",
+			docs: false
+		},
+		NUXT_B2007: {
+			why: (p) => `Plugin \`${p.src}\` is not wrapped in \`defineNuxtPlugin\`.`,
+			fix: "Wrap your plugin with `defineNuxtPlugin`. This may enable enhancements in future.",
+			docs: false
+		},
+		NUXT_B2008: {
+			why: (p) => `Plugin \`${p.name}\` depends on \`${p.missing}\` but they are not registered.`,
+			fix: "Register the missing dependency plugins, or remove them from the `dependsOn` array.",
+			docs: false
+		},
+		NUXT_B2009: {
+			why: (p) => `Circular dependency detected in plugins: ${p.cycle}.`,
+			fix: "Restructure the plugin `dependsOn` declarations to break the cycle.",
+			docs: false
+		},
+		NUXT_B2010: {
+			why: (p) => `Failed to parse static properties from plugin \`${p.src}\`, falling back to non-optimized runtime meta.`,
+			fix: "Use an object literal with static values as the second argument to `defineNuxtPlugin()`, and check the plugin file for syntax errors or unsupported constructs in the metadata.",
+			docs: false
+		},
+		NUXT_B2011: {
+			why: (p) => `Invalid plugin \`${p.src}\`. The \`src\` option is required.`,
+			fix: "Pass a string path, or an object with a `src` property, to `addPlugin()`.",
+			docs: false
+		}
+	}
+});
+//#endregion
 //#region src/plugin.ts
 /**
 * Normalize a nuxt plugin object
@@ -1940,7 +2485,7 @@ function normalizePlugin(plugin) {
 	if (typeof plugin === "string") plugin = { src: plugin };
 	else plugin = { ...plugin };
 	if (pluginSymbol in plugin) return plugin;
-	if (!plugin.src) throw new Error("Invalid plugin. src option is required: " + JSON.stringify(plugin));
+	if (!plugin.src) throw pluginDiagnostics.NUXT_B2011({ src: JSON.stringify(plugin) });
 	plugin.src = normalize(resolveAlias(plugin.src));
 	if (!existsSync(plugin.src) && isAbsolute$1(plugin.src)) try {
 		plugin.src = resolveModulePath(plugin.src, { extensions: tryUseNuxt()?.options.extensions ?? [
@@ -1978,4 +2523,317 @@ function addPluginTemplate(plugin, opts = {}) {
 	}, opts);
 }
 //#endregion
-export { addBuildPlugin, addComponent, addComponentExports, addComponentsDir, addDevServerHandler, addImports, addImportsDir, addImportsSources, addLayout, addPlugin, addPluginTemplate, addPrerenderRoutes, addRouteMiddleware, addRspackPlugin, addServerHandler, addServerImports, addServerImportsDir, addServerPlugin, addServerScanDir, addServerTemplate, addTemplate, addTypeTemplate, addVitePlugin, addWebpackPlugin, assertNuxtCompatibility, buildNuxt, checkNuxtCompatibility, createIsIgnored, createResolver, defineNuxtModule, directoryToURL, extendNuxtSchema, extendPages, extendRouteRules, extendRspackConfig, extendViteConfig, extendWebpackConfig, findPath, getDirectory, getLayerDirectories, getNuxtCtx, getNuxtModuleVersion, getNuxtVersion, hasNuxtCompatibility, hasNuxtModule, hasNuxtModuleCompatibility, importModule, installModule, installModules, isIgnored, isNuxt2, isNuxt3, isNuxtMajorVersion, loadNuxt, loadNuxtConfig, loadNuxtModuleInstance, logger, normalizeModuleTranspilePath, normalizePlugin, normalizeSemanticVersion, normalizeTemplate, nuxtCtx, requireModule, resolveAlias, resolveFiles, resolveIgnorePatterns, resolveModule, resolveModuleWithOptions, resolveNuxtModule, resolvePath, runWithNuxtContext, setGlobalHead, tryImportModule, tryRequireModule, tryResolveModule, tryUseNuxt, updateRuntimeConfig, updateTemplates, useLogger, useNitro, useNuxt, useRuntimeConfig, writeTypes };
+//#region src/diagnostics/build.ts
+/**
+* B1xxx
+* Build / compilation diagnostics.
+*
+* @internal
+*/
+const buildDiagnostics = /* #__PURE__ */ defineDiagnostics({
+	docsBase,
+	reporters,
+	codes: {
+		NUXT_B1001: {
+			why: (p) => `Could not compile template \`${p.filename}\`.`,
+			fix: (p) => p.src ? `Check the template source file at \`${p.src}\` for syntax errors.` : "Check the `getContents` function of this template for errors.",
+			docs: false
+		},
+		NUXT_B1002: {
+			why: (p) => `Error reading template from \`${p.src}\`.`,
+			fix: "Check that the template `src` path exists and is readable.",
+			docs: false
+		},
+		NUXT_B1003: {
+			why: "Invalid template. Templates must have either `src` or `getContents`.",
+			fix: "Add a `getContents` function or a `src` path to the `addTemplate()` call.",
+			docs: false
+		},
+		NUXT_B1004: {
+			why: "Failed to install dependencies.",
+			fix: (p) => `Try installing manually with \`npm install ${p.packages}\`.`,
+			docs: false
+		},
+		NUXT_B1005: {
+			why: (p) => `Plugin \`${p.plugin}\` failed to scan file \`${p.file}\`.`,
+			fix: "Check the file for syntax errors, or report this issue to the plugin author.",
+			docs: false
+		},
+		NUXT_B1006: {
+			why: (p) => `Cannot read file \`${p.file}\`.`,
+			fix: "Check that the file exists and has correct permissions.",
+			docs: false
+		},
+		NUXT_B1007: {
+			why: (p) => `Error in \`afterScan\` hook of plugin \`${p.plugin}\`.`,
+			fix: "Check the plugin implementation or report this issue to the plugin author.",
+			docs: false
+		},
+		NUXT_B1008: {
+			why: (p) => `No factory function found for \`${p.function}\` in file \`${p.file}\`. This is a Nuxt bug.`,
+			fix: "Please report this issue at https://github.com/nuxt/nuxt/issues with the file contents.",
+			docs: false
+		},
+		NUXT_B1009: {
+			why: (p) => `Duplicate keyed function name \`${p.functionName}\`${p.name && p.functionName !== p.name ? ` defined as \`${p.name}\`` : ""} with ${p.source ? `the same source \`${p.source}\`` : "no source"} found. Overwriting the existing entry.`,
+			fix: "Ensure each keyed function has a unique name, or use a different source to distinguish them.",
+			docs: false
+		},
+		NUXT_B1010: {
+			why: (p) => `Failed to read file \`${p.file}\` as it changed during read.`,
+			fix: "The file was modified while being read, usually by a concurrent process writing to it. Try restarting the build.",
+			docs: false
+		},
+		NUXT_B1011: {
+			why: (p) => `Failed to read file \`${p.file}\`.`,
+			fix: "Check that the file exists and is readable, or try clearing the build cache with `nuxi clean`.",
+			docs: false
+		},
+		NUXT_B1012: {
+			why: (p) => `Skipping unsafe cache path: ${p.path}. This cache file has a path that escapes the project directory (possible path traversal).`,
+			fix: "Delete the cache with `nuxi clean` and rebuild.",
+			docs: false
+		},
+		NUXT_B1013: {
+			why: (p) => `Failed to restore cached file \`${p.file}\`.`,
+			fix: "Try clearing the build cache with `nuxi clean` and rebuilding from scratch.",
+			docs: false
+		},
+		NUXT_B1014: {
+			why: "Problem checking for external configuration files.",
+			fix: "This is likely a transient file system error. If it persists, check file permissions in your project root.",
+			docs: false
+		},
+		NUXT_B1015: {
+			why: "Falling back to `chokidar-granular` as `@parcel/watcher` cannot be resolved in your project.",
+			fix: "Install `@parcel/watcher` for better performance: `npm install -D @parcel/watcher`.",
+			docs: false
+		},
+		NUXT_B1016: {
+			why: "Failed to set up the `@parcel/watcher` file watcher.",
+			fix: "This is likely an environment or file system issue. Watching for file changes may not work; restart the dev server and, if the problem persists, report it.",
+			docs: false
+		},
+		NUXT_B1017: {
+			why: (p) => `Loading \`${p.builder}\` builder failed.`,
+			fix: (p) => `Run \`npm install ${p.builder}\` to install it.`,
+			docs: false
+		},
+		NUXT_B1018: {
+			why: (p) => `Loading \`${p.builder}\` server builder failed.`,
+			fix: (p) => `Run \`npm install ${p.builder}\` to install it.`,
+			docs: false
+		},
+		NUXT_B1019: {
+			why: (p) => `Unknown component mode \`${p.mode}\`. This might be an internal Nuxt bug.`,
+			fix: "If you are a module author, ensure the component `mode` is set to `client`, `server`, or `all`. Otherwise, please report this issue.",
+			docs: false
+		},
+		NUXT_B1020: {
+			why: "`experimental.watcher: \"builder\"` is set but the active builder does not implement `setupWatcher`. Falling back to the default file watcher.",
+			fix: "Remove `experimental.watcher` from your `nuxt.config`, or use a builder that supports its own watcher.",
+			docs: false
+		}
+	}
+});
+//#endregion
+//#region src/diagnostics/config.ts
+/**
+* B5xxx
+* Configuration diagnostics.
+*
+* @internal
+*/
+const configDiagnostics = /* #__PURE__ */ defineDiagnostics({
+	docsBase,
+	reporters,
+	codes: {
+		NUXT_B5001: {
+			why: (p) => `No \`compatibilityDate\` is set in \`nuxt.config\`, so the \`${p.fallback}\` fallback is being used.`,
+			fix: (p) => `Add \`compatibilityDate: '${p.latest}'\` to your \`nuxt.config.ts\`.`
+		},
+		NUXT_B5002: {
+			why: (p) => `\`@nuxt/webpack-builder\` could not be installed in \`${p.rootDir}\`.`,
+			fix: "Install it manually with `npm install -D @nuxt/webpack-builder`, or change the `builder` option to `vite` in `nuxt.config`.",
+			docs: false
+		},
+		NUXT_B5003: {
+			why: (p) => `The \`app\` namespace is reserved for Nuxt and exposed to the browser, but \`runtimeConfig.app.${p.key}\` is set.`,
+			fix: "Move the key to `runtimeConfig.public` or a custom namespace."
+		},
+		NUXT_B5004: {
+			why: (p) => `External configuration files are not supported: ${p.files}.`,
+			fix: "Move these configurations into `nuxt.config.ts` and delete the external config files."
+		},
+		NUXT_B5005: {
+			why: (p) => `Nuxt schema could not be loaded from \`${p.filePath}\`.`,
+			fix: "Ensure the file exports a valid object with `defineNuxtSchema()` or as a plain object.",
+			docs: false
+		},
+		NUXT_B5006: {
+			why: (p) => `\`${p.option}\` is used in dev mode, which causes a memory leak.`,
+			fix: "Remove the hash option from your webpack config.",
+			docs: false
+		},
+		NUXT_B5007: {
+			why: "The webpack server config `target` is not set to \"node\".",
+			fix: "Set `target: \"node\"` in your webpack server configuration.",
+			docs: false
+		},
+		NUXT_B5009: {
+			why: "`@parcel/watcher` cannot be resolved in your project, so `chokidar` is being used instead.",
+			fix: "Install `@parcel/watcher` for better file watching: `npm install -D @parcel/watcher`.",
+			docs: false
+		},
+		NUXT_B5010: {
+			why: (p) => `Required packages are not installed: ${p.names}.`,
+			fix: (p) => `Run \`npm install ${p.install}\` to install them.`,
+			docs: false
+		},
+		NUXT_B5011: {
+			why: (p) => `Package \`${p.name}\` is missing.`,
+			fix: (p) => `Run \`npx nuxt add ${p.name}\` to install it.`,
+			docs: false
+		}
+	}
+});
+//#endregion
+//#region src/diagnostics/head.ts
+/**
+* B6xxx
+* Head / auto-import diagnostics.
+*
+* @internal
+*/
+const headDiagnostics = /* #__PURE__ */ defineDiagnostics({
+	docsBase,
+	reporters,
+	codes: {
+		NUXT_B6001: {
+			why: (p) => `\`${p.file}\` imports head composables directly from \`${p.module}\`, which loses Nuxt's type safety.`,
+			fix: "Import from `#imports` instead.",
+			docs: false
+		},
+		NUXT_B6002: {
+			why: (p) => `\`${p.name}\` is already auto-imported by Nuxt as a built-in, and overriding it will likely cause issues.`,
+			fix: (p) => `Rename \`${p.name}\` in \`${p.file}\` so it no longer collides with the built-in auto-import.`,
+			docs: false
+		},
+		NUXT_B6003: {
+			why: "`unhead.legacy` is deprecated and will be removed.",
+			fix: "Remove deprecated head patterns (`hid`, `vmid`, `children`, `body: true`) and resolve promise values before passing them to `useHead`.",
+			docs: false
+		},
+		NUXT_B6004: {
+			why: "`experimental.headNext` is deprecated. CAPO sorting is now the default.",
+			fix: "Remove `experimental.headNext` from your `nuxt.config`, or set `unhead.legacy: true` to opt out temporarily.",
+			docs: false
+		}
+	}
+});
+//#endregion
+//#region src/diagnostics/bundler.ts
+/**
+* B7xxx
+* Bundler (Vite / webpack / Nitro) diagnostics.
+*
+* @internal
+*/
+const bundlerDiagnostics = /* #__PURE__ */ defineDiagnostics({
+	docsBase,
+	reporters,
+	codes: {
+		NUXT_B7001: {
+			why: "`rollup-plugin-visualizer` is not installed, so bundle analysis cannot run.",
+			fix: "Run `npm install -D rollup-plugin-visualizer` to enable bundle analysis.",
+			docs: false
+		},
+		NUXT_B7002: {
+			why: (p) => `Some \`vite.optimizeDeps.include\` entries could not be resolved: ${p.deps}.`,
+			fix: "Remove or correct these entries in the `vite.optimizeDeps.include` array of your `nuxt.config.ts`. Report entries added by a Nuxt module to the module author.",
+			docs: false
+		},
+		NUXT_B7003: {
+			why: "The server-side bundle produced more than one JS entry file.",
+			fix: "Avoid using `optimization.splitChunks` in the server config.",
+			docs: false
+		},
+		NUXT_B7004: {
+			why: (p) => `Webpack entry \`${p.entryName}\` was not found.`,
+			fix: (p) => `Check that the \`entry\` option in your webpack configuration points to an existing file. Expected entry name: \`${p.entryName}\`.`,
+			docs: false
+		},
+		NUXT_B7005: {
+			why: (p) => `No client entry was found in \`rollupOptions.input\`; expected an \`entry\` key or a string input but received ${p.input}.`,
+			fix: "Set `vite.build.rollupOptions.input` to a string or an object with an `entry` key in your `nuxt.config`.",
+			docs: false
+		},
+		NUXT_B7006: {
+			why: (p) => `No server entry was found in \`rollupOptions.input\`; expected a \`server\` key or a string input but received ${p.input}.`,
+			fix: "Set `vite.build.rollupOptions.input` to a string or an object with a `server` key in your `nuxt.config`.",
+			docs: false
+		},
+		NUXT_B7007: {
+			why: (p) => `The PostCSS plugin \`${p.pluginName}\` could not be loaded.`,
+			fix: (p) => `Run \`npm install -D ${p.pluginName}\` to install the PostCSS plugin.`,
+			docs: false
+		},
+		NUXT_B7008: {
+			why: "`@vitejs/plugin-vue-jsx` is not installed, so JSX support is unavailable.",
+			fix: "Run `npm install -D @vitejs/plugin-vue-jsx` to install it.",
+			docs: false
+		},
+		NUXT_B7009: {
+			why: (p) => `The Babel dependencies required for decorator support are missing: ${p.deps}.`,
+			fix: (p) => `Run \`npm install -D ${p.install}\` to install the required Babel decorator dependencies.`,
+			docs: false
+		},
+		NUXT_B7011: {
+			why: (p) => `The PostCSS plugin \`${p.pluginName}\` could not be imported, which is unexpected.`,
+			fix: (p) => `Run \`npm install -D ${p.pluginName}\` to install it, or report this issue at https://github.com/nuxt/nuxt/issues.`,
+			docs: false
+		},
+		NUXT_B7012: {
+			why: (p) => `A ViteNode socket payload of ${p.requiredSize} bytes exceeds the internal buffer limit of ${p.maxSize} bytes.`,
+			fix: "Reduce the payload size sent through the ViteNode socket.",
+			docs: false
+		},
+		NUXT_B7013: {
+			why: "The ViteNode socket server was started without a configured socket path.",
+			fix: "This is likely an internal Nuxt bug. Please report it at https://github.com/nuxt/nuxt/issues.",
+			docs: false
+		},
+		NUXT_B7014: {
+			why: (p) => `The webpack \`${p.name}\` build failed with errors.`,
+			fix: "Fix the build errors listed above. If the errors are unclear, try running `nuxi clean` and rebuilding.",
+			docs: false
+		},
+		NUXT_B7015: {
+			why: "Payload extraction is disabled, which is suboptimal for full-static output.",
+			fix: "Set `experimental.payloadExtraction` to `true` or `'client'`.",
+			docs: false
+		},
+		NUXT_B7016: {
+			why: (p) => `The configured \`spaLoadingTemplate\` path does not exist: \`${p.path}\`.`,
+			fix: "Point `spaLoadingTemplate` in `nuxt.config` at an existing HTML file, or set it to `true` to use the default template.",
+			docs: false
+		},
+		NUXT_B7017: {
+			why: "Could not find the Nuxt dev server to attach Rspack HMR to; hot module replacement will be disabled.",
+			fix: "This is likely an internal Nuxt bug. Please report it with a reproduction.",
+			docs: false
+		},
+		NUXT_B7018: {
+			why: "Failed to restrict vite-node socket permissions; closing the socket.",
+			fix: "Check that the temporary directory used for the vite-node socket is writable and supports `chmod`.",
+			docs: false
+		},
+		NUXT_B7019: {
+			why: "The server webpack build does not externalize dependencies.",
+			fix: "Externalize dependencies in the server build (`externals`) for better build performance.",
+			docs: false
+		}
+	}
+});
+//#endregion
+export { addBuildPlugin, addComponent, addComponentExports, addComponentsDir, addDevServerHandler, addImports, addImportsDir, addImportsSources, addLayout, addPlugin, addPluginTemplate, addPrerenderRoutes, addRouteMiddleware, addRspackPlugin, addServerHandler, addServerImports, addServerImportsDir, addServerPlugin, addServerScanDir, addServerTemplate, addTemplate, addTypeTemplate, addVitePlugin, addWebpackPlugin, assertNuxtCompatibility, buildDiagnostics, buildNuxt, bundlerDiagnostics, checkNuxtCompatibility, componentDiagnostics, configDiagnostics, createIsIgnored, createResolver, defineNuxtModule, directoryToURL, extendNuxtSchema, extendPages, extendRouteRules, extendRspackConfig, extendViteConfig, extendWebpackConfig, findPath, getDirectory, getLayerDirectories, getNuxtCtx, getNuxtModuleVersion, getNuxtVersion, hasNuxtCompatibility, hasNuxtModule, hasNuxtModuleCompatibility, headDiagnostics, importModule, installModule, installModules, isIgnored, isNuxt2, isNuxt3, isNuxtMajorVersion, loadNuxt, loadNuxtConfig, loadNuxtModuleInstance, logger, normalizeModuleTranspilePath, normalizePlugin, normalizeSemanticVersion, normalizeTemplate, nuxtCtx, packageName, pageDiagnostics, pluginDiagnostics, requireModule, resolveAlias, resolveDeclarationPath, resolveFiles, resolveIgnorePatterns, resolveModule, resolveModuleWithOptions, resolveNuxtModule, resolvePath, resolveTypePaths, runWithNuxtContext, setBuildOutput, setGlobalHead, tryImportModule, tryRequireModule, tryResolveModule, tryUseNuxt, updateAppConfig, updateRuntimeConfig, updateTemplates, useLogger, useNitro, useNuxt, useRuntimeConfig, writeTypes };