@analogjs/vite-plugin-nitro 3.0.0-alpha.9 → 3.0.0-alpha.91

package/src/lib/vite-plugin-nitro.js

@@ -1,24 +1,65 @@
 import { buildServer, isVercelPreset } from "./build-server.js";
 import { getBundleOptionsKey, isRolldown } from "./utils/rolldown.js";
-import { buildSSRApp } from "./build-ssr.js";
-import { apiMiddleware, clientRenderer, ssrRenderer } from "./utils/renderers.js";
+import { buildClientApp, buildSSRApp } from "./build-ssr.js";
+import { clientRenderer, ssrRenderer } from "./utils/renderers.js";
 import { pageEndpointsPlugin } from "./plugins/page-endpoints.js";
+import { serverFnIdPlugin } from "./plugins/server-fn-id-plugin.js";
 import { getPageHandlers } from "./utils/get-page-handlers.js";
+import { getServerFnHandlers } from "./utils/get-server-fn-handlers.js";
+import { SERVER_FN_DISPATCH_VIRTUAL, buildServerFnDispatchModule, getServerFnDispatchHandler } from "./utils/server-fn-endpoints.js";
 import { buildSitemap } from "./build-sitemap.js";
 import { toWebRequest, writeWebResponseToNode } from "./utils/node-web-bridge.js";
 import { devServerPlugin } from "./plugins/dev-server-plugin.js";
 import { getMatchingContentFilesWithFrontMatter } from "./utils/get-content-files.js";
