@punkestu/react-html 0.0.0-stage → 0.1.0

package/src/core/bundler.ts

@@ -0,0 +1,122 @@
+import * as esbuild from 'esbuild';
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { IslandInstance } from './island-registry.js';
+
+export interface BundlerOptions {
+  outDir: string;
+  minify?: boolean;
+}
+
+export async function bundleIslands(
+  islands: IslandInstance[],
+  options: BundlerOptions
+): Promise<string[]> {
+  const { outDir, minify = true } = options;
+  const islandsOutputDir = path.join(outDir, 'assets', 'islands');
+  await fs.mkdir(islandsOutputDir, { recursive: true });
+
+  const tempDir = path.resolve(process.cwd(), '.react-html/temp-islands');
+  await fs.mkdir(tempDir, { recursive: true });
+
+  const uniqueIslandsMap = new Map<string, IslandInstance>();
+  for (const island of islands) {
+    if (!uniqueIslandsMap.has(island.name)) {
+      uniqueIslandsMap.set(island.name, island);
+    }
+  }
+
+  const bundledFiles: string[] = [];
+
+  // Locate hydrate module
+  const currentDir = import.meta.dirname || path.dirname(fileURLToPath(import.meta.url));
+  let hydratePath = path.resolve(currentDir, '../client/hydrate.js');
+  if (!existsSync(hydratePath)) {
+    hydratePath = path.resolve(currentDir, '../client/hydrate.ts');
+  }
+
+  let islandClientPath = path.resolve(currentDir, './island-client.js');
+  if (!existsSync(islandClientPath)) {
+    islandClientPath = path.resolve(currentDir, './island-client.ts');
+  }
+
+  for (const [name, island] of uniqueIslandsMap.entries()) {
+    let resolvedEntry = island.entryPath;
+    if (resolvedEntry.startsWith('file://')) {
+      resolvedEntry = fileURLToPath(resolvedEntry);
+    } else {
+      resolvedEntry = path.resolve(resolvedEntry);
+    }
+
+    try {
+      await fs.access(resolvedEntry);
+    } catch {
+      console.warn(`[react-html] Warning: Island source file not found for "${name}" at "${resolvedEntry}". Skipping client bundle.`);
+      continue;
+    }
+
+    // Create a virtual client entrypoint for this island
+    const virtualEntryFile = path.join(tempDir, `${name}.entry.ts`);
+    const virtualEntryCode = `
+import React from 'react';
+import { hydrateIsland } from ${JSON.stringify(hydratePath)};
+import * as Module from ${JSON.stringify(resolvedEntry)};
+
+const raw = Module.default || Module[${JSON.stringify(name)}] || Module;
+const Component = (raw && raw.__rawComponent) ? raw.__rawComponent : raw;
+
+hydrateIsland(${JSON.stringify(name)}, Component);
+`;
+    await fs.writeFile(virtualEntryFile, virtualEntryCode, 'utf8');
+
+    const outfile = path.join(islandsOutputDir, `${name}.js`);
+
+    await esbuild.build({
+      entryPoints: [virtualEntryFile],
+      outfile,
+      bundle: true,
+      format: 'esm',
+      platform: 'browser',
+      target: ['es2022'],
+      minify,
+      treeShaking: true,
+      define: {
+        'process.env.NODE_ENV': '"production"'
+      },
+      alias: {
+        'react-html': islandClientPath
+      },
+      plugins: [
+        {
+          name: 'redirect-react-html-imports',
+          setup(build) {
+            // Redirect any import of react-html or root index to island-client
+            build.onResolve({ filter: /(react-html|(\/|\\)(src|dist)(\/|\\)index(\.js|\.mjs|\.ts)?)$/ }, () => {
+              return { path: islandClientPath };
+            });
+          }
+        }
+      ],
+      loader: {
+        '.tsx': 'tsx',
+        '.ts': 'ts',
+        '.jsx': 'jsx',
+        '.js': 'js',
+        '.css': 'empty'
+      }
+    });
+
+    bundledFiles.push(outfile);
+  }
+
+  // Cleanup virtual entry files
+  try {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  } catch {
+    // Ignore cleanup error
+  }
+
+  return bundledFiles;
+}

package/src/core/formatter.ts

