@nuxt/kit 4.3.1 → 4.4.1

package/dist/index.mjs

@@ -3,7 +3,7 @@ import { createDefu, defu } from "defu";
 import { applyDefaults } from "untyped";
 import { consola } from "consola";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { createContext, getContext } from "unctx";
+import { getContext } from "unctx";
 import satisfies from "semver/functions/satisfies.js";
 import { readPackageJSON, resolvePackageJSON } from "pkg-types";
 import { existsSync, lstatSync, promises, readFileSync } from "node:fs";
@@ -26,27 +26,59 @@ import { kebabCase, pascalCase, snakeCase } from "scule";
 import { klona } from "klona";
 import { hash } from "ohash";
 import { isAbsolute as isAbsolute$1 } from "node:path";
+//#region src/logger.ts
 const logger = consola;
 function useLogger(tag, options = {}) {
 	return tag ? logger.create(options).withTag(tag) : logger;
 }
+//#endregion
+//#region src/context.ts
+/**
+* Direct access to the Nuxt global context - see https://github.com/unjs/unctx.
+* @deprecated Use `getNuxtCtx` instead
+*/
 const nuxtCtx = getContext("nuxt");
-const asyncNuxtStorage = createContext({
+/** async local storage for the name of the current nuxt instance */
+const asyncNuxtStorage = getContext("asyncNuxtStorage", {
 	asyncContext: true,
 	AsyncLocalStorage
 });
+/** Direct access to the Nuxt context with asyncLocalStorage - see https://github.com/unjs/unctx. */
 const getNuxtCtx = () => asyncNuxtStorage.tryUse();
+/**
+* Get access to Nuxt instance.
+*
+* Throws an error if Nuxt instance is unavailable.
+* @example
+* ```js
+* const nuxt = useNuxt()
+* ```
+*/
 function useNuxt() {
 	const instance = asyncNuxtStorage.tryUse() || nuxtCtx.tryUse();
 	if (!instance) throw new Error("Nuxt instance is unavailable!");
 	return instance;
 }
+/**
+* Get access to Nuxt instance.
+*
+* Returns null if Nuxt instance is unavailable.
+* @example
+* ```js
+* const nuxt = tryUseNuxt()
+* if (nuxt) {
+*  // Do something
+* }
+* ```
+*/
 function tryUseNuxt() {
 	return asyncNuxtStorage.tryUse() || nuxtCtx.tryUse();
 }
 function runWithNuxtContext(nuxt, fn) {
 	return asyncNuxtStorage.call(nuxt, fn);
 }
+//#endregion
+//#region src/compatibility.ts
 const SEMANTIC_VERSION_RE = /-\d+\.[0-9a-f]+/;
 function normalizeSemanticVersion(version) {
 	return version.replace(SEMANTIC_VERSION_RE, "");
@@ -59,6 +91,9 @@ const builderMap = {
 function checkNuxtVersion(version, nuxt = useNuxt()) {
 	return satisfies(normalizeSemanticVersion(getNuxtVersion(nuxt)), version, { includePrerelease: true });
 }
+/**
+* Check version constraints and return incompatibility issues as an array
+*/
 async function checkNuxtCompatibility(constraints, nuxt = useNuxt()) {
 	const issues = [];
 	if (constraints.nuxt) {
@@ -96,30 +131,50 @@ async function checkNuxtCompatibility(constraints, nuxt = useNuxt()) {
 	issues.toString = () => issues.map((issue) => ` - [${issue.name}] ${issue.message}`).join("\n");
 	return issues;
 }
+/**
+* Check version constraints and throw a detailed error if has any, otherwise returns true
+*/
 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());
 	return true;
 }
+/**
+* Check version constraints and return true if passed, otherwise returns false
+*/
 async function hasNuxtCompatibility(constraints, nuxt = useNuxt()) {
 	return !(await checkNuxtCompatibility(constraints, nuxt)).length;
 }
+/**
+* Check if current Nuxt instance is of specified major version
+*/
 function isNuxtMajorVersion(majorVersion, nuxt = useNuxt()) {
 	const version = getNuxtVersion(nuxt);
 	return version[0] === majorVersion.toString() && version[1] === ".";
 }
+/**
+* @deprecated Use `isNuxtMajorVersion(2, nuxt)` instead. This may be removed in \@nuxt/kit v5 or a future major version.
+*/
 function isNuxt2(nuxt = useNuxt()) {
 	return isNuxtMajorVersion(2, nuxt);
 }
+/**
+* @deprecated Use `isNuxtMajorVersion(3, nuxt)` instead. This may be removed in \@nuxt/kit v5 or a future major version.
+*/
 function isNuxt3(nuxt = useNuxt()) {
 	return isNuxtMajorVersion(3, nuxt);
 }
 const NUXT_VERSION_RE = /^v/g;
+/**
+* Get nuxt version
+*/
 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?");
 	return rawVersion.replace(NUXT_VERSION_RE, "");
 }
+//#endregion
+//#region src/module/define.ts
 function defineNuxtModule(definition) {
 	if (definition) return _defineNuxtModule(definition);
 	return { with: (definition) => _defineNuxtModule(definition) };
@@ -161,12 +216,19 @@ function _defineNuxtModule(definition) {
 		}
 		const _options = await getOptions(inlineOptions, nuxt);
 		if (module.hooks) nuxt.hooks.addHooks(module.hooks);
+		const moduleName = uniqueKey || module.meta.name || "<no name>";
+		nuxt._perf?.startPhase(`module:${moduleName}`);
 		const start = performance.now();
-		const res = await module.setup?.call(null, _options, nuxt) ?? {};
+		let res = {};
+		try {
+			res = await module.setup?.call(null, _options, nuxt) ?? {};
+		} finally {
+			nuxt._perf?.endPhase(`module:${moduleName}`);
+		}
 		const perf = performance.now() - start;
 		const setupTime = Math.round(perf * 100) / 100;
-		if (setupTime > 5e3 && uniqueKey !== "@nuxt/telemetry") logger.warn(`Slow module \`${uniqueKey || "<no name>"}\` took \`${setupTime}ms\` to setup.`);
-		else if (nuxt.options.debug && nuxt.options.debug.modules) logger.info(`Module \`${uniqueKey || "<no name>"}\` took \`${setupTime}ms\` to setup.`);
+		if (setupTime > 5e3 && uniqueKey !== "@nuxt/telemetry") logger.warn(`Slow module \`${moduleName}\` took \`${setupTime}ms\` to setup.`);
+		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 } });
 	}
