@useavalon/avalon 0.1.0

package/src/nitro/island-manifest.ts

@@ -0,0 +1,584 @@
+/**
+ * Island Manifest Generation Module for Nitro
+ *
+ * This module provides island manifest generation during production builds.
+ * The manifest contains information about all discovered islands, their
+ * compiled asset paths, and framework metadata for client-side hydration.
+ *
+ * ## Build Output
+ *
+ * During production build, this module generates:
+ * - `island-manifest.json` in the build output directory
+ * - Contains metadata for all islands (src, framework, css, preload)
+ * - Includes build timestamp and content hashes for cache busting
+ * - Generates preload hints for critical assets
+ *
+ * ## Nitro Integration
+ *
+ * The manifest is used by Nitro's renderer to:
+ * - Resolve compiled island paths for hydration scripts
+ * - Inject CSS assets for islands used on a page
+ * - Generate preload tags for critical resources
+ *
+ * ## Asset Metadata
+ *
+ * Each island entry includes:
+ * - `src`: Compiled JavaScript path (e.g., `/islands/Counter.abc123.js`)
+ * - `framework`: Detected framework (react, preact, vue, svelte, solid, lit)
+ * - `css`: Associated CSS files
+ * - `contentHash`: Hash for cache busting
+ * - `preloadDeps`: Dependencies to preload
+ *
+ * @module nitro/island-manifest
+ */
+
+import { readFile } from "node:fs/promises";
+import type { Plugin } from "vite";
+import type { ResolvedAvalonConfig } from "../vite-plugin/types.ts";
+import type { IslandManifest, IslandEntry } from "./types.ts";
+
+/**
+ * Extended island entry with build-time metadata
+ */
+export interface BuildIslandEntry extends IslandEntry {
+  /** Original source file path */
+  sourcePath: string;
+  /** Compiled JavaScript chunk name */
+  chunkName: string;
+  /** Content hash for cache busting */
+  contentHash: string;
+  /** Dependencies that need to be preloaded */
+  preloadDeps: string[];
+  /** Whether the island uses streaming */
+  usesStreaming: boolean;
+}
+
+/**
+ * Asset metadata for Nitro's asset manifest format
+ * This matches Nitro's expected asset metadata structure
+ */
+export interface AssetMetadata {
+  /** MIME type of the asset */
+  type: string;
+  /** ETag for cache validation */
+  etag: string;
+  /** Last modification time (ISO string) */
+  mtime: string;
+  /** File size in bytes */
+  size: number;
+}
+
+/**
+ * Build-time island manifest with additional metadata
+ */
+export interface BuildIslandManifest extends IslandManifest {
+  /** Build timestamp */
+  buildTime: number;
+  /** Build version/hash */
+  buildHash: string;
+  /** Avalon version */
+  avalonVersion: string;
+  /** All CSS assets to inject */
+  cssAssets: string[];
+  /** Preload hints for critical assets */
+  preloadHints: PreloadHint[];
+  /** Framework-specific bundles */
+  frameworkBundles: Record<string, string>;
+  /** Asset metadata for cache headers (Nitro format) */
+  assetMetadata?: Record<string, AssetMetadata>;
+}
+
+/**
+ * Preload hint for resource optimization
+ */
+export interface PreloadHint {
+  /** Resource URL */
+  href: string;
+  /** Resource type (script, style, font, etc.) */
+  as: "script" | "style" | "font" | "image";
+  /** MIME type */
+  type?: string;
+  /** Cross-origin setting */
+  crossorigin?: "anonymous" | "use-credentials";
+}
+
+/**
+ * Options for island manifest generation
+ */
+export interface IslandManifestOptions {
+  /** Output path for the manifest file */
+  outputPath?: string;
+  /** Include source maps in manifest */
+  includeSourceMaps?: boolean;
+  /** Generate preload hints */
+  generatePreloadHints?: boolean;
+  /** Verbose logging */
+  verbose?: boolean;
+}
+
+/**
+ * Default manifest generation options
+ */
+export const DEFAULT_MANIFEST_OPTIONS: Required<IslandManifestOptions> = {
+  outputPath: "dist/island-manifest.json",
+  includeSourceMaps: false,
+  generatePreloadHints: true,
+  verbose: false,
+};
+
+/**
+ * Framework detection patterns for island files
+ */
+const FRAMEWORK_PATTERNS: Record<string, RegExp[]> = {
+  react: [
+    /from\s+['"]react['"]/,
+    /from\s+['"]react-dom['"]/,
+    /@jsxImportSource\s+react/,
+  ],
+  preact: [
+    /from\s+['"]preact['"]/,
+    /from\s+['"]preact\/hooks['"]/,
+    /@jsxImportSource\s+preact/,
+  ],
+  vue: [
+    /from\s+['"]vue['"]/,
+    /\.vue$/,
+  ],
+  svelte: [
+    /from\s+['"]svelte['"]/,
+    /\.svelte$/,
+  ],
+  solid: [
+    /from\s+['"]solid-js['"]/,
+    /\.solid\.(tsx|jsx)$/,
+  ],
+  lit: [
+    /from\s+['"]lit['"]/,
+    /from\s+['"]@lit['"]/,
+    /\.lit\.(ts|js)$/,
+  ],
+};
+
+/**
+ * Detects the framework used by an island based on file content and extension
+ *
+ * @param filePath - Path to the island file
+ * @param content - File content
+ * @returns Detected framework name
+ */
+export function detectIslandFramework(
+  filePath: string,
+  content: string
+): string {
+  // Check file extension first
+  if (filePath.endsWith(".vue")) return "vue";
+  if (filePath.endsWith(".svelte")) return "svelte";
+  if (filePath.includes(".solid.")) return "solid";
+  if (filePath.includes(".lit.")) return "lit";
+
+  // Check content patterns
+  for (const [framework, patterns] of Object.entries(FRAMEWORK_PATTERNS)) {
+    for (const pattern of patterns) {
+      if (pattern.test(content) || pattern.test(filePath)) {
+        return framework;
+      }
+    }
+  }
+
+  // Default to preact for JSX/TSX files
+  if (filePath.endsWith(".tsx") || filePath.endsWith(".jsx")) {
+    return "preact";
+  }
+
+  return "unknown";
+}
+
+/**
+ * Generates a content hash for cache busting
+ *
+ * @param content - Content to hash
+ * @returns Short hash string
+ */
+export async function generateContentHash(content: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(content);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  return hashHex.slice(0, 8);
+}
+
+/**
+ * Extracts dependencies from island file content
+ *
+ * @param content - File content
+ * @returns Array of dependency names
+ */
+export function extractIslandDependencies(content: string): string[] {
+  const deps: string[] = [];
+  const importRegex = /import\s+.*?\s+from\s+['"]([^'"]+)['"]/g;
+  const dynamicImportRegex = /import\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+  let match;
+
+  // Static imports
+  while ((match = importRegex.exec(content)) !== null) {
+    const importPath = match[1];
+    if (!importPath.startsWith(".") && !importPath.startsWith("/")) {
+      deps.push(importPath);
+    }
+  }
+
+  // Dynamic imports
+  while ((match = dynamicImportRegex.exec(content)) !== null) {
+    const importPath = match[1];
+    if (!importPath.startsWith(".") && !importPath.startsWith("/")) {
+      deps.push(importPath);
+    }
+  }
+
+  return [...new Set(deps)];
+}
+
+/**
+ * Creates an island entry from discovered island information
+ *
+ * @param name - Island name
+ * @param sourcePath - Source file path
+ * @param content - File content
+ * @param compiledPath - Compiled asset path
+ * @returns Island entry
+ */
+export async function createIslandEntry(
+  name: string,
+  sourcePath: string,
+  content: string,
+  compiledPath: string
+): Promise<BuildIslandEntry> {
+  const framework = detectIslandFramework(sourcePath, content);
+  const contentHash = await generateContentHash(content);
+  const deps = extractIslandDependencies(content);
+
+  return {
+    src: compiledPath,
+    framework,
+    css: [], // Will be populated during build
+    preload: deps.filter((d) => !d.includes("/")), // Only top-level packages
+    sourcePath,
+    chunkName: name,
+    contentHash,
+    preloadDeps: [],
+    usesStreaming: false,
+  };
+}
+
+/**
+ * Generates preload hints for critical assets
+ *
+ * @param manifest - Island manifest
+ * @returns Array of preload hints
+ */
+export function generatePreloadHints(
+  manifest: Partial<BuildIslandManifest>
+): PreloadHint[] {
+  const hints: PreloadHint[] = [];
+
+  // Add client entry script
+  if (manifest.clientEntry) {
+    hints.push({
+      href: manifest.clientEntry,
+      as: "script",
+      type: "text/javascript",
+    });
+  }
+
+  // Add CSS assets
+  for (const css of manifest.css ?? []) {
+    hints.push({
+      href: css,
+      as: "style",
+      type: "text/css",
+    });
+  }
+
+  // Add framework bundles
+  for (const bundle of Object.values(manifest.frameworkBundles ?? {})) {
+    hints.push({
+      href: bundle,
+      as: "script",
+      type: "text/javascript",
+    });
+  }
+
+  return hints;
+}
+
+/**
+ * Creates a Vite plugin for island manifest generation
+ *
+ * @param avalonConfig - Resolved Avalon configuration
+ * @param options - Manifest generation options
+ * @returns Vite plugin
+ */
+export function createIslandManifestPlugin(
+  avalonConfig: ResolvedAvalonConfig,
+  options: IslandManifestOptions = {}
+): Plugin {
+  const opts = { ...DEFAULT_MANIFEST_OPTIONS, ...options };
+  const islands: Map<string, BuildIslandEntry> = new Map();
+  const cssAssets: Set<string> = new Set();
+  let clientEntry = "";
+
+  return {
+    name: "avalon:island-manifest",
+    enforce: "post",
+
+    // Track island chunks during build
+    generateBundle(_outputOptions, bundle) {
+      for (const [fileName, chunk] of Object.entries(bundle)) {
+        // Track CSS assets
+        if (fileName.endsWith(".css")) {
+          cssAssets.add(`/${fileName}`);
+        }
+
+        // Track client entry
+        if (
+          chunk.type === "chunk" &&
+          (chunk.name === "client" || chunk.name === "main")
+        ) {
+          clientEntry = `/${fileName}`;
+        }
+
+        // Track island chunks
+        if (
+          chunk.type === "chunk" &&
+          (chunk.facadeModuleId?.includes("/islands/") ||
+            chunk.name?.startsWith("islands/"))
+        ) {
+          const name = chunk.name?.replace("islands/", "") ?? fileName;
+          const existingEntry = islands.get(name);
+
+          if (existingEntry) {
+            // Update with compiled path
+            existingEntry.src = `/${fileName}`;
+          } else {
+            // Create new entry
+            islands.set(name, {
+              src: `/${fileName}`,
+              framework: detectFrameworkFromChunk(chunk),
+              css: [],
+              preload: [],
+              sourcePath: chunk.facadeModuleId ?? "",
+              chunkName: name,
+              contentHash: /\.([a-f0-9]+)\.js$/.exec(fileName)?.[1] ?? "",
+              preloadDeps: chunk.imports ?? [],
+              usesStreaming: false,
+            });
+          }
+        }
+      }
+    },
+
+    // Write manifest after build
+    async writeBundle(_options: unknown, bundle: Record<string, { type: string; source?: string | Uint8Array; code?: string }>) {
+      // Generate asset metadata for Nitro's format (type, etag, mtime, size)
+      const assetMetadata: Record<string, AssetMetadata> = {};
+      const buildTime = new Date().toISOString();
+      
+      for (const [fileName, chunk] of Object.entries(bundle)) {
+        const entry = await buildAssetMetadataEntry(fileName, chunk, buildTime);
+        if (entry) assetMetadata[`/${fileName}`] = entry;
+      }
+
+      const manifest: BuildIslandManifest = {
+        islands: Object.fromEntries(islands),
+        clientEntry,
+        css: Array.from(cssAssets),
+        buildTime: Date.now(),
+        buildHash: await generateContentHash(JSON.stringify(Object.fromEntries(islands))),
+        avalonVersion: "1.0.0",
+        cssAssets: Array.from(cssAssets),
+        preloadHints: opts.generatePreloadHints
+          ? generatePreloadHints({
+              clientEntry,
+              css: Array.from(cssAssets),
+              islands: Object.fromEntries(islands),
+            })
+          : [],
+        frameworkBundles: {},
+        assetMetadata,
+      };
+
+      // Write manifest file
+      const manifestJson = JSON.stringify(manifest, null, 2);
+      
+      if (opts.verbose) {
+        console.log("📋 Island manifest generated:");
+        console.log(`   Islands: ${islands.size}`);
+        console.log(`   CSS assets: ${cssAssets.size}`);
+        console.log(`   Client entry: ${clientEntry}`);
+        console.log(`   Asset metadata entries: ${Object.keys(assetMetadata).length}`);
+      }
+
+      // Emit the manifest as an asset
+      this.emitFile({
+        type: "asset",
+        fileName: "island-manifest.json",
+        source: manifestJson,
+      });
+    },
+  };
+}
+
+/**
+ * Generates asset metadata entry for a single bundle chunk
+ */
+async function buildAssetMetadataEntry(
+  fileName: string,
+  chunk: { type: string; source?: string | Uint8Array; code?: string },
+  buildTime: string
+): Promise<AssetMetadata | null> {
+  let content: string | Uint8Array | undefined;
+  if (chunk.type === "asset" && chunk.source) {
+    content = chunk.source;
+  } else if (chunk.type === "chunk" && chunk.code) {
+    content = chunk.code;
+  }
+  if (!content) return null;
+
+  const size = typeof content === "string"
+    ? new TextEncoder().encode(content).length
+    : content.length;
+  const contentStr = typeof content === "string"
+    ? content
+    : new TextDecoder().decode(content);
+  const etag = await generateContentHash(contentStr);
+
+  const ext = fileName.substring(fileName.lastIndexOf("."));
+  const mimeTypes: Record<string, string> = {
+    ".js": "application/javascript",
+    ".mjs": "application/javascript",
+    ".css": "text/css",
+    ".json": "application/json",
+    ".html": "text/html",
+    ".map": "application/json",
+  };
+
+  return {
+    type: mimeTypes[ext] ?? "application/octet-stream",
+    etag: `"${etag}"`,
+    mtime: buildTime,
+    size,
+  };
+}
+
+/**
+ * @param chunk - Rollup output chunk
+ * @returns Detected framework name
+ */
+function detectFrameworkFromChunk(chunk: {
+  facadeModuleId?: string | null;
+  code?: string;
+}): string {
+  const filePath = chunk.facadeModuleId ?? "";
+  const content = chunk.code ?? "";
+
+  return detectIslandFramework(filePath, content);
+}
+
+/**
+ * Loads an existing island manifest from disk
+ *
+ * @param manifestPath - Path to the manifest file
+ * @returns Loaded manifest or null if not found
+ */
+export async function loadIslandManifest(
+  manifestPath: string = "dist/island-manifest.json"
+): Promise<BuildIslandManifest | null> {
+  try {
+    const content = await readFile(manifestPath, "utf-8");
+    return JSON.parse(content) as BuildIslandManifest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Gets the compiled asset path for an island
+ *
+ * @param islandName - Name of the island
+ * @param manifest - Island manifest
+ * @returns Compiled asset path or null if not found
+ */
+export function getIslandAssetPath(
+  islandName: string,
+  manifest: BuildIslandManifest | null
+): string | null {
+  if (!manifest) return null;
+
+  const entry = manifest.islands[islandName];
+  return entry?.src ?? null;
+}
+
+/**
+ * Gets all CSS assets that should be injected for a page
+ *
+ * @param islandNames - Names of islands used on the page
+ * @param manifest - Island manifest
+ * @returns Array of CSS asset paths
+ */
+export function getPageCssAssets(
+  islandNames: string[],
+  manifest: BuildIslandManifest | null
+): string[] {
+  if (!manifest) return [];
+
+  const cssAssets = new Set<string>();
+
+  // Add global CSS
+  for (const css of manifest.css) {
+    cssAssets.add(css);
+  }
+
+  // Add island-specific CSS
+  for (const name of islandNames) {
+    const entry = manifest.islands[name];
+    if (entry?.css) {
+      for (const css of entry.css) {
+        cssAssets.add(css);
+      }
+    }
+  }
+
+  return Array.from(cssAssets);
+}
+
+/**
+ * Generates HTML preload tags for critical assets
+ *
+ * @param manifest - Island manifest
+ * @returns HTML string with preload tags
+ */
+export function generatePreloadTags(manifest: BuildIslandManifest): string {
+  const tags: string[] = [];
+
+  for (const hint of manifest.preloadHints) {
+    const attrs = [
+      `rel="preload"`,
+      `href="${hint.href}"`,
+      `as="${hint.as}"`,
+    ];
+
+    if (hint.type) {
+      attrs.push(`type="${hint.type}"`);
+    }
+
+    if (hint.crossorigin) {
+      attrs.push(`crossorigin="${hint.crossorigin}"`);
+    }
+
+    tags.push(`<link ${attrs.join(" ")}>`);
+  }
+
+  return tags.join("\n");
+}