@@ -0,0 +1,92 @@
+/**
+ * Robust HTML formatter to output clean, readable HTML
+ * Preserves exact inner markup inside reactive islands to ensure seamless React hydration.
+ */
+export function formatHtml(html: string): string {
+  // Extract and preserve island contents verbatim
+  const preservedIslands: string[] = [];
+  let clean = html.replace(
+    /<!--__ISLAND_START__-->([\s\S]*?)<!--__ISLAND_END__-->/g,
+    (_, inner) => {
+      const idx = preservedIslands.length;
+      preservedIslands.push(inner);
+      return `%%REACT_HTML_ISLAND_${idx}%%`;
+    }
+  );
+
+  // Strip React comment artifacts outside islands if any
+  clean = clean.replace(/<!-- -->/g, '');
+
+  const tokens = clean.split(/(<[^>]+>)/g).filter((t) => t.trim().length > 0);
+  let formatted = '';
+  let indent = 0;
+  const indentStr = '  ';
+
+  // Void tags that don't need closing or indentation changes
+  const voidTags = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'link', 'meta', 'param', 'source', 'track', 'wbr', '!doctype'
+  ]);
+
+  // Tags where content is typically kept on the same line if brief
+  const inlineTags = new Set([
+    'title', 'span', 'strong', 'em', 'b', 'i', 'code', 'small', 'sub', 'sup'
+  ]);
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i].trim();
+
+    if (token.startsWith('<!DOCTYPE') || token.startsWith('<!doctype')) {
+      formatted += token + '\n';
+      continue;
+    }
+
+    if (token.startsWith('</')) {
+      // Closing tag
+      const match = token.match(/<\/([a-zA-Z0-9\-]+)/);
+      const tagName = match ? match[1].toLowerCase() : '';
+
+      indent = Math.max(0, indent - 1);
+      formatted += indentStr.repeat(indent) + token + '\n';
+    } else if (token.startsWith('<') && !token.startsWith('<!--')) {
+      // Opening or self-closing tag
+      const match = token.match(/<([a-zA-Z0-9\-]+)/);
+      const tagName = match ? match[1].toLowerCase() : '';
+      const isSelfClosing = token.endsWith('/>') || voidTags.has(tagName);
+
+      // Check if next token is text and next-next token is closing tag
+      if (
+        inlineTags.has(tagName) &&
+        i + 2 < tokens.length &&
+        !tokens[i + 1].trim().startsWith('<') &&
+        tokens[i + 2].trim().toLowerCase() === `</${tagName}>`
+      ) {
+        const text = tokens[i + 1].trim();
+        const closeTag = tokens[i + 2].trim();
+        formatted += indentStr.repeat(indent) + `${token}${text}${closeTag}\n`;
+        i += 2;
+        continue;
+      }
+
+      formatted += indentStr.repeat(indent) + token + '\n';
+
+      if (!isSelfClosing) {
+        indent++;
+      }
+    } else {
+      // Standalone text content
+      formatted += indentStr.repeat(indent) + token + '\n';
+    }
+  }
+
+  // Restore preserved island markup untouched
+  let finalHtml = formatted.replace(
+    /%%REACT_HTML_ISLAND_(\d+)%%/g,
+    (_, idxStr) => {
+      const idx = parseInt(idxStr, 10);
+      return preservedIslands[idx] ?? '';
+    }
+  );
+
+  return finalHtml.trim() + '\n';
+}

package/src/core/island-client.ts

@@ -0,0 +1,23 @@
+import React, { ComponentType, ReactNode } from 'react';
+
+export function Island<P extends Record<string, unknown>>({
+  component: Component,
+  props = {} as P,
+  children
+}: {
+  component: ComponentType<P>;
+  props?: P;
+  children?: ReactNode;
+  [key: string]: unknown;
+}): React.ReactElement {
+  return React.createElement(Component, props, children);
+}
+
+export function island<P extends Record<string, unknown>>(
+  Component: ComponentType<P>,
+  _sourcePath?: string,
+  _customName?: string
+): ComponentType<P> {
+  return Component;
+}
+

package/src/core/island-registry.ts

@@ -0,0 +1,35 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export interface IslandInstance {
+  id: string;
+  name: string;
+  entryPath: string;
+  props: Record<string, unknown>;
+  clientDirective?: 'load' | 'idle' | 'visible';
+}
+
+export interface RenderContext {
+  pagePath: string;
+  islands: IslandInstance[];
+}
+
+const GLOBAL_STORAGE_KEY = Symbol.for('__react_html_render_context__');
+
+const storage: AsyncLocalStorage<RenderContext> =
+  (globalThis as any)[GLOBAL_STORAGE_KEY] ||
+  ((globalThis as any)[GLOBAL_STORAGE_KEY] = new AsyncLocalStorage<RenderContext>());
+
+export function runWithRenderContext<T>(context: RenderContext, fn: () => T): T {
+  return storage.run(context, fn);
+}
+
+export function getCurrentRenderContext(): RenderContext | undefined {
+  return storage.getStore();
+}
+
+export function registerIslandInContext(island: IslandInstance): void {
+  const ctx = storage.getStore();
+  if (ctx) {
+    ctx.islands.push(island);
+  }
+}