@@ -177,6 +239,8 @@ function _defineNuxtModule(definition) {
 	normalizedModule.onUpgrade = module.onUpgrade;
 	return normalizedModule;
 }
+//#endregion
+//#region src/internal/trace.ts
 const distURL = import.meta.url.replace(/\/dist\/.*$/, "/");
 function getUserCaller() {
 	if (!import.meta.dev) return null;
@@ -195,7 +259,20 @@ function warn(warning) {
 		warnings.add(warning);
 	}
 }
+//#endregion
+//#region src/layers.ts
 const layerMap = /* @__PURE__ */ new WeakMap();
+/**
+* Get the resolved directory paths for all layers in a Nuxt application.
+*
+* Returns an array of LayerDirectories objects, ordered by layer priority:
+* - The first layer is the user/project layer (highest priority)
+* - Earlier layers override later layers in the array
+* - Base layers appear last in the array (lowest priority)
+*
+* @param nuxt - The Nuxt instance to get layers from. Defaults to the current Nuxt context.
+* @returns Array of LayerDirectories objects, ordered by priority (user layer first)
+*/
 function getLayerDirectories(nuxt = useNuxt()) {
 	return nuxt.options._layers.map((layer) => {
 		if (layerMap.has(layer)) return layerMap.get(layer);
@@ -221,9 +298,14 @@ function getLayerDirectories(nuxt = useNuxt()) {
 function withTrailingSlash$2(dir) {
 	return dir.replace(/[^/]$/, "$&/");
 }
+//#endregion
+//#region src/ignore.ts
 function createIsIgnored(nuxt = tryUseNuxt()) {
 	return (pathname, stats) => isIgnored(pathname, stats, nuxt);
 }
+/**
+* Return a filter function to filter an array of paths
+*/
 function isIgnored(pathname, _stats, nuxt = tryUseNuxt()) {
 	if (!nuxt) return false;
 	if (!nuxt._ignore) {
@@ -251,6 +333,13 @@ function resolveIgnorePatterns(relativePath) {
 	});
 	return ignorePatterns;
 }
+/**
+* This function turns string containing groups '**\/*.{spec,test}.{js,ts}' into an array of strings.
+* For example will '**\/*.{spec,test}.{js,ts}' be resolved to:
+* ['**\/*.spec.js', '**\/*.spec.ts', '**\/*.test.js', '**\/*.test.ts']
+* @param group string containing the group syntax
+* @returns {string[]} array of strings without the group syntax
+*/
 function resolveGroupSyntax(group) {
 	let groups = [group];
 	while (groups.some((group) => group.includes("{"))) groups = groups.flatMap((group) => {
@@ -263,15 +352,32 @@ function resolveGroupSyntax(group) {
 	});
 	return groups;
 }
+//#endregion
+//#region src/utils.ts
+/** @since 3.9.0 */
 function toArray(value) {
 	return Array.isArray(value) ? value : [value];
 }
+/**
+* Filter out items from an array in place. This function mutates the array.
+* `predicate` get through the array from the end to the start for performance.
+*
+* This function should be faster than `Array.prototype.filter` on large arrays.
+*/
 function filterInPlace(array, predicate) {
 	for (let i = array.length; i--;) if (!predicate(array[i], i, array)) array.splice(i, 1);
 	return array;
 }
 const MODE_RE = /\.(server|client)(\.\w+)*$/;
 const distDirURL = new URL(".", import.meta.url);
+//#endregion
+//#region src/resolve.ts
+/**
+* Resolve the full path to a file or a directory (based on the provided type), respecting Nuxt alias and extensions options.
+*
+* If a path cannot be resolved, normalized input will be returned unless the `fallbackToOriginal` option is set to `true`,
+* in which case the original input path will be returned.
+*/
 async function resolvePath(path, opts = {}) {
 	const { type = "file" } = opts;
 	const res = await _resolvePathGranularly(path, {
@@ -281,6 +387,9 @@ async function resolvePath(path, opts = {}) {
 	if (res.type === type) return res.path;
 	return opts.fallbackToOriginal ? path : res.path;
 }
+/**
+* Try to resolve first existing file in paths
+*/
 async function findPath(paths, opts, pathType = "file") {
 	for (const path of toArray(paths)) {
 		const res = await _resolvePathGranularly(path, {
@@ -292,10 +401,16 @@ async function findPath(paths, opts, pathType = "file") {
 	}
 	return null;
 }
+/**
+* Resolve path aliases respecting Nuxt alias options
+*/
 function resolveAlias(path, alias) {
 	alias ||= tryUseNuxt()?.options.alias || {};
 	return resolveAlias$1(path, alias);
 }
+/**
+* Create a relative resolver
+*/
 function createResolver(base) {
 	if (!base) throw new Error("`base` argument is missing for createResolver(base)!");
 	base = base.toString();
@@ -398,6 +513,15 @@ function existsInVFS(path, nuxt = tryUseNuxt()) {
 	if (path in nuxt.vfs) return true;
 	return (nuxt.apps.default?.templates ?? nuxt.options.build.templates).some((template) => template.dst === path);
 }
+/**
+* Resolve absolute file paths in the provided directory with respect to `.nuxtignore` and return them sorted.
+* @param path path to the directory to resolve files in
+* @param pattern glob pattern or an array of glob patterns to match files
+* @param opts options for globbing
+* @param opts.followSymbolicLinks whether to follow symbolic links, default is `true`
+* @param opts.ignore additional glob patterns to ignore
+* @returns sorted array of absolute file paths
+*/
 async function resolveFiles(path, pattern, opts = {}) {
 	const files = [];
 	for (const p of await glob(pattern, {
@@ -408,6 +532,8 @@ async function resolveFiles(path, pattern, opts = {}) {
 	})) if (!isIgnored(p)) files.push(p);
 	return files.sort();
 }
+//#endregion
+//#region src/internal/esm.ts
 function directoryToURL(dir) {
 	return pathToFileURL(dir + "/");
 }
@@ -439,17 +565,25 @@ function tryImportModule(id, opts) {
 		return importModule(id, opts).catch(() => void 0);
 	} catch {}
 }
+/**
+* @deprecated Please use `importModule` instead.
+*/
 function requireModule(id, opts) {
 	const caller = getUserCaller();
 	warn(`[@nuxt/kit] \`requireModule\` is deprecated${caller ? ` (used at \`${resolveAlias(caller.source)}:${caller.line}:${caller.column}\`)` : ""}. Please use \`importModule\` instead.`);
 	const resolvedPath = resolveModule(id, opts);
 	return createJiti(import.meta.url, { interopDefault: opts?.interopDefault !== false })(pathToFileURL(resolvedPath).href);
 }
+/**
+* @deprecated Please use `tryImportModule` instead.
+*/
 function tryRequireModule(id, opts) {
 	try {
 		return requireModule(id, opts);
 	} catch {}
 }
+//#endregion
+//#region src/module/install.ts
 const NODE_MODULES_RE = /[/\\]node_modules[/\\]/;
 const ignoredConfigKeys = new Set([
 	"components",
@@ -458,6 +592,10 @@ const ignoredConfigKeys = new Set([
 	"devtools",
 	"telemetry"
 ]);
+/**
+* Installs a set of modules on a Nuxt instance.
+* @internal
+*/
 async function installModules(modulesToInstall, resolvedModulePaths, nuxt = useNuxt()) {
 	const localLayerModuleDirs = [];
 	for (const l of nuxt.options._layers) {
@@ -529,12 +667,12 @@ 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 = [
+		const optionsFns = new Set([
 			...nuxt._moduleOptionsFunctions.get(moduleToInstall) || [],
 			...meta?.name ? nuxt._moduleOptionsFunctions.get(meta.name) || [] : [],
 			...configKey ? nuxt._moduleOptionsFunctions.get(configKey) || [] : []
-		];
-		if (optionsFns.length > 0) {
+		]);
+		if (optionsFns.size > 0) {
 			const overrides = [];
 			const defaults = [];
 			for (const fn of optionsFns) {
@@ -556,6 +694,10 @@ async function installModules(modulesToInstall, resolvedModulePaths, nuxt = useN
 	}
 	delete nuxt._moduleOptionsFunctions;
 }
+/**
+* Installs a module on a Nuxt instance.
+* @deprecated Use module dependencies.
+*/
 async function installModule(moduleToInstall, inlineOptions, nuxt = useNuxt()) {
 	const { nuxtModule, buildTimeModuleMeta, resolvedModulePath } = await loadNuxtModuleInstance(moduleToInstall, nuxt);
 	const localLayerModuleDirs = [];
@@ -730,19 +872,35 @@ async function callModule(nuxt, nuxtModule, moduleOptions = {}, options) {
 		entryPath
 	});
 }
+//#endregion
+//#region src/module/compatibility.ts
 function resolveNuxtModuleEntryName(m) {
 	if (typeof m === "object" && !Array.isArray(m)) return m.name;
 	if (Array.isArray(m)) return resolveNuxtModuleEntryName(m[0]);
 	return m || false;
 }
+/**
+* Check if a Nuxt module is installed by name.
+*
+* This will check both the installed modules and the modules to be installed. Note
+* that it cannot detect if a module is _going to be_ installed programmatically by another module.
+*/
 function hasNuxtModule(moduleName, nuxt = useNuxt()) {
 	return nuxt.options._installedModules.some(({ meta }) => meta.name === moduleName) || nuxt.options.modules.some((m) => moduleName === resolveNuxtModuleEntryName(m));
 }
+/**
+* Checks if a Nuxt module is compatible with a given semver version.
+*/
 async function hasNuxtModuleCompatibility(module, semverVersion, nuxt = useNuxt()) {
 	const version = await getNuxtModuleVersion(module, nuxt);
 	if (!version) return false;
 	return satisfies(normalizeSemanticVersion(version), semverVersion, { includePrerelease: true });
 }
+/**
+* Get the version of a Nuxt module.
+*
+* Scans installed modules for the version, if it's not found it will attempt to load the module instance and get the version from there.
+*/
 async function getNuxtModuleVersion(module, nuxt = useNuxt()) {
 	const moduleMeta = (typeof module === "string" ? { name: module } : await module.getMeta?.()) || {};
 	if (moduleMeta.version) return moduleMeta.version;
@@ -754,6 +912,8 @@ async function getNuxtModuleVersion(module, nuxt = useNuxt()) {
 	}
 	return false;
 }
+//#endregion
+//#region src/loader/config.ts
 const merger = createDefu((obj, key, value) => {
 	if (Array.isArray(obj[key]) && Array.isArray(value)) {
 		obj[key] = obj[key].concat(value);
@@ -834,7 +994,7 @@ async function loadNuxtConfig(opts) {
 	});
 	return await applyDefaults(NuxtConfigSchema, nuxtConfig);
 }
-async function loadNuxtSchema(cwd) {
+function loadNuxtSchema(cwd) {
 	const url = directoryToURL(cwd);
 	const urls = [url];
 	const nuxtPath = resolveModuleURL("nuxt", {
@@ -845,7 +1005,7 @@ async function loadNuxtSchema(cwd) {
 		from: url
 	});
 	if (nuxtPath) urls.unshift(nuxtPath);
-	return await import(resolveModuleURL("@nuxt/schema", {
+	return import(resolveModuleURL("@nuxt/schema", {
 		try: true,
 		from: urls
 	}) ?? "@nuxt/schema").then((r) => r.NuxtConfigSchema);
@@ -865,11 +1025,15 @@ async function withDefineNuxtConfig(fn) {
 		if (!globalSelf[key].count) delete globalSelf[key];
 	}
 }
+//#endregion
+//#region src/loader/schema.ts
 function extendNuxtSchema(def) {
 	useNuxt().hook("schema:extend", (schemas) => {
 		schemas.push(typeof def === "function" ? def() : def);
 	});
 }
+//#endregion
+//#region src/loader/nuxt.ts
 async function loadNuxt(opts) {
 	opts.cwd = resolve(opts.cwd || opts.rootDir || ".");
 	opts.overrides ||= opts.config || {};
@@ -890,10 +1054,14 @@ async function buildNuxt(nuxt) {
 	const { build } = await tryImportModule("nuxt-nightly", { url: rootURL }) || await importModule("nuxt", { url: rootURL });
 	return runWithNuxtContext(nuxt, () => build(nuxt));
 }
+//#endregion
+//#region src/head.ts
 function setGlobalHead(head) {
 	const nuxt = useNuxt();
 	nuxt.options.app.head = defu(head, nuxt.options.app.head);
 }
+//#endregion
+//#region src/imports.ts
 function addImports(imports) {
 	useNuxt().hook("imports:extend", (_imports) => {
 		_imports.push(...toArray(imports));
@@ -909,7 +1077,13 @@ function addImportsSources(presets) {
 		for (const preset of toArray(presets)) _presets.push(preset);
 	});
 }
+//#endregion
+//#region src/nitro.ts
 const HANDLER_METHOD_RE = /\.(get|head|patch|post|put|delete|connect|options|trace)(\.\w+)*$/;
+/**
+* normalize handler object
+*
+*/
 function normalizeHandlerMethod(handler) {
 	const [, method = void 0] = handler.handler.match(HANDLER_METHOD_RE) || [];
 	return {
@@ -918,17 +1092,31 @@ function normalizeHandlerMethod(handler) {
 		handler: normalize(handler.handler)
 	};
 }
+/**
+* Adds a nitro server handler
+*
+*/
 function addServerHandler(handler) {
 	useNuxt().options.serverHandlers.push(normalizeHandlerMethod(handler));
 }
+/**
+* Adds a nitro server handler for development-only
+*
+*/
 function addDevServerHandler(handler) {
 	useNuxt().options.devServerHandlers.push(handler);
 }
+/**
+* Adds a Nitro plugin
+*/
 function addServerPlugin(plugin) {
 	const nuxt = useNuxt();
 	nuxt.options.nitro.plugins ||= [];
 	nuxt.options.nitro.plugins.push(normalize(plugin));
 }
+/**
+* Adds routes to be prerendered
+*/
 function addPrerenderRoutes(routes) {
 	const nuxt = useNuxt();
 	routes = toArray(routes).filter(Boolean);
@@ -937,11 +1125,28 @@ function addPrerenderRoutes(routes) {
 		for (const route of routes) ctx.routes.add(route);
 	});
 }
+/**
+* Access to the Nitro instance
+*
+* **Note:** You can call `useNitro()` only after `ready` hook.
+*
+* **Note:** Changes to the Nitro instance configuration are not applied.
+* @example
+*
+* ```ts
+* nuxt.hook('ready', () => {
+*   console.log(useNitro())
+* })
+* ```
+*/
 function useNitro() {
 	const nuxt = useNuxt();
 	if (!nuxt._nitro) throw new Error("Nitro is not initialized yet. You can call `useNitro()` only after `ready` hook.");
 	return nuxt._nitro;
 }
+/**
+* Add server imports to be auto-imported by Nitro
+*/
 function addServerImports(imports) {
 	const nuxt = useNuxt();
 	const _imports = toArray(imports);
@@ -951,6 +1156,9 @@ function addServerImports(imports) {
 		config.imports.imports.push(..._imports);
 	});
 }
+/**
+* Add directories to be scanned for auto-imports by Nitro
+*/
 function addServerImportsDir(dirs, opts = {}) {
 	const nuxt = useNuxt();
 	const _dirs = toArray(dirs);
@@ -960,12 +1168,23 @@ function addServerImportsDir(dirs, opts = {}) {
 		config.imports.dirs[opts.prepend ? "unshift" : "push"](..._dirs);
 	});
 }
+/**
+* Add directories to be scanned by Nitro. It will check for subdirectories,
+* which will be registered just like the `~~/server` folder is.
+*/
 function addServerScanDir(dirs, opts = {}) {
 	useNuxt().hook("nitro:config", (config) => {
 		config.scanDirs ||= [];
 		for (const dir of toArray(dirs)) config.scanDirs[opts.prepend ? "unshift" : "push"](dir);
 	});
 }
+//#endregion
+//#region src/runtime-config.ts
+/**
+* Access 'resolved' Nuxt runtime configuration, with values updated from environment.
+*
+* This mirrors the runtime behavior of Nitro.
+*/
 function useRuntimeConfig() {
 	const nuxt = useNuxt();
 	return applyEnv(klona(nuxt.options.nitro.runtimeConfig), {
@@ -974,6 +1193,9 @@ function useRuntimeConfig() {
 		envExpansion: nuxt.options.nitro.experimental?.envExpansion ?? !!process.env.NITRO_ENV_EXPANSION
 	});
 }
+/**
+* Update Nuxt runtime configuration.
+*/
 function updateRuntimeConfig(runtimeConfig) {
 	const nuxt = useNuxt();
 	Object.assign(nuxt.options.nitro.runtimeConfig, defu(runtimeConfig, nuxt.options.nitro.runtimeConfig));
@@ -1011,6 +1233,8 @@ function _expandFromEnv(value, env = process.env) {
 		return env[key] || match;
 	});
 }
+//#endregion
+//#region src/build.ts
 const extendWebpackCompatibleConfig = (builder) => (fn, options = {}) => {
 	const nuxt = useNuxt();
 	if (options.dev === false && nuxt.options.dev) return;
@@ -1026,8 +1250,23 @@ const extendWebpackCompatibleConfig = (builder) => (fn, options = {}) => {
 		}
 	});
 };
+/**
+* Extend webpack config
+*
+* The fallback function might be called multiple times
+* when applying to both client and server builds.
+*/
 const extendWebpackConfig = extendWebpackCompatibleConfig("webpack");
+/**
+* Extend rspack config
+*
+* The fallback function might be called multiple times
+* when applying to both client and server builds.
+*/
 const extendRspackConfig = extendWebpackCompatibleConfig("rspack");
+/**
+* Extend Vite config
+*/
 function extendViteConfig(fn, options = {}) {
 	const nuxt = useNuxt();
 	if (options.dev === false && nuxt.options.dev) return;
@@ -1038,6 +1277,9 @@ function extendViteConfig(fn, options = {}) {
 	}
 	return nuxt.hook("vite:extend", ({ config }) => fn(config));
 }
+/**
+* Append webpack plugin to the config.
+*/
 function addWebpackPlugin(pluginOrGetter, options) {
 	extendWebpackConfig(async (config) => {
 		const method = options?.prepend ? "unshift" : "push";
@@ -1046,6 +1288,9 @@ function addWebpackPlugin(pluginOrGetter, options) {
 		config.plugins[method](...toArray(plugin));
 	}, options);
 }
+/**
+* Append rspack plugin to the config.
+*/
 function addRspackPlugin(pluginOrGetter, options) {
 	extendRspackConfig(async (config) => {
 		const method = options?.prepend ? "unshift" : "push";
@@ -1054,6 +1299,9 @@ function addRspackPlugin(pluginOrGetter, options) {
 		config.plugins[method](...toArray(plugin));
 	}, options);
 }
+/**
+* Append Vite plugin to the config.
+*/
 function addVitePlugin(pluginOrGetter, options = {}) {
 	const nuxt = useNuxt();
 	if (options.dev === false && nuxt.options.dev) return;
@@ -1094,6 +1342,11 @@ function addBuildPlugin(pluginFactory, options) {
 	if (pluginFactory.webpack) addWebpackPlugin(pluginFactory.webpack, options);
 	if (pluginFactory.rspack) addRspackPlugin(pluginFactory.rspack, options);
 }
+//#endregion
+//#region src/components.ts
+/**
+* Register a directory to be scanned for components and imported only when used.
+*/
 function addComponentsDir(dir, opts = {}) {
 	const nuxt = useNuxt();
 	nuxt.options.components ||= [];
@@ -1102,6 +1355,9 @@ function addComponentsDir(dir, opts = {}) {
 		dirs[opts.prepend ? "unshift" : "push"](dir);
 	});
 }
+/**
+* This utility takes a file path or npm package that is scanned for named exports, which are get added automatically
+*/
 function addComponentExports(opts) {
 	const nuxt = useNuxt();
 	const components = [];
@@ -1116,6 +1372,9 @@ function addComponentExports(opts) {
 	});
 	addComponents(components);
 }
+/**
+* Register a component by its name and filePath.
+*/
 function addComponent(opts) {
 	addComponents([normalizeComponent(opts)]);
 }
@@ -1159,6 +1418,11 @@ function normalizeComponent(opts) {
 		...opts
 	};
 }
+//#endregion
+//#region src/template.ts
+/**
+* Renders given template during build into the virtual file system (and optionally to disk in the project `buildDir`)
+*/
 function addTemplate(_template) {
 	const nuxt = useNuxt();
 	const template = normalizeTemplate(_template);
@@ -1174,12 +1438,23 @@ function addTemplate(_template) {
 	nuxt.options.build.templates.push(template);
 	return template;
 }
+/**
+* Adds a virtual file that can be used within the Nuxt Nitro server build.
+*/
 function addServerTemplate(template) {
 	const nuxt = useNuxt();
 	nuxt.options.nitro.virtual ||= {};
 	nuxt.options.nitro.virtual[template.filename] = template.getContents;
 	return template;
 }
+/**
+* Renders given types during build to disk in the project `buildDir`
+* and register them as types.
+*
+* You can pass a second context object to specify in which context the type should be added.
+*
+* If no context object is passed, then it will only be added to the nuxt context.
+*/
 function addTypeTemplate(_template, context) {
 	const nuxt = useNuxt();
 	const template = addTemplate(_template);
@@ -1203,6 +1478,9 @@ function addTypeTemplate(_template, context) {
 	});
 	return template;
 }
+/**
+* Normalize a nuxt template object
+*/
 function normalizeTemplate(template, buildDir) {
 	if (!template) throw new Error("Invalid template: " + JSON.stringify(template));
 	if (typeof template === "string") template = { src: template };
@@ -1220,8 +1498,13 @@ function normalizeTemplate(template, buildDir) {
 	template.dst ||= resolve(buildDir ?? useNuxt().options.buildDir, template.filename);
 	return template;
 }
+/**
+* Trigger rebuilding Nuxt templates
+*
+* You can pass a filter within the options to selectively regenerate a subset of templates.
+*/
 async function updateTemplates(options) {
-	return await tryUseNuxt()?.hooks.callHook("builder:generateApp", options);
+	await tryUseNuxt()?.hooks.callHook("builder:generateApp", options);
 }
 function resolveLayerPaths(dirs, projectBuildDir) {
 	const relativeRootDir = relativeWithDot(projectBuildDir, dirs.root);
@@ -1594,6 +1877,8 @@ function relativeWithDot(from, to) {
 function withTrailingSlash$1(dir) {
 	return dir.replace(/[^/]$/, "$&/");
 }
+//#endregion
+//#region src/layout.ts
 const LAYOUT_RE = /["']/g;
 function addLayout(template, name) {
 	const nuxt = useNuxt();
@@ -1617,6 +1902,8 @@ const strippedAtAliases = {
 	"@": "",
 	"@@": ""
 };
+//#endregion
+//#region src/pages.ts
 function extendPages(cb) {
 	useNuxt().hook("pages:extend", cb);
 }
@@ -1643,6 +1930,11 @@ function addRouteMiddleware(input, options = {}) {
 		}
 	});
 }
+//#endregion
+//#region src/plugin.ts
+/**
+* Normalize a nuxt plugin object
+*/
 const pluginSymbol = Symbol.for("nuxt plugin");
 function normalizePlugin(plugin) {
 	if (typeof plugin === "string") plugin = { src: plugin };
@@ -1676,10 +1968,14 @@ function addPlugin(_plugin, opts = {}) {
 	nuxt.options.plugins[opts.append ? "push" : "unshift"](plugin);
 	return plugin;
 }
+/**
+* Adds a template and registers as a nuxt plugin.
+*/
 function addPluginTemplate(plugin, opts = {}) {
 	return addPlugin(typeof plugin === "string" ? { src: plugin } : {
 		...plugin,
 		src: addTemplate(plugin).dst
 	}, 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 };