+import { debugNitro, debugSsr } from "./utils/debug.js";
 import { build, createDevServer, createNitro } from "nitro/builder";
 import { mergeConfig, normalizePath } from "vite";
 import { relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 //#region packages/vite-plugin-nitro/src/lib/vite-plugin-nitro.ts
-function createNitroMiddlewareHandler(handler) {
+function isObjectHook(value) {
+	return !!value && typeof value === "object" && "handler" in value;
+}
+function cloneObjectHook(hook) {
+	if (!isObjectHook(hook)) return hook;
 	return {
-		route: "/**",
-		handler,
-		middleware: true
+		...hook,
+		handler: hook.handler
+	};
+}
+function cloneUserPlugin(plugin) {
+	if (!plugin || typeof plugin !== "object") return plugin;
+	const pluginRecord = plugin;
+	const clone = Object.assign(Object.create(Object.getPrototypeOf(plugin)), pluginRecord);
+	for (const key of Object.keys(pluginRecord)) clone[key] = cloneObjectHook(pluginRecord[key]);
+	return clone;
+}
+function cloneEnvironmentEntries(environments) {
+	if (!environments || typeof environments !== "object") return environments;
+	return Object.fromEntries(Object.entries(environments).map(([name, environment]) => {
+		if (!environment || typeof environment !== "object") return [name, environment];
+		const environmentRecord = environment;
+		return [name, {
+			...environmentRecord,
+			build: environmentRecord["build"] && typeof environmentRecord["build"] === "object" ? { ...environmentRecord["build"] } : environmentRecord["build"]
+		}];
+	}));
+}
+function cloneUserConfig(userConfig) {
+	const { environments, resolve, build, server, plugins } = userConfig;
+	const test = userConfig.test;
+	return {
+		...userConfig,
+		plugins: plugins?.map(cloneUserPlugin),
+		build: build && { ...build },
+		environments: cloneEnvironmentEntries(environments),
+		server: server && { ...server },
+		test: test && { ...test },
+		resolve: resolve && {
+			...resolve,
+			alias: Array.isArray(resolve.alias) ? [...resolve.alias] : resolve.alias && typeof resolve.alias === "object" ? { ...resolve.alias } : resolve.alias
+		}
 	};
 }
 /**
@@ -87,10 +128,137 @@ function sanitizeNitroBundlerConfig(_nitro, bundlerConfig) {
 		};
 	}
 }
-function resolveClientOutputPath(cachedPath, workspaceRoot, rootDir, configuredOutDir, ssrBuild) {
-	if (cachedPath) return cachedPath;
-	if (!ssrBuild) return resolve(workspaceRoot, rootDir, configuredOutDir || "dist/client");
-	return resolve(workspaceRoot, "dist", rootDir, "client");
+function resolveClientOutputPath(cachedPath, workspaceRoot, rootDir, configuredOutDir) {
+	if (cachedPath) {
+		debugNitro("resolveClientOutputPath using cached path", {
+			cachedPath,
+			workspaceRoot,
+			rootDir,
+			configuredOutDir
+		});
+		return cachedPath;
+	}
+	if (configuredOutDir) {
+		const resolvedPath = normalizePath(resolve(workspaceRoot, rootDir, configuredOutDir));
+		debugNitro("resolveClientOutputPath using configured build.outDir", {
+			workspaceRoot,
+			rootDir,
+			configuredOutDir,
+			resolvedPath
+		});
+		return resolvedPath;
+	}
+	const resolvedPath = normalizePath(resolve(workspaceRoot, "dist", rootDir, "client"));
+	debugNitro("resolveClientOutputPath using default dist client path", {
+		workspaceRoot,
+		rootDir,
+		configuredOutDir,
+		resolvedPath
+	});
+	return resolvedPath;
+}
+function getEnvironmentBuildOutDir(environment) {
+	if (!environment || typeof environment !== "object") return;
+	const environmentConfig = environment;
+	return environmentConfig.config?.build?.outDir ?? environmentConfig.build?.outDir;
+}
+function resolveBuiltClientOutputPath(cachedPath, workspaceRoot, rootDir, configuredOutDir, environment) {
+	const environmentOutDir = getEnvironmentBuildOutDir(environment);
+	if (environmentOutDir) {
+		const resolvedPath = normalizePath(resolve(workspaceRoot, rootDir, environmentOutDir));
+		debugNitro("resolveBuiltClientOutputPath using environment outDir", {
+			cachedPath,
+			workspaceRoot,
+			rootDir,
+			configuredOutDir,
+			environmentOutDir,
+			resolvedPath
+		});
+		return resolvedPath;
+	}
+	debugNitro("resolveBuiltClientOutputPath falling back to shared resolver", {
+		cachedPath,
+		workspaceRoot,
+		rootDir,
+		configuredOutDir,
+		environmentOutDir
+	});
+	return resolveClientOutputPath(cachedPath, workspaceRoot, rootDir, configuredOutDir);
+}
+function getNitroPublicOutputDir(nitroConfig) {
+	const publicDir = nitroConfig.output?.publicDir;
+	if (!publicDir) throw new Error("Nitro public output directory is required to build the sitemap.");
+	return publicDir;
+}
+function readDirectoryEntries(path) {
+	try {
+		return readdirSync(path).sort();
+	} catch (error) {
+		return [`<<unable to read directory: ${error instanceof Error ? error.message : String(error)}>>`];
+	}
+}
+function getPathDebugInfo(path) {
+	return {
+		rawPath: path,
+		normalizedPath: normalizePath(path),
+		exists: existsSync(path),
+		entries: existsSync(path) ? readDirectoryEntries(path) : []
+	};
+}
+function assetSourceToString(source) {
+	return typeof source === "string" ? source : Buffer.from(source).toString("utf8");
+}
+function captureClientIndexHtmlFromBundle(bundle, hook) {
+	const indexHtmlAsset = Object.values(bundle).find((chunk) => chunk.type === "asset" && chunk.fileName === "index.html" && typeof chunk.source !== "undefined");
+	if (!indexHtmlAsset?.source) {
+		debugNitro(`client bundle did not expose index.html during ${hook}`, {
+			hook,
+			bundleKeys: Object.keys(bundle).sort(),
+			assetFileNames: Object.values(bundle).filter((chunk) => chunk.type === "asset").map((chunk) => chunk.fileName).filter(Boolean)
+		});
+		return;
+	}
+	const indexHtml = assetSourceToString(indexHtmlAsset.source);
+	debugNitro(`captured client bundle index.html asset during ${hook}`, {
+		hook,
+		fileName: indexHtmlAsset.fileName,
+		htmlLength: indexHtml.length
+	});
+	return indexHtml;
+}
+function registerIndexHtmlVirtual(nitroConfig, clientOutputPath, inlineIndexHtml) {
+	const indexHtmlPath = resolve(clientOutputPath, "index.html");
+	debugNitro("registerIndexHtmlVirtual inspecting client output", {
+		platform: process.platform,
+		cwd: process.cwd(),
+		clientOutputPath,
+		clientOutputPathInfo: getPathDebugInfo(clientOutputPath),
+		indexHtmlPath,
+		indexHtmlExists: existsSync(indexHtmlPath),
+		hasInlineIndexHtml: typeof inlineIndexHtml === "string"
+	});
+	if (!existsSync(indexHtmlPath) && typeof inlineIndexHtml !== "string") {
+		debugNitro("registerIndexHtmlVirtual missing index.html", {
+			platform: process.platform,
+			cwd: process.cwd(),
+			clientOutputPath,
+			clientOutputPathInfo: getPathDebugInfo(clientOutputPath),
+			indexHtmlPath,
+			hasInlineIndexHtml: typeof inlineIndexHtml === "string",
+			nitroOutput: nitroConfig.output,
+			nitroPublicAssets: nitroConfig.publicAssets
+		});
+		throw new Error(`[analog] Client build output not found at ${indexHtmlPath}.\nEnsure the client environment build completed successfully before the server build.`);
+	}
+	const indexHtml = typeof inlineIndexHtml === "string" ? inlineIndexHtml : readFileSync(indexHtmlPath, "utf8");
+	debugNitro("registerIndexHtmlVirtual using HTML template source", {
+		source: typeof inlineIndexHtml === "string" ? "captured client bundle asset" : "client output index.html file",
+		indexHtmlPath
+	});
+	nitroConfig.virtual = {
+		...nitroConfig.virtual,
+		"#analog/index": `export default ${JSON.stringify(indexHtml)};`
+	};
 }
 /**
 * Converts the built SSR entry path into a specifier that Nitro's bundler
@@ -147,7 +315,6 @@ function nitro(options, nitroOptions) {
 	const baseURL = process.env["NITRO_APP_BASE_URL"] || "";
 	const prefix = baseURL ? baseURL.substring(0, baseURL.length - 1) : "";
 	const apiPrefix = `/${options?.apiPrefix || "api"}`;
-	const useAPIMiddleware = typeof options?.useAPIMiddleware !== "undefined" ? options?.useAPIMiddleware : true;
 	const viteRolldownOutput = options?.vite?.build?.rolldownOptions?.output;
 	const viteRolldownOutputConfig = viteRolldownOutput && !Array.isArray(viteRolldownOutput) ? viteRolldownOutput : void 0;
 	const codeSplitting = viteRolldownOutputConfig?.codeSplitting;
@@ -157,10 +324,12 @@ function nitro(options, nitroOptions) {
 	let config;
 	let nitroConfig;
 	let environmentBuild = false;
-	let hasAPIDir = false;
+	let hasServerFns = false;
 	let clientOutputPath = "";
-	let rendererIndexEntry = "";
+	let clientIndexHtml;
+	let legacyClientSubBuild = false;
 	const rollupExternalEntries = [];
+	const sitemapRoutes = [];
 	const routeSitemaps = {};
 	const routeSourceFiles = {};
 	let rootDir = workspaceRoot;
@@ -168,7 +337,8 @@ function nitro(options, nitroOptions) {
 		options?.ssr ? devServerPlugin({
 			entryServer: options?.entryServer,
 			index: options?.index,
-			routeRules: nitroOptions?.routeRules
+			routeRules: nitroOptions?.routeRules,
+			i18n: options?.i18n
 		}) : false,
 		{
 			name: "@analogjs/vite-plugin-nitro",
@@ -176,20 +346,48 @@ function nitro(options, nitroOptions) {
 				isServe = command === "serve";
 				isBuild = command === "build";
 				ssrBuild = userConfig.build?.ssr === true;
-				config = userConfig;
+				config = cloneUserConfig(userConfig);
 				isTest = isTest ? isTest : mode === "test";
-				rootDir = relative(workspaceRoot, config.root || ".") || ".";
-				hasAPIDir = existsSync(resolve(workspaceRoot, rootDir, `${sourceRoot}/server/routes/${options?.apiPrefix || "api"}`));
+				rollupExternalEntries.length = 0;
+				clientIndexHtml = void 0;
+				sitemapRoutes.length = 0;
+				for (const key of Object.keys(routeSitemaps)) delete routeSitemaps[key];
+				for (const key of Object.keys(routeSourceFiles)) delete routeSourceFiles[key];
+				const resolvedConfigRoot = config.root ? resolve(workspaceRoot, config.root) : workspaceRoot;
+				rootDir = relative(workspaceRoot, resolvedConfigRoot) || ".";
 				const buildPreset = process.env["BUILD_PRESET"] ?? nitroOptions?.preset ?? (process.env["VERCEL"] ? "vercel" : void 0);
 				const pageHandlers = getPageHandlers({
 					workspaceRoot,
 					sourceRoot,
 					rootDir,
-					additionalPagesDirs: options?.additionalPagesDirs,
-					hasAPIDir
+					additionalPagesDirs: options?.additionalPagesDirs
 				});
-				const resolvedClientOutputPath = resolveClientOutputPath(clientOutputPath, workspaceRoot, rootDir, config.build?.outDir, ssrBuild);
-				rendererIndexEntry = normalizePath(resolve(resolvedClientOutputPath, "index.html"));
+				const resolvedClientOutputPath = resolveClientOutputPath(clientOutputPath, workspaceRoot, rootDir, config.build?.outDir);
+				debugNitro("nitro config resolved client output path", {
+					platform: process.platform,
+					workspaceRoot,
+					configRoot: config.root,
+					resolvedConfigRoot,
+					rootDir,
+					buildOutDir: config.build?.outDir,
+					clientOutputPath,
+					resolvedClientOutputPath,
+					hasEnvironmentConfig: !!config.environments,
+					clientEnvironmentOutDir: config.environments?.["client"] && typeof config.environments["client"] === "object" && "build" in config.environments["client"] ? config.environments["client"].build?.outDir : void 0
+				});
+				const serverFnModules = getServerFnHandlers({
+					workspaceRoot,
+					sourceRoot,
+					rootDir,
+					additionalServerFnDirs: options?.additionalServerFnDirs
+				});
+				const serverFnAppConfigModule = resolveServerFnAppConfigModule(workspaceRoot, rootDir, sourceRoot);
+				hasServerFns = serverFnModules.length > 0;
+				const serverFnHandlers = hasServerFns ? [getServerFnDispatchHandler()] : [];
+				const serverFnVirtual = serverFnModules.length > 0 ? { [SERVER_FN_DISPATCH_VIRTUAL]: buildServerFnDispatchModule({
+					modules: serverFnModules,
+					appConfigModule: serverFnAppConfigModule
+				}) } : {};
 				nitroConfig = {
 					rootDir: normalizePath(rootDir),
 					preset: buildPreset,
@@ -202,36 +400,43 @@ function nitro(options, nitroOptions) {
 						publicDir: normalizePath(resolve(workspaceRoot, "dist", rootDir, "analog/public"))
 					},
 					buildDir: normalizePath(resolve(workspaceRoot, "dist", rootDir, ".nitro")),
-					typescript: { generateTsConfig: false },
 					runtimeConfig: {
 						apiPrefix: apiPrefix.substring(1),
 						prefix
 					},
 					renderer: false,
-					imports: { autoImport: false },
 					hooks: { "rollup:before": createRollupBeforeHook(rollupExternalEntries) },
 					rollupConfig: {
 						onwarn(warning) {
 							if (warning.message.includes("empty chunk") && warning.message.endsWith(".server")) return;
 						},
-						plugins: [pageEndpointsPlugin()]
+						plugins: [pageEndpointsPlugin(), serverFnIdPlugin(normalizePath(resolve(workspaceRoot, rootDir)))]
 					},
-					handlers: [...hasAPIDir ? [] : useAPIMiddleware ? [createNitroMiddlewareHandler("#ANALOG_API_MIDDLEWARE")] : [], ...pageHandlers],
-					routeRules: hasAPIDir ? void 0 : useAPIMiddleware ? void 0 : { [`${prefix}${apiPrefix}/**`]: { proxy: { to: "/**" } } },
+					...hasServerFns ? { moduleSideEffects: ["@angular/compiler", ...serverFnModules.map((m) => normalizePath(m.file))] } : {},
+					handlers: [...pageHandlers, ...serverFnHandlers],
+					routeRules: void 0,
 					virtual: {
-						"#ANALOG_SSR_RENDERER": ssrRenderer(rendererIndexEntry),
-						"#ANALOG_CLIENT_RENDERER": clientRenderer(rendererIndexEntry),
-						...hasAPIDir ? {} : { "#ANALOG_API_MIDDLEWARE": apiMiddleware }
+						"#ANALOG_SSR_RENDERER": ssrRenderer(),
+						"#ANALOG_CLIENT_RENDERER": clientRenderer(),
+						...serverFnVirtual
 					}
 				};
 				if (isVercelPreset(buildPreset)) nitroConfig = withVercelOutputAPI(nitroConfig, workspaceRoot);
 				if (isCloudflarePreset(buildPreset)) nitroConfig = withCloudflareOutput(nitroConfig);
 				if (isNetlifyPreset(buildPreset) && rootDir === "." && !existsSync(resolve(workspaceRoot, "netlify.toml"))) nitroConfig = withNetlifyOutputAPI(nitroConfig, workspaceRoot);
 				if (isFirebaseAppHosting()) nitroConfig = withAppHostingOutput(nitroConfig);
-				if (!ssrBuild && !isTest) clientOutputPath = resolvedClientOutputPath;
+				if (!ssrBuild && !isTest) {
+					clientOutputPath = resolvedClientOutputPath;
+					debugNitro("nitro config cached client output path for later SSR/Nitro build", {
+						ssrBuild,
+						isTest,
+						clientOutputPath
+					});
+				}
+				nitroConfig.alias = {};
 				if (isBuild) {
 					nitroConfig.publicAssets = [{
-						dir: normalizePath(clientOutputPath),
+						dir: normalizePath(resolvedClientOutputPath),
 						maxAge: 0
 					}];
 					const rendererHandler = options?.ssr ? "#ANALOG_SSR_RENDERER" : "#ANALOG_CLIENT_RENDERER";
@@ -249,12 +454,14 @@ function nitro(options, nitroOptions) {
 						nitroConfig.prerender.crawlLinks = options?.prerender?.discover;
 						let routes = [];
 						const prerenderRoutes = options?.prerender?.routes;
+						const hasExplicitPrerenderRoutes = typeof prerenderRoutes === "function" || Array.isArray(prerenderRoutes);
 						if (isArrayWithElements(prerenderRoutes)) routes = prerenderRoutes;
 						else if (typeof prerenderRoutes === "function") routes = await prerenderRoutes();
-						nitroConfig.prerender.routes = routes.reduce((prev, current) => {
+						const resolvedPrerenderRoutes = routes.reduce((prev, current) => {
 							if (!current) return prev;
 							if (typeof current === "string") {
 								prev.push(current);
+								sitemapRoutes.push(current);
 								return prev;
 							}
 							if ("route" in current) {
@@ -264,10 +471,11 @@ function nitro(options, nitroOptions) {
 									routeSourceFiles[current.route] = readFileSync(sourcePath, "utf8");
 								}
 								prev.push(current.route);
+								sitemapRoutes.push(current.route);
 								if ("staticData" in current) prev.push(`${apiPrefix}/_analog/pages/${current.route}`);
 								return prev;
 							}
-							getMatchingContentFilesWithFrontMatter(workspaceRoot, rootDir, current.contentDir).forEach((f) => {
+							getMatchingContentFilesWithFrontMatter(workspaceRoot, rootDir, current.contentDir, current.recursive).forEach((f) => {
 								const result = current.transform(f);
 								if (result) {
 									if (current.sitemap) routeSitemaps[result] = current.sitemap && typeof current.sitemap === "function" ? current.sitemap?.(f) : current.sitemap;
@@ -276,21 +484,23 @@ function nitro(options, nitroOptions) {
 										if (sourceContent) routeSourceFiles[result] = sourceContent;
 									}
 									prev.push(result);
+									sitemapRoutes.push(result);
 									if ("staticData" in current) prev.push(`${apiPrefix}/_analog/pages/${result}`);
 								}
 							});
 							return prev;
 						}, []);
+						nitroConfig.prerender.routes = hasExplicitPrerenderRoutes || resolvedPrerenderRoutes.length ? resolvedPrerenderRoutes : nitroConfig.prerender.routes ?? [];
 					}
 					if (ssrBuild || options?.ssr || nitroConfig.prerender?.routes?.length) {
+						nitroConfig.noExternals = appendNoExternals(nitroConfig.noExternals, "es-toolkit");
 						if (process.platform === "win32") nitroConfig.noExternals = appendNoExternals(nitroConfig.noExternals, "std-env");
-						rollupExternalEntries.push("rxjs", "node-fetch-native/dist/polyfill");
+						rollupExternalEntries.push("rxjs", "node-fetch-native/dist/polyfill", "sharp");
 						nitroConfig = {
 							...nitroConfig,
-							moduleSideEffects: ["zone.js/node", "zone.js/fesm2015/zone-node"],
 							handlers: [
-								...hasAPIDir ? [] : useAPIMiddleware ? [createNitroMiddlewareHandler("#ANALOG_API_MIDDLEWARE")] : [],
 								...pageHandlers,
+								...serverFnHandlers,
 								{
 									handler: rendererHandler,
 									route: "/**",
@@ -301,10 +511,12 @@ function nitro(options, nitroOptions) {
 					}
 				}
 				nitroConfig = mergeConfig(nitroConfig, nitroOptions);
+				if (environmentBuild || ssrBuild || isServe) return {};
 				return {
 					environments: {
 						client: { build: {
 							outDir: config?.build?.outDir || resolve(workspaceRoot, "dist", rootDir, "client"),
+							emptyOutDir: true,
 							...isRolldown() && codeSplitting !== void 0 ? { rolldownOptions: { output: {
 								...viteRolldownOutputConfig,
 								codeSplitting
@@ -313,29 +525,81 @@ function nitro(options, nitroOptions) {
 						ssr: { build: {
 							ssr: true,
 							[getBundleOptionsKey()]: { input: options?.entryServer || resolve(workspaceRoot, rootDir, `${sourceRoot}/main.server.ts`) },
-							outDir: options?.ssrBuildDir || resolve(workspaceRoot, "dist", rootDir, "ssr")
+							outDir: options?.ssrBuildDir || resolve(workspaceRoot, "dist", rootDir, "ssr"),
+							emptyOutDir: false
 						} }
 					},
 					builder: {
 						sharedPlugins: true,
 						buildApp: async (builder) => {
 							environmentBuild = true;
-							const builds = [builder.build(builder.environments["client"])];
-							if (options?.ssr || nitroConfig.prerender?.routes?.length) builds.push(builder.build(builder.environments["ssr"]));
-							await Promise.all(builds);
+							debugNitro("builder.buildApp starting", {
+								platform: process.platform,
+								workspaceRoot,
+								rootDir,
+								cachedClientOutputPath: clientOutputPath,
+								configuredBuildOutDir: config.build?.outDir,
+								clientEnvironmentOutDir: getEnvironmentBuildOutDir(builder.environments["client"]),
+								ssrEnvironmentOutDir: getEnvironmentBuildOutDir(builder.environments["ssr"])
+							});
+							await builder.build(builder.environments["client"]);
+							const postClientBuildOutputPath = resolveBuiltClientOutputPath(clientOutputPath, workspaceRoot, rootDir, config.build?.outDir, builder.environments["client"]);
+							registerIndexHtmlVirtual(nitroConfig, postClientBuildOutputPath, clientIndexHtml);
+							debugNitro("builder.buildApp completed client build", {
+								postClientBuildOutputPath,
+								postClientBuildOutputInfo: getPathDebugInfo(postClientBuildOutputPath),
+								postClientBuildIndexHtmlPath: resolve(postClientBuildOutputPath, "index.html"),
+								postClientBuildIndexHtmlExists: existsSync(resolve(postClientBuildOutputPath, "index.html"))
+							});
+							if (options?.ssr || nitroConfig.prerender?.routes?.length) {
+								debugSsr("builder.buildApp starting SSR build", {
+									ssrEnabled: options?.ssr,
+									prerenderRoutes: nitroConfig.prerender?.routes
+								});
+								/**
+								* This launches the SSR environment as a second build from the
+								* shared plugin graph above. When debugging an apparent
+								* duplicate `@analogjs/vite-plugin-angular` registration, this
+								* is the handoff to inspect: the SSR builder replays the shared
+								* plugins for the server pass and may therefore expose multiple
+								* Angular-plugin entries in the SSR resolved config.
+								*
+								* That is expected for this orchestration path and should not
+								* be treated the same as a duplicated client build, where two
+								* Angular plugin instances would maintain separate style maps.
+								*/
+								await builder.build(builder.environments["ssr"]);
+								debugSsr("builder.buildApp completed SSR build", { ssrOutputPath: options?.ssrBuildDir || resolve(workspaceRoot, "dist", rootDir, "ssr") });
+							}
 							applySsrEntryAlias(nitroConfig, options, workspaceRoot, rootDir);
+							const resolvedClientOutputPath = resolveBuiltClientOutputPath(clientOutputPath, workspaceRoot, rootDir, config.build?.outDir, builder.environments["client"]);
+							nitroConfig.publicAssets = [{
+								dir: normalizePath(resolvedClientOutputPath),
+								maxAge: 0
+							}];
+							debugNitro("builder.buildApp resolved final client output path before Nitro build", {
+								resolvedClientOutputPath,
+								resolvedClientOutputInfo: getPathDebugInfo(resolvedClientOutputPath),
+								nitroPublicAssets: nitroConfig.publicAssets
+							});
 							await buildServer(options, nitroConfig, routeSourceFiles);
 							if (nitroConfig.prerender?.routes?.length && options?.prerender?.sitemap) {
-								const publicDir = nitroConfig.output?.publicDir;
-								if (!publicDir) throw new Error("Nitro public output directory is required to build the sitemap.");
 								console.log("Building Sitemap...");
-								await buildSitemap(config, options.prerender.sitemap, nitroConfig.prerender.routes, publicDir, routeSitemaps);
+								await buildSitemap(config, options.prerender.sitemap, sitemapRoutes.length ? sitemapRoutes : nitroConfig.prerender.routes, getNitroPublicOutputDir(nitroConfig), routeSitemaps, { apiPrefix: options?.apiPrefix || "api" });
 							}
 							console.log(`\n\nThe '@analogjs/platform' server has been successfully built.`);
 						}
 					}
 				};
 			},