package/src/core/island.tsx

@@ -0,0 +1,110 @@
+import React, { ComponentType, ReactNode } from 'react';
+import { renderToString } from 'react-dom/server';
+import { registerIslandInContext } from './island-registry.js';
+
+let islandCounter = 0;
+
+export interface IslandProps<P = Record<string, unknown>> {
+  /** Explicit island name (optional) */
+  name?: string;
+  /** Path to the island component file (relative or absolute) */
+  src?: string;
+  /** The React component to render */
+  component: ComponentType<P>;
+  /** Props passed to the component */
+  props?: P;
+  /** Client hydration directive (default: 'load') */
+  client?: 'load' | 'idle' | 'visible';
+  /** Optional wrapper tag, default: 'div' */
+  as?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  children?: ReactNode;
+}
+
+export function Island<P extends Record<string, unknown>>({
+  name,
+  src,
+  component: Component,
+  props = {} as P,
+  client = 'load',
+  as: Tag = 'div',
+  className,
+  style,
+  children
+}: IslandProps<P>): React.ReactElement {
+  const componentName =
+    name ||
+    (Component as any).__islandName ||
+    Component.displayName ||
+    Component.name ||
+    'AnonymousIsland';
+
+  const islandId = `island-${++islandCounter}`;
+
+  // If src is specified or attached to component
+  const entryPath = src || (Component as any).__islandPath || '';
+
+  registerIslandInContext({
+    id: islandId,
+    name: componentName,
+    entryPath,
+    props,
+    clientDirective: client
+  });
+
+  const Wrapper = Tag as any;
+
+  // Use renderToString for the island's inner tree to produce hydration-compatible SSR markup
+  const innerHtml = renderToString(React.createElement(Component, props, children));
+
+  return (
+    <Wrapper
+      data-island={componentName}
+      data-island-id={islandId}
+      data-props={JSON.stringify(props)}
+      data-client={client}
+      className={className}
+      style={style}
+      dangerouslySetInnerHTML={{ __html: `<!--__ISLAND_START__-->${innerHtml}<!--__ISLAND_END__-->` }}
+    />
+  );
+}
+
+/**
+ * Helper to wrap any React component into a ready-to-use Island component
+ * Example:
+ *   export const Counter = island(CounterComponent, import.meta.url, 'Counter');
+ *   // In page: <Counter initialCount={5} />
+ */
+export function island<P extends Record<string, unknown>>(
+  Component: ComponentType<P>,
+  sourcePath: string,
+  customName?: string
+): ComponentType<P & { client?: 'load' | 'idle' | 'visible'; as?: string; className?: string; style?: React.CSSProperties }> {
+  const resolvedName = customName || Component.displayName || Component.name || 'AnonymousIsland';
+  (Component as any).__islandPath = sourcePath;
+  (Component as any).__islandName = resolvedName;
+
+  const IslandWrapper = (props: P & { client?: 'load' | 'idle' | 'visible'; as?: string; className?: string; style?: React.CSSProperties }) => {
+    const { client, as, className, style, ...componentProps } = props;
+    return (
+      <Island
+        name={resolvedName}
+        src={sourcePath}
+        component={Component}
+        props={componentProps as P}
+        client={client}
+        as={as}
+        className={className}
+        style={style}
+      />
+    );
+  };
+
+  IslandWrapper.displayName = `Island(${resolvedName})`;
+  (IslandWrapper as any).__islandPath = sourcePath;
+  (IslandWrapper as any).__islandName = resolvedName;
+  (IslandWrapper as any).__rawComponent = Component;
+  return IslandWrapper;
+}

package/src/core/loader.ts

