@useavalon/avalon 0.1.11 → 0.1.13

package/src/nitro/config.ts

@@ -1,483 +1,483 @@
-/**
- * Nitro Configuration Module for Avalon
- *
- * This module provides configuration interfaces and utilities for integrating
- * Nitro as Avalon's server runtime. It handles preset configuration, route rules,
- * and merging Avalon-specific options with Nitro defaults.
- *
- * ## Static Asset Handling
- *
- * Nitro automatically serves static assets from the `public/` directory at the root path.
- * The configuration supports:
- * - `publicAssets`: Configures directories for static file serving
- * - `routeRules`: Configures cache headers for different asset types
- * - `staticAssets`: Avalon-specific static asset configuration
- *
- * Default route rules for static assets are generated by `createDefaultStaticAssetRouteRules()`:
- * - `/assets/**`, `/islands/**`, `/chunks/**`: Long cache (1 year, immutable)
- * - `/*.woff`, `/*.woff2`: Long cache for fonts
- * - `/*.html`, `/*.css`: Short cache with revalidation
- * - `/favicon.ico`: Medium cache (1 day)
- */
-
-import type { ResolvedAvalonConfig } from "../vite-plugin/types.ts";
-
-/**
- * Cache configuration options for route rules
- */
-export interface CacheOptions {
-  /** Maximum age in seconds for cache validity */
-  maxAge?: number;
-  /** Maximum age in seconds for stale content */
-  staleMaxAge?: number;
-  /** Enable stale-while-revalidate behavior */
-  swr?: boolean;
-}
-
-/**
- * Route rule configuration for caching, redirects, proxying, and headers
- */
-export interface RouteRule {
-  /** Cache configuration or boolean to enable/disable */
-  cache?: CacheOptions | boolean;
-  /** Redirect destination URL */
-  redirect?: string;
-  /** Proxy destination URL */
-  proxy?: string;
-  /** Custom headers to set */
-  headers?: Record<string, string>;
-  /** Enable CORS for this route */
-  cors?: boolean;
-}
-
-/**
- * Static asset serving configuration
- */
-export interface StaticAssetsConfig {
-  /**
-   * Directory containing public static assets
-   * @default "public"
-   */
-  publicDir?: string;
-
-  /**
-   * Directory containing compiled build output
-   * @default "dist"
-   */
-  buildDir?: string;
-
-  /**
-   * Enable serving pre-compressed assets (gzip, brotli)
-   * @default true
-   */
-  compression?: boolean;
-
-  /**
-   * Default cache control header for immutable static assets
-   * @default "public, max-age=31536000, immutable"
-   */
-  cacheControl?: string;
-
-  /**
-   * Cache control header for mutable assets (HTML, etc.)
-   * @default "public, max-age=0, must-revalidate"
-   */
-  mutableCacheControl?: string;
-
-  /**
-   * Custom headers to add to all static asset responses
-   */
-  headers?: Record<string, string>;
-}
-
-/**
- * Avalon-specific Nitro configuration options
- */
-export interface AvalonNitroConfig {
-  /**
-   * Deployment preset (vercel, cloudflare, deno-deploy, node-server, netlify, etc.)
-   * @default "node-server"
-   */
-  preset?: string;
-
-  /**
-   * Directory containing server routes
-   * @default "server"
-   */
-  serverDir?: string;
-
-  /**
-   * Directory containing pages (overrides Avalon config if set)
-   */
-  pagesDir?: string;
-
-  /**
-   * Enable streaming SSR responses
-   * @default true
-   */
-  streaming?: boolean;
-
-  /**
-   * Route rules for caching, redirects, proxying, and headers
-   * Keys are route patterns (e.g., "/api/**", "/static/**")
-   */
-  routeRules?: Record<string, RouteRule>;
-
-  /**
-   * Runtime configuration accessible via useRuntimeConfig()
-   * Can be overridden by NITRO_ prefixed environment variables
-   */
-  runtimeConfig?: Record<string, unknown>;
-
-  /**
-   * Public runtime configuration (exposed to client)
-   */
-  publicRuntimeConfig?: Record<string, unknown>;
-
-  /**
-   * Static asset serving configuration
-   */
-  staticAssets?: StaticAssetsConfig;
-
-  /** Nitro v3: Compatibility date for preset features (YYYY-MM-DD) */
-  compatibilityDate?: string;
-  /** Nitro v3: Dependencies to trace instead of bundle */
-  traceDeps?: string[];
-  /** Nitro v3: Rolldown-specific configuration */
-  rolldownConfig?: Record<string, unknown>;
-  /** Nitro v3: Custom server entry point */
-  serverEntry?: string;
-  /** Nitro v3: Renderer configuration, or false to disable */
-  renderer?: { handler: string } | false;
-  /** Nitro v3: Pre-compress public assets (gzip, brotli, zstd) */
-  compressPublicAssets?: boolean | { gzip?: boolean; brotli?: boolean; zstd?: boolean };
-}
-
-/**
- * Nitro configuration output structure
- * This matches the expected NitroConfig interface from nitro/types
- */
-export interface NitroConfigOutput {
-  /** Deployment preset */
-  preset: string;
-  /** Server directory */
-  serverDir: string;
-  /** Route rules */
-  routeRules: Record<string, RouteRule>;
-  /** Runtime configuration */
-  runtimeConfig: {
-    avalon: AvalonRuntimeConfig;
-    [key: string]: unknown;
-  };
-  /** Public runtime configuration */
-  publicRuntimeConfig?: Record<string, unknown>;
-  /** Renderer configuration, or false to disable */
-  renderer?: {
-    handler: string;
-  } | false;
-  /** Nitro v3: Compatibility date for preset features (YYYY-MM-DD) */
-  compatibilityDate?: string;
-  /** Nitro v3: Dependencies to trace instead of bundle */
-  traceDeps?: string[];
-  /** Nitro v3: Rolldown-specific configuration */
-  rolldownConfig?: Record<string, unknown>;
-  /** Nitro v3: Custom server entry point */
-  serverEntry?: string;
-  /** Nitro v3: Pre-compress public assets (gzip, brotli, zstd) */
-  compressPublicAssets?: boolean | { gzip?: boolean; brotli?: boolean; zstd?: boolean };
-  /** Public assets directory */
-  publicAssets?: Array<{
-    dir: string;
-    baseURL?: string;
-    maxAge?: number;
-  }>;
-  /** Server assets configuration */
-  serverAssets?: Array<{
-    baseName: string;
-    dir: string;
-  }>;
-  /** Static assets configuration */
-  staticAssets?: StaticAssetsConfig;
-}
-
-/**
- * Avalon-specific runtime configuration stored in Nitro's runtimeConfig
- */
-export interface AvalonRuntimeConfig {
-  /** Enable streaming SSR */
-  streaming: boolean;
-  /** Pages directory path */
-  pagesDir: string;
-  /** Layouts directory path */
-  layoutsDir: string;
-}
-
-/**
- * Default static assets configuration
- */
-export const DEFAULT_STATIC_ASSETS_CONFIG: Required<StaticAssetsConfig> = {
-  publicDir: "public",
-  buildDir: "dist",
-  compression: true,
-  cacheControl: "public, max-age=31536000, immutable",
-  mutableCacheControl: "public, max-age=0, must-revalidate",
-  headers: {},
-};
-
-/**
- * All valid Nitro v3 preset names (underscore convention).
- */
-export const VALID_V3_PRESETS: string[] = [
-  "node_server",
-  "node_middleware",
-  "vercel",
-  "cloudflare_module",
-  "cloudflare_pages",
-  "deno_deploy",
-  "deno_server",
-  "netlify_functions",
-  "netlify_edge",
-  "aws_lambda",
-  "azure_swa",
-  "firebase_functions",
-  "render_com",
-  "static",
-  "browser",
-];
-
-/**
- * Validates a preset name against the v3 preset list.
- * Returns the preset name if valid, throws if unrecognized.
- *
- * @param preset - The preset name to validate (must be a v3 name)
- * @returns The validated v3 preset name
- * @throws Error if the preset is not recognized
- */
-export function resolvePresetName(preset: string): string {
-  if (VALID_V3_PRESETS.includes(preset)) return preset;
-  throw new Error(
-    `Unknown Nitro preset: "${preset}". Valid presets: ${VALID_V3_PRESETS.join(", ")}`
-  );
-}
-
-/**
- * Default Nitro configuration values
- */
-export const DEFAULT_NITRO_CONFIG: Required<
-  Pick<AvalonNitroConfig, "preset" | "serverDir" | "streaming">
-> = {
-  preset: "node_server",
-  serverDir: "server",
-  streaming: true,
-};
-
-/**
- * Creates a Nitro configuration from Avalon plugin config and Nitro-specific options
- *
- * This function merges Avalon's resolved configuration with Nitro-specific options
- * to produce a complete Nitro configuration object. Avalon-specific settings are
- * stored in `runtimeConfig.avalon` for access by handlers.
- *
- * @param avalonNitroConfig - Nitro-specific configuration options
- * @param resolvedAvalonConfig - Resolved Avalon plugin configuration
- * @returns Complete Nitro configuration object
- *
- * @example
- * ```ts
- * const nitroConfig = createNitroConfig(
- *   { preset: 'vercel', streaming: true },
- *   resolvedAvalonConfig
- * );
- * ```
- */
-export function createNitroConfig(
-  avalonNitroConfig: AvalonNitroConfig,
-  resolvedAvalonConfig: ResolvedAvalonConfig
-): NitroConfigOutput {
-  // Determine final directory paths (Nitro config overrides Avalon config)
-  const pagesDir = avalonNitroConfig.pagesDir ?? resolvedAvalonConfig.pagesDir;
-  const layoutsDir = resolvedAvalonConfig.layoutsDir;
-
-  // Build Avalon runtime config
-  const avalonRuntimeConfig: AvalonRuntimeConfig = {
-    streaming: avalonNitroConfig.streaming ?? DEFAULT_NITRO_CONFIG.streaming,
-    pagesDir,
-    layoutsDir,
-  };
-
-  // Validate that runtimeConfig does not contain a 'nitro' key (reserved in v3)
-  if (avalonNitroConfig.runtimeConfig && "nitro" in avalonNitroConfig.runtimeConfig) {
-    throw new Error(
-      'The "nitro" key in runtimeConfig is reserved by Nitro v3 and cannot be used.'
-    );
-  }
-
-  // Merge user runtime config with Avalon runtime config
-  const runtimeConfig: NitroConfigOutput["runtimeConfig"] = {
-    avalon: avalonRuntimeConfig,
-    ...avalonNitroConfig.runtimeConfig,
-  };
-
-  // Merge static assets config with defaults
-  const staticAssetsConfig: StaticAssetsConfig = {
-    ...DEFAULT_STATIC_ASSETS_CONFIG,
-    ...avalonNitroConfig.staticAssets,
-  };
-
-  // Create default route rules for static assets
-  const defaultStaticRouteRules = createDefaultStaticAssetRouteRules(staticAssetsConfig);
-
-  // Merge user route rules with default static asset rules
-  const routeRules = mergeRouteRules(
-    defaultStaticRouteRules,
-    avalonNitroConfig.routeRules ?? {}
-  );
-
-  // Configure public assets directories
-  const publicAssets: NitroConfigOutput["publicAssets"] = [
-    {
-      dir: staticAssetsConfig.publicDir ?? DEFAULT_STATIC_ASSETS_CONFIG.publicDir,
-      baseURL: "/",
-      maxAge: 0, // Let route rules handle caching
-    },
-  ];
-
-  // Resolve renderer: support explicit false to disable, otherwise use default handler
-  const renderer: NitroConfigOutput["renderer"] =
-    avalonNitroConfig.renderer === false
-      ? false
-      : (avalonNitroConfig.renderer ?? { handler: "./server/renderer.ts" });
-
-  return {
-    preset: resolvePresetName(avalonNitroConfig.preset ?? DEFAULT_NITRO_CONFIG.preset),
-    serverDir: avalonNitroConfig.serverDir ?? DEFAULT_NITRO_CONFIG.serverDir,
-    routeRules,
-    runtimeConfig,
-    publicRuntimeConfig: avalonNitroConfig.publicRuntimeConfig,
-    renderer,
-    compatibilityDate: avalonNitroConfig.compatibilityDate,
-    traceDeps: avalonNitroConfig.traceDeps,
-    rolldownConfig: avalonNitroConfig.rolldownConfig,
-    serverEntry: avalonNitroConfig.serverEntry,
-    compressPublicAssets: avalonNitroConfig.compressPublicAssets,
-    publicAssets,
-    staticAssets: staticAssetsConfig,
-  };
-}
-
-/**
- * Creates default route rules for static asset caching
- *
- * @param config - Static assets configuration
- * @returns Route rules for static assets
- */
-export function createDefaultStaticAssetRouteRules(
-  config: StaticAssetsConfig
-): Record<string, RouteRule> {
-  const cacheControl = config.cacheControl ?? DEFAULT_STATIC_ASSETS_CONFIG.cacheControl;
-  const mutableCacheControl = config.mutableCacheControl ?? DEFAULT_STATIC_ASSETS_CONFIG.mutableCacheControl;
-
-  return {
-    // Immutable assets with hashed filenames (long cache)
-    "/assets/**": {
-      headers: {
-        "Cache-Control": cacheControl,
-        ...config.headers,
-      },
-    },
-    "/islands/**": {
-      headers: {
-        "Cache-Control": cacheControl,
-        ...config.headers,
-      },
-    },
-    "/chunks/**": {
-      headers: {
-        "Cache-Control": cacheControl,
-        ...config.headers,
-      },
-    },
-    "/_nuxt/**": {
-      headers: {
-        "Cache-Control": cacheControl,
-        ...config.headers,
-      },
-    },
-    // Font files (long cache)
-    "/**/*.woff": {
-      headers: {
-        "Cache-Control": cacheControl,
-        ...config.headers,
-      },
-    },
-    "/**/*.woff2": {
-      headers: {
-        "Cache-Control": cacheControl,
-        ...config.headers,
-      },
-    },
-    // Mutable assets (short cache with revalidation)
-    "/**/*.html": {
-      headers: {
-        "Cache-Control": mutableCacheControl,
-        ...config.headers,
-      },
-    },
-    // Favicon (medium cache)
-    "/favicon.ico": {
-      headers: {
-        "Cache-Control": "public, max-age=86400",
-        ...config.headers,
-      },
-    },
-    // CSS files in public directory (may be mutable)
-    "/**/*.css": {
-      headers: {
-        "Cache-Control": mutableCacheControl,
-        ...config.headers,
-      },
-    },
-  };
-}
-
-/**
- * Validates a Nitro preset name against the v3 preset list
- *
- * @param preset - The preset name to validate
- * @returns True if the preset is a known valid v3 preset
- */
-export function isValidPreset(preset: string): boolean {
-  return VALID_V3_PRESETS.includes(preset);
-}
-
-/**
- * Merges route rules, with later rules taking precedence
- *
- * @param baseRules - Base route rules
- * @param overrideRules - Override route rules
- * @returns Merged route rules
- */
-export function mergeRouteRules(
-  baseRules: Record<string, RouteRule>,
-  overrideRules: Record<string, RouteRule>
-): Record<string, RouteRule> {
-  const merged: Record<string, RouteRule> = { ...baseRules };
-
-  for (const [pattern, rule] of Object.entries(overrideRules)) {
-    if (merged[pattern]) {
-      // Deep merge the rule
-      merged[pattern] = {
-        ...merged[pattern],
-        ...rule,
-        headers: {
-          ...merged[pattern].headers,
-          ...rule.headers,
-        },
-      };
-    } else {
-      merged[pattern] = rule;
-    }
-  }
-
-  return merged;
-}
+/**
+ * Nitro Configuration Module for Avalon
+ *
+ * This module provides configuration interfaces and utilities for integrating
+ * Nitro as Avalon's server runtime. It handles preset configuration, route rules,
+ * and merging Avalon-specific options with Nitro defaults.
+ *
+ * ## Static Asset Handling
+ *
+ * Nitro automatically serves static assets from the `public/` directory at the root path.
+ * The configuration supports:
+ * - `publicAssets`: Configures directories for static file serving
+ * - `routeRules`: Configures cache headers for different asset types
+ * - `staticAssets`: Avalon-specific static asset configuration
+ *
+ * Default route rules for static assets are generated by `createDefaultStaticAssetRouteRules()`:
+ * - `/assets/**`, `/islands/**`, `/chunks/**`: Long cache (1 year, immutable)
+ * - `/*.woff`, `/*.woff2`: Long cache for fonts
+ * - `/*.html`, `/*.css`: Short cache with revalidation
+ * - `/favicon.ico`: Medium cache (1 day)
+ */
+
+import type { ResolvedAvalonConfig } from "../vite-plugin/types.ts";
+
+/**
+ * Cache configuration options for route rules
+ */
+export interface CacheOptions {
+  /** Maximum age in seconds for cache validity */
+  maxAge?: number;
+  /** Maximum age in seconds for stale content */
+  staleMaxAge?: number;
+  /** Enable stale-while-revalidate behavior */
+  swr?: boolean;
+}
+
+/**
+ * Route rule configuration for caching, redirects, proxying, and headers
+ */
+export interface RouteRule {
+  /** Cache configuration or boolean to enable/disable */
+  cache?: CacheOptions | boolean;
+  /** Redirect destination URL */
+  redirect?: string;
+  /** Proxy destination URL */
+  proxy?: string;
+  /** Custom headers to set */
+  headers?: Record<string, string>;
+  /** Enable CORS for this route */
+  cors?: boolean;
+}
+
+/**
+ * Static asset serving configuration
+ */
+export interface StaticAssetsConfig {
+  /**
+   * Directory containing public static assets
+   * @default "public"
+   */
+  publicDir?: string;
+
+  /**
+   * Directory containing compiled build output
+   * @default "dist"
+   */
+  buildDir?: string;
+
+  /**
+   * Enable serving pre-compressed assets (gzip, brotli)
+   * @default true
+   */
+  compression?: boolean;
+
+  /**
+   * Default cache control header for immutable static assets
+   * @default "public, max-age=31536000, immutable"
+   */
+  cacheControl?: string;
+
+  /**
+   * Cache control header for mutable assets (HTML, etc.)
+   * @default "public, max-age=0, must-revalidate"
+   */
+  mutableCacheControl?: string;
+
+  /**
+   * Custom headers to add to all static asset responses
+   */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Avalon-specific Nitro configuration options
+ */
+export interface AvalonNitroConfig {
+  /**
+   * Deployment preset (vercel, cloudflare, deno-deploy, node-server, netlify, etc.)
+   * @default "node-server"
+   */
+  preset?: string;
+
+  /**
+   * Directory containing server routes
+   * @default "server"
+   */
+  serverDir?: string;
+
+  /**
+   * Directory containing pages (overrides Avalon config if set)
+   */
+  pagesDir?: string;
+
+  /**
+   * Enable streaming SSR responses
+   * @default true
+   */
+  streaming?: boolean;
+
+  /**
+   * Route rules for caching, redirects, proxying, and headers
+   * Keys are route patterns (e.g., "/api/**", "/static/**")
+   */
+  routeRules?: Record<string, RouteRule>;
+
+  /**
+   * Runtime configuration accessible via useRuntimeConfig()
+   * Can be overridden by NITRO_ prefixed environment variables
+   */
+  runtimeConfig?: Record<string, unknown>;
+
+  /**
+   * Public runtime configuration (exposed to client)
+   */
+  publicRuntimeConfig?: Record<string, unknown>;
+
+  /**
+   * Static asset serving configuration
+   */
+  staticAssets?: StaticAssetsConfig;
+
+  /** Nitro v3: Compatibility date for preset features (YYYY-MM-DD) */
+  compatibilityDate?: string;
+  /** Nitro v3: Dependencies to trace instead of bundle */
+  traceDeps?: string[];
+  /** Nitro v3: Rolldown-specific configuration */
+  rolldownConfig?: Record<string, unknown>;
+  /** Nitro v3: Custom server entry point */
+  serverEntry?: string;
+  /** Nitro v3: Renderer configuration, or false to disable */
+  renderer?: { handler: string } | false;
+  /** Nitro v3: Pre-compress public assets (gzip, brotli, zstd) */
+  compressPublicAssets?: boolean | { gzip?: boolean; brotli?: boolean; zstd?: boolean };
+}
+
+/**
+ * Nitro configuration output structure
+ * This matches the expected NitroConfig interface from nitro/types
+ */
+export interface NitroConfigOutput {
+  /** Deployment preset */
+  preset: string;
+  /** Server directory */
+  serverDir: string;
+  /** Route rules */
+  routeRules: Record<string, RouteRule>;
+  /** Runtime configuration */
+  runtimeConfig: {
+    avalon: AvalonRuntimeConfig;
+    [key: string]: unknown;
+  };
+  /** Public runtime configuration */
+  publicRuntimeConfig?: Record<string, unknown>;
+  /** Renderer configuration, or false to disable */
+  renderer?: {
+    handler: string;
+  } | false;
+  /** Nitro v3: Compatibility date for preset features (YYYY-MM-DD) */
+  compatibilityDate?: string;
+  /** Nitro v3: Dependencies to trace instead of bundle */
+  traceDeps?: string[];
+  /** Nitro v3: Rolldown-specific configuration */
+  rolldownConfig?: Record<string, unknown>;
+  /** Nitro v3: Custom server entry point */
+  serverEntry?: string;
+  /** Nitro v3: Pre-compress public assets (gzip, brotli, zstd) */
+  compressPublicAssets?: boolean | { gzip?: boolean; brotli?: boolean; zstd?: boolean };
+  /** Public assets directory */
+  publicAssets?: Array<{
+    dir: string;
+    baseURL?: string;
+    maxAge?: number;
+  }>;
+  /** Server assets configuration */
+  serverAssets?: Array<{
+    baseName: string;
+    dir: string;
+  }>;
+  /** Static assets configuration */
+  staticAssets?: StaticAssetsConfig;
+}
+
+/**
+ * Avalon-specific runtime configuration stored in Nitro's runtimeConfig
+ */
+export interface AvalonRuntimeConfig {
+  /** Enable streaming SSR */
+  streaming: boolean;
+  /** Pages directory path */
+  pagesDir: string;
+  /** Layouts directory path */
+  layoutsDir: string;
+}
+
+/**
+ * Default static assets configuration
+ */
+export const DEFAULT_STATIC_ASSETS_CONFIG: Required<StaticAssetsConfig> = {
+  publicDir: "public",
+  buildDir: "dist",
+  compression: true,
+  cacheControl: "public, max-age=31536000, immutable",
+  mutableCacheControl: "public, max-age=0, must-revalidate",
+  headers: {},
+};
+
+/**
+ * All valid Nitro v3 preset names (underscore convention).
+ */
+export const VALID_V3_PRESETS: string[] = [
+  "node_server",
+  "node_middleware",
+  "vercel",
+  "cloudflare_module",
+  "cloudflare_pages",
+  "deno_deploy",
+  "deno_server",
+  "netlify_functions",
+  "netlify_edge",
+  "aws_lambda",
+  "azure_swa",
+  "firebase_functions",
+  "render_com",
+  "static",
+  "browser",
+];
+
+/**
+ * Validates a preset name against the v3 preset list.
+ * Returns the preset name if valid, throws if unrecognized.
+ *
+ * @param preset - The preset name to validate (must be a v3 name)
+ * @returns The validated v3 preset name
+ * @throws Error if the preset is not recognized
+ */
+export function resolvePresetName(preset: string): string {
+  if (VALID_V3_PRESETS.includes(preset)) return preset;
+  throw new Error(
+    `Unknown Nitro preset: "${preset}". Valid presets: ${VALID_V3_PRESETS.join(", ")}`
+  );
+}
+
+/**
+ * Default Nitro configuration values
+ */
+export const DEFAULT_NITRO_CONFIG: Required<
+  Pick<AvalonNitroConfig, "preset" | "serverDir" | "streaming">
+> = {
+  preset: "node_server",
+  serverDir: "server",
+  streaming: true,
+};
+
+/**
+ * Creates a Nitro configuration from Avalon plugin config and Nitro-specific options
+ *
+ * This function merges Avalon's resolved configuration with Nitro-specific options
+ * to produce a complete Nitro configuration object. Avalon-specific settings are
+ * stored in `runtimeConfig.avalon` for access by handlers.
+ *
+ * @param avalonNitroConfig - Nitro-specific configuration options
+ * @param resolvedAvalonConfig - Resolved Avalon plugin configuration
+ * @returns Complete Nitro configuration object
+ *
+ * @example
+ * ```ts
+ * const nitroConfig = createNitroConfig(
+ *   { preset: 'vercel', streaming: true },
+ *   resolvedAvalonConfig
+ * );
+ * ```
+ */
+export function createNitroConfig(
+  avalonNitroConfig: AvalonNitroConfig,
+  resolvedAvalonConfig: ResolvedAvalonConfig
+): NitroConfigOutput {
+  // Determine final directory paths (Nitro config overrides Avalon config)
+  const pagesDir = avalonNitroConfig.pagesDir ?? resolvedAvalonConfig.pagesDir;
+  const layoutsDir = resolvedAvalonConfig.layoutsDir;
+
+  // Build Avalon runtime config
+  const avalonRuntimeConfig: AvalonRuntimeConfig = {
+    streaming: avalonNitroConfig.streaming ?? DEFAULT_NITRO_CONFIG.streaming,
+    pagesDir,
+    layoutsDir,
+  };
+
+  // Validate that runtimeConfig does not contain a 'nitro' key (reserved in v3)
+  if (avalonNitroConfig.runtimeConfig && "nitro" in avalonNitroConfig.runtimeConfig) {
+    throw new Error(
+      'The "nitro" key in runtimeConfig is reserved by Nitro v3 and cannot be used.'
+    );
+  }
+
+  // Merge user runtime config with Avalon runtime config
+  const runtimeConfig: NitroConfigOutput["runtimeConfig"] = {
+    avalon: avalonRuntimeConfig,
+    ...avalonNitroConfig.runtimeConfig,
+  };
+
+  // Merge static assets config with defaults
+  const staticAssetsConfig: StaticAssetsConfig = {
+    ...DEFAULT_STATIC_ASSETS_CONFIG,
+    ...avalonNitroConfig.staticAssets,
+  };
+
+  // Create default route rules for static assets
+  const defaultStaticRouteRules = createDefaultStaticAssetRouteRules(staticAssetsConfig);
+
+  // Merge user route rules with default static asset rules
+  const routeRules = mergeRouteRules(
+    defaultStaticRouteRules,
+    avalonNitroConfig.routeRules ?? {}
+  );
+
+  // Configure public assets directories
+  const publicAssets: NitroConfigOutput["publicAssets"] = [
+    {
+      dir: staticAssetsConfig.publicDir ?? DEFAULT_STATIC_ASSETS_CONFIG.publicDir,
+      baseURL: "/",
+      maxAge: 0, // Let route rules handle caching
+    },
+  ];
+
+  // Resolve renderer: support explicit false to disable, otherwise use default handler
+  const renderer: NitroConfigOutput["renderer"] =
+    avalonNitroConfig.renderer === false
+      ? false
+      : (avalonNitroConfig.renderer ?? { handler: "./server/renderer.ts" });
+
+  return {
+    preset: resolvePresetName(avalonNitroConfig.preset ?? DEFAULT_NITRO_CONFIG.preset),
+    serverDir: avalonNitroConfig.serverDir ?? DEFAULT_NITRO_CONFIG.serverDir,
+    routeRules,
+    runtimeConfig,
+    publicRuntimeConfig: avalonNitroConfig.publicRuntimeConfig,
+    renderer,
+    compatibilityDate: avalonNitroConfig.compatibilityDate,
+    traceDeps: avalonNitroConfig.traceDeps,
+    rolldownConfig: avalonNitroConfig.rolldownConfig,
+    serverEntry: avalonNitroConfig.serverEntry,
+    compressPublicAssets: avalonNitroConfig.compressPublicAssets,
+    publicAssets,
+    staticAssets: staticAssetsConfig,
+  };
+}
+
+/**
+ * Creates default route rules for static asset caching
+ *
+ * @param config - Static assets configuration
+ * @returns Route rules for static assets
+ */
+export function createDefaultStaticAssetRouteRules(
+  config: StaticAssetsConfig
+): Record<string, RouteRule> {
+  const cacheControl = config.cacheControl ?? DEFAULT_STATIC_ASSETS_CONFIG.cacheControl;
+  const mutableCacheControl = config.mutableCacheControl ?? DEFAULT_STATIC_ASSETS_CONFIG.mutableCacheControl;
+
+  return {
+    // Immutable assets with hashed filenames (long cache)
+    "/assets/**": {
+      headers: {
+        "Cache-Control": cacheControl,
+        ...config.headers,
+      },
+    },
+    "/islands/**": {
+      headers: {
+        "Cache-Control": cacheControl,
+        ...config.headers,
+      },
+    },
+    "/chunks/**": {
+      headers: {
+        "Cache-Control": cacheControl,
+        ...config.headers,
+      },
+    },
+    "/_nuxt/**": {
+      headers: {
+        "Cache-Control": cacheControl,
+        ...config.headers,
+      },
+    },
+    // Font files (long cache)
+    "/**/*.woff": {
+      headers: {
+        "Cache-Control": cacheControl,
+        ...config.headers,
+      },
+    },
+    "/**/*.woff2": {
+      headers: {
+        "Cache-Control": cacheControl,
+        ...config.headers,
+      },
+    },
+    // Mutable assets (short cache with revalidation)
+    "/**/*.html": {
+      headers: {
+        "Cache-Control": mutableCacheControl,
+        ...config.headers,
+      },
+    },
+    // Favicon (medium cache)
+    "/favicon.ico": {
+      headers: {
+        "Cache-Control": "public, max-age=86400",
+        ...config.headers,
+      },
+    },
+    // CSS files in public directory (may be mutable)
+    "/**/*.css": {
+      headers: {
+        "Cache-Control": mutableCacheControl,
+        ...config.headers,
+      },
+    },
+  };
+}
+
+/**
+ * Validates a Nitro preset name against the v3 preset list
+ *
+ * @param preset - The preset name to validate
+ * @returns True if the preset is a known valid v3 preset
+ */
+export function isValidPreset(preset: string): boolean {
+  return VALID_V3_PRESETS.includes(preset);
+}
+
+/**
+ * Merges route rules, with later rules taking precedence
+ *
+ * @param baseRules - Base route rules
+ * @param overrideRules - Override route rules
+ * @returns Merged route rules
+ */
+export function mergeRouteRules(
+  baseRules: Record<string, RouteRule>,
+  overrideRules: Record<string, RouteRule>
+): Record<string, RouteRule> {
+  const merged: Record<string, RouteRule> = { ...baseRules };
+
+  for (const [pattern, rule] of Object.entries(overrideRules)) {
+    if (merged[pattern]) {
+      // Deep merge the rule
+      merged[pattern] = {
+        ...merged[pattern],
+        ...rule,
+        headers: {
+          ...merged[pattern].headers,
+          ...rule.headers,
+        },
+      };
+    } else {
+      merged[pattern] = rule;
+    }
+  }
+
+  return merged;
+}