+			generateBundle(_options, bundle) {
+				if (!isBuild || ssrBuild) return;
+				clientIndexHtml = captureClientIndexHtmlFromBundle(bundle, "generateBundle") ?? clientIndexHtml;
+			},
+			writeBundle(_options, bundle) {
+				if (!isBuild || ssrBuild) return;
+				clientIndexHtml = captureClientIndexHtmlFromBundle(bundle, "writeBundle") ?? clientIndexHtml;
+			},
 			async configureServer(viteServer) {
 				if (isServe && !isTest) {
 					const nitro = await createNitro({
@@ -345,41 +609,120 @@ function nitro(options, nitroOptions) {
 					});
 					const server = createDevServer(nitro);
 					await build(nitro);
+					const nitroSourceRoots = [normalizePath(resolve(workspaceRoot, rootDir, `${sourceRoot}/server`)), ...(options?.additionalAPIDirs || []).map((dir) => normalizePath(`${workspaceRoot}${dir}`))];
+					const isNitroSourceFile = (path) => {
+						const normalizedPath = normalizePath(path);
+						return nitroSourceRoots.some((root) => normalizedPath === root || normalizedPath.startsWith(`${root}/`));
+					};
+					let nitroRebuildPromise;
+					let nitroRebuildPending = false;
+					const rebuildNitroServer = () => {
+						if (nitroRebuildPromise) {
+							nitroRebuildPending = true;
+							return nitroRebuildPromise;
+						}
+						nitroRebuildPromise = (async () => {
+							do {
+								nitroRebuildPending = false;
+								await build(nitro);
+							} while (nitroRebuildPending);
+							viteServer.ws.send("analog:debug-full-reload", {
+								plugin: "vite-plugin-nitro",
+								reason: "nitro-server-rebuilt"
+							});
+							viteServer.ws.send({ type: "full-reload" });
+						})().catch((error) => {
+							viteServer.config.logger.error(`[analog] Failed to rebuild Nitro dev server.\n${error instanceof Error ? error.stack || error.message : String(error)}`);
+						}).finally(() => {
+							nitroRebuildPromise = void 0;
+						});
+						return nitroRebuildPromise;
+					};
+					const onNitroSourceChange = (path) => {
+						if (!isNitroSourceFile(path)) return;
+						rebuildNitroServer();
+					};
+					viteServer.watcher.on("add", onNitroSourceChange);
+					viteServer.watcher.on("change", onNitroSourceChange);
+					viteServer.watcher.on("unlink", onNitroSourceChange);
 					const apiHandler = async (req, res) => {
 						await writeWebResponseToNode(res, await server.fetch(toWebRequest(req)));
 					};
-					if (hasAPIDir) viteServer.middlewares.use((req, res, next) => {
+					viteServer.middlewares.use((req, res, next) => {
 						if (req.url?.startsWith(`${prefix}${apiPrefix}`)) {
 							apiHandler(req, res).catch((error) => next(error));
 							return;
 						}
 						next();
 					});
-					else viteServer.middlewares.use(apiPrefix, (req, res, next) => {
-						apiHandler(req, res).catch((error) => next(error));
-					});
 					viteServer.httpServer?.once("listening", () => {
 						process.env["ANALOG_HOST"] = !viteServer.config.server.host ? "localhost" : viteServer.config.server.host;
 						process.env["ANALOG_PORT"] = `${viteServer.config.server.port}`;
 					});
-					if (nitroOptions?.experimental?.websocket) viteServer.httpServer?.on("upgrade", server.upgrade);
+					if (nitroOptions?.experimental?.websocket) {
+						debugNitro("experimental websocket upgrade handler enabled");
+						viteServer.httpServer?.on("upgrade", server.upgrade);
+					}
 					console.log(`\n\nThe server endpoints are accessible under the "${prefix}${apiPrefix}" path.`);
 				}
 			},
 			async closeBundle() {
+				if (legacyClientSubBuild) return;
 				if (environmentBuild) return;
 				if (ssrBuild) return;
 				if (isBuild) {
+					const resolvedClientOutputPath = resolveClientOutputPath(clientOutputPath, workspaceRoot, rootDir, config.build?.outDir);
+					debugNitro("closeBundle resolved client output path before legacy SSR build", {
+						platform: process.platform,
+						workspaceRoot,
+						rootDir,
+						cachedClientOutputPath: clientOutputPath,
+						configuredBuildOutDir: config.build?.outDir,
+						resolvedClientOutputPath,
+						resolvedClientOutputInfo: getPathDebugInfo(resolvedClientOutputPath)
+					});
+					const indexHtmlPath = resolve(resolvedClientOutputPath, "index.html");
+					if (!existsSync(indexHtmlPath) && typeof clientIndexHtml !== "string") {
+						debugNitro("closeBundle rebuilding missing client output before SSR/Nitro", {
+							platform: process.platform,
+							workspaceRoot,
+							rootDir,
+							configuredBuildOutDir: config.build?.outDir,
+							resolvedClientOutputPath,
+							indexHtmlPath
+						});
+						legacyClientSubBuild = true;
+						try {
+							await buildClientApp(config, options);
+						} finally {
+							legacyClientSubBuild = false;
+						}
+					}
+					registerIndexHtmlVirtual(nitroConfig, resolvedClientOutputPath, clientIndexHtml);
 					if (options?.ssr) {
 						console.log("Building SSR application...");
 						await buildSSRApp(config, options);
+						debugSsr("closeBundle completed standalone SSR build", {
+							ssrBuildDir: options?.ssrBuildDir || resolve(workspaceRoot, "dist", rootDir, "ssr"),
+							clientOutputPathInfo: clientOutputPath ? getPathDebugInfo(clientOutputPath) : null
+						});
 					}
+					applySsrEntryAlias(nitroConfig, options, workspaceRoot, rootDir);
+					debugNitro("closeBundle resolved client output path before Nitro build", {
+						platform: process.platform,
+						workspaceRoot,
+						rootDir,
+						cachedClientOutputPath: clientOutputPath,
+						configuredBuildOutDir: config.build?.outDir,
+						resolvedClientOutputPath,
+						resolvedClientOutputInfo: getPathDebugInfo(resolvedClientOutputPath)
+					});
+					registerIndexHtmlVirtual(nitroConfig, resolvedClientOutputPath, clientIndexHtml);
+					await buildServer(options, nitroConfig, routeSourceFiles);
 					if (nitroConfig.prerender?.routes?.length && options?.prerender?.sitemap) {
 						console.log("Building Sitemap...");
-						await buildSitemap(config, options.prerender.sitemap, nitroConfig.prerender.routes, clientOutputPath, routeSitemaps);
+						await buildSitemap(config, options.prerender.sitemap, sitemapRoutes.length ? sitemapRoutes : nitroConfig.prerender.routes, getNitroPublicOutputDir(nitroConfig), routeSitemaps, { apiPrefix: options?.apiPrefix || "api" });
 					}
-					applySsrEntryAlias(nitroConfig, options, workspaceRoot, rootDir);
-					await buildServer(options, nitroConfig, routeSourceFiles);
 					console.log(`\n\nThe '@analogjs/platform' server has been successfully built.`);
 				}
 			}
@@ -387,7 +730,13 @@ function nitro(options, nitroOptions) {
 		{
 			name: "@analogjs/vite-plugin-nitro-api-prefix",
 			config() {
-				return { define: { ANALOG_API_PREFIX: `"${baseURL.substring(1)}${apiPrefix.substring(1)}"` } };
+				return { define: {
+					ANALOG_API_PREFIX: `"${baseURL.substring(1)}${apiPrefix.substring(1)}"`,
+					...options?.i18n ? {
+						ANALOG_I18N_DEFAULT_LOCALE: JSON.stringify(options.i18n.defaultLocale),
+						ANALOG_I18N_LOCALES: JSON.stringify(options.i18n.locales)
+					} : {}
+				} };
 			}
 		}
 	];
@@ -457,6 +806,10 @@ var withAppHostingOutput = (nitroConfig) => {
 		}
 	};
 };
+function resolveServerFnAppConfigModule(workspaceRoot, rootDir, sourceRoot) {
+	const root = normalizePath(resolve(workspaceRoot, rootDir));
+	return [`${root}/${sourceRoot}/app/app.config.server.ts`, `${root}/${sourceRoot}/app.config.server.ts`].find((candidate) => existsSync(candidate));
+}
 var isNetlifyPreset = (buildPreset) => process.env["NETLIFY"] || buildPreset && buildPreset.toLowerCase().includes("netlify");
 var withNetlifyOutputAPI = (nitroConfig, workspaceRoot) => ({
 	...nitroConfig,