@@ -0,0 +1,89 @@
+import * as esbuild from 'esbuild';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+
+export interface LoadedPage {
+  Component: React.ComponentType<any>;
+  metadata?: {
+    title?: string;
+    description?: string;
+    [key: string]: unknown;
+  };
+}
+
+const CACHE_DIR = path.resolve(process.cwd(), '.react-html/cache');
+
+// Plugin to replace import.meta.url with the real source file URL
+const importMetaUrlPlugin: esbuild.Plugin = {
+  name: 'preserve-import-meta-url',
+  setup(build) {
+    build.onLoad({ filter: /\.(tsx|ts|jsx|js)$/ }, async (args) => {
+      if (args.path.includes('node_modules')) return null;
+      let text = await fs.readFile(args.path, 'utf8');
+      if (text.includes('import.meta.url')) {
+        const fileUrl = pathToFileURL(args.path).href;
+        text = text.replaceAll('import.meta.url', JSON.stringify(fileUrl));
+        const ext = path.extname(args.path).slice(1);
+        return {
+          contents: text,
+          loader: (ext === 'js' || ext === 'jsx' || ext === 'ts' || ext === 'tsx') ? (ext as any) : 'tsx'
+        };
+      }
+      return null;
+    });
+  }
+};
+
+export async function loadPageModule(pageFilePath: string): Promise<LoadedPage> {
+  await fs.mkdir(CACHE_DIR, { recursive: true });
+
+  const resolvedPath = path.resolve(pageFilePath);
+  const hash = crypto.createHash('sha256').update(resolvedPath).digest('hex').slice(0, 12);
+  const cacheFilePath = path.join(CACHE_DIR, `page-${hash}.mjs`);
+
+  // Build the page bundle for Node.js execution
+  await esbuild.build({
+    entryPoints: [resolvedPath],
+    outfile: cacheFilePath,
+    bundle: true,
+    format: 'esm',
+    platform: 'node',
+    target: 'node22',
+    packages: 'external',
+    sourcemap: 'inline',
+    plugins: [importMetaUrlPlugin],
+    loader: {
+      '.tsx': 'tsx',
+      '.ts': 'ts',
+      '.jsx': 'jsx',
+      '.js': 'js',
+      '.css': 'empty'
+    }
+  });
+
+  // Dynamic import with timestamp cache buster
+  const fileUrl = `${pathToFileURL(cacheFilePath).href}?t=${Date.now()}`;
+  const importedModule = await import(fileUrl);
+
+  const Component = importedModule.default;
+  if (!Component) {
+    throw new Error(`Page "${pageFilePath}" does not have a default export. Please provide "export default function Page()".`);
+  }
+
+  const { default: _, ...metadata } = importedModule;
+
+  return {
+    Component,
+    metadata
+  };
+}
+
+export async function clearCache(): Promise<void> {
+  try {
+    await fs.rm(CACHE_DIR, { recursive: true, force: true });
+  } catch {
+    // Ignore cache cleanup errors
+  }
+}

package/src/core/renderer.ts

@@ -0,0 +1,80 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { runWithRenderContext, IslandInstance } from './island-registry.js';
+import { formatHtml } from './formatter.js';
+
+export interface RenderResult {
+  html: string;
+  islands: IslandInstance[];
+}
+
+export interface RenderOptions {
+  pagePath: string;
+  Component: React.ComponentType<any>;
+  props?: Record<string, unknown>;
+  metadata?: {
+    title?: string;
+    description?: string;
+    lang?: string;
+    [key: string]: unknown;
+  };
+  basePath?: string;
+}
+
+export function renderPageToHtml(options: RenderOptions): RenderResult {
+  const { pagePath, Component, props = {}, metadata = {}, basePath = '' } = options;
+  const islands: IslandInstance[] = [];
+
+  const rawMarkup = runWithRenderContext(
+    { pagePath, islands },
+    () => renderToStaticMarkup(React.createElement(Component, props))
+  );
+
+  let finalHtml = rawMarkup;
+  const hasHtmlTag = /<html[^>]*>/i.test(finalHtml);
+  const hasDoctype = /<!DOCTYPE html>/i.test(finalHtml);
+
+  // If component returned only body contents / fragments, wrap in standard HTML shell
+  if (!hasHtmlTag) {
+    const lang = metadata.lang || 'en';
+    const titleTag = metadata.title ? `<title>${metadata.title}</title>` : '';
+    const descTag = metadata.description ? `<meta name="description" content="${metadata.description}">` : '';
+
+    finalHtml = `<!DOCTYPE html>
+<html lang="${lang}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  ${titleTag}
+  ${descTag}
+</head>
+<body>
+  ${finalHtml}
+</body>
+</html>`;
+  } else if (!hasDoctype) {
+    finalHtml = `<!DOCTYPE html>\n${finalHtml}`;
+  }
+
+  // If there are islands, inject script tags before </body> or at the end of the file
+  if (islands.length > 0) {
+    // Collect unique island names
+    const uniqueIslands = Array.from(new Set(islands.map(i => i.name)));
+    const assetPrefix = basePath ? (basePath.endsWith('/') ? basePath : `${basePath}/`) : '/';
+    const scriptTags = uniqueIslands
+      .map(name => `<script type="module" src="${assetPrefix}assets/islands/${name}.js"></script>`)
+      .join('\n');
+
+    if (/<\/body>/i.test(finalHtml)) {
+      finalHtml = finalHtml.replace(/<\/body>/i, `${scriptTags}\n</body>`);
+    } else {
+      finalHtml = `${finalHtml}\n${scriptTags}`;
+    }
+  }
+
+  return {
+    html: formatHtml(finalHtml),
+    islands
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,138 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loadPageModule, clearCache } from './core/loader.js';
+import { renderPageToHtml } from './core/renderer.js';
+import { bundleIslands } from './core/bundler.js';
+import { IslandInstance } from './core/island-registry.js';
+
+export { Island, island } from './core/island.js';
+export type { IslandProps } from './core/island.js';
+export { hydrateIsland } from './client/hydrate.js';
+export { renderPageToHtml } from './core/renderer.js';
+export { createEngine, ReactHtmlEngine } from './server/engine.js';
+export type { EngineOptions } from './server/engine.js';
+
+export interface BuildConfig {
+  root?: string;
+  pagesDir?: string;
+  outDir?: string;
+  publicDir?: string;
+  minify?: boolean;
+}
+
+export interface BuildResult {
+  pages: { input: string; output: string }[];
+  islands: string[];
+  outDir: string;
+}
+
+async function findFilesRecursively(dir: string, extensions: string[]): Promise<string[]> {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await findFilesRecursively(fullPath, extensions)));
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name);
+      if (extensions.includes(ext) && !entry.name.startsWith('_') && !entry.name.includes('.test.')) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+export async function build(config: BuildConfig = {}): Promise<BuildResult> {
+  const root = path.resolve(config.root || process.cwd());
+  const outDir = path.resolve(root, config.outDir || 'dist');
+  const minify = config.minify ?? true;
+
+  // Locate pages directory
+  let pagesDir = config.pagesDir ? path.resolve(root, config.pagesDir) : '';
+  if (!pagesDir) {
+    const candidateDirs = ['src/pages', 'pages'];
+    for (const cand of candidateDirs) {
+      const p = path.join(root, cand);
+      try {
+        const stat = await fs.stat(p);
+        if (stat.isDirectory()) {
+          pagesDir = p;
+          break;
+        }
+      } catch {
+        // Continue checking
+      }
+    }
+  }
+
+  if (!pagesDir) {
+    throw new Error(`Pages directory not found. Please create 'src/pages' or specify 'pagesDir'.`);
+  }
+
+  // Ensure output directory exists and is clean
+  await fs.mkdir(outDir, { recursive: true });
+
+  // Copy public static directory if present
+  const publicDir = path.resolve(root, config.publicDir || 'public');
+  try {
+    const publicStat = await fs.stat(publicDir);
+    if (publicStat.isDirectory()) {
+      await fs.cp(publicDir, outDir, { recursive: true });
+    }
+  } catch {
+    // Public directory optional
+  }
+
+  const pageFiles = await findFilesRecursively(pagesDir, ['.tsx', '.jsx', '.ts', '.js']);
+  if (pageFiles.length === 0) {
+    console.warn(`[react-html] No pages found in ${pagesDir}`);
+  }
+
+  const allDiscoveredIslands: IslandInstance[] = [];
+  const processedPages: { input: string; output: string }[] = [];
+
+  for (const pageFile of pageFiles) {
+    const relativePage = path.relative(pagesDir, pageFile);
+    const parsed = path.parse(relativePage);
+
+    // Compute destination path: index.tsx -> index.html, about.tsx -> about.html
+    const outHtmlFile = path.join(outDir, parsed.dir, `${parsed.name}.html`);
+    await fs.mkdir(path.dirname(outHtmlFile), { recursive: true });
+
+    // Load page module
+    const { Component, metadata } = await loadPageModule(pageFile);
+
+    // Render to pure HTML and extract islands
+    const { html, islands } = renderPageToHtml({
+      pagePath: pageFile,
+      Component,
+      metadata
+    });
+
+    await fs.writeFile(outHtmlFile, html, 'utf8');
+    processedPages.push({ input: pageFile, output: outHtmlFile });
+
+    if (islands.length > 0) {
+      allDiscoveredIslands.push(...islands);
+    }
+  }
+
+  // Bundle reactive islands
+  let bundledIslands: string[] = [];
+  if (allDiscoveredIslands.length > 0) {
+    bundledIslands = await bundleIslands(allDiscoveredIslands, { outDir, minify });
+  }
+
+  // Cleanup compile cache
+  await clearCache();
+
+  return {
+    pages: processedPages,
+    islands: bundledIslands,
+    outDir
+  };
+}
+