@hyperspan/plugin-preact 1.0.2 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/plugin-preact",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Hyperspan Plugin for Preact",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -11,7 +11,7 @@
   "author": "Vance Lucas <vance@vancelucas.com>",
   "license": "BSD-3-Clause",
   "keywords": [],
-  "homepage": "https://www.hyperspan.dev/docs/islands-architecture",
+  "homepage": "https://www.hyperspan.dev/docs/clientjs/islands",
   "bugs": {
     "url": "https://github.com/vlucas/hyperspan/issues"
   },

package/src/index.test.ts

@@ -0,0 +1,190 @@
+import { test, describe, expect } from 'bun:test';
+import { h } from 'preact';
+import { buildIslandHtml, renderPreactSSR, renderPreactIsland } from './index';
+
+// ---------------------------------------------------------------------------
+// Simple Preact components defined inline — no .tsx compilation needed
+// ---------------------------------------------------------------------------
+
+function Hello({ name = 'World', count = 0 }: { name?: string; count?: number }) {
+  return h('div', { class: 'hello' }, [
+    h('h1', null, `Hello ${name}!`),
+    h('p', null, `Count: ${count}`),
+  ]);
+}
+
+// ---------------------------------------------------------------------------
+// buildIslandHtml
+// ---------------------------------------------------------------------------
+
+describe('buildIslandHtml', () => {
+  const jsId = 'abc123';
+  const componentName = 'Hello';
+  const esmName = 'hello-component';
+
+  test('wraps SSR content in a div with the island id', () => {
+    const result = buildIslandHtml(jsId, componentName, esmName, '', '<p>SSR</p>');
+    expect(result).toContain(`<div id="${jsId}">`);
+    expect(result).toContain('<p>SSR</p>');
+  });
+
+  test('includes a module script tag with the correct source id', () => {
+    const result = buildIslandHtml(jsId, componentName, esmName, 'console.log(1)', '');
+    expect(result).toContain(`<script type="module" id="${jsId}_script" data-source-id="${jsId}">`);
+    expect(result).toContain(`import ${componentName} from "${esmName}"`);
+    expect(result).toContain('console.log(1)');
+  });
+
+  test('lazy loading wraps script in a template inside a hidden div', () => {
+    const result = buildIslandHtml(jsId, componentName, esmName, '', '<p>SSR</p>', {
+      loading: 'lazy',
+    });
+    expect(result).toContain('data-loading="lazy"');
+    expect(result).toContain('<template>');
+    expect(result).toContain('<p>SSR</p>');
+  });
+
+  test('eager loading (default) does not include a template tag', () => {
+    const result = buildIslandHtml(jsId, componentName, esmName, '', '<p>SSR</p>');
+    expect(result).not.toContain('data-loading="lazy"');
+    expect(result).not.toContain('<template>');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// renderPreactSSR
+// ---------------------------------------------------------------------------
+
+describe('renderPreactSSR', () => {
+  test('renders a component to an HTML string', () => {
+    const output = renderPreactSSR(Hello, { name: 'World' });
+    expect(output).toContain('<div');
+    expect(output).toContain('Hello World!');
+  });
+
+  test('passes props to the component', () => {
+    const output = renderPreactSSR(Hello, { name: 'Alice', count: 42 });
+    expect(output).toContain('Hello Alice!');
+    expect(output).toContain('Count: 42');
+  });
+
+  test('uses component defaults when props are omitted', () => {
+    const output = renderPreactSSR(Hello, {});
+    expect(output).toContain('Hello World!');
+    expect(output).toContain('Count: 0');
+  });
+
+  test('returns a string', () => {
+    const output = renderPreactSSR(Hello, {});
+    expect(typeof output).toBe('string');
+  });
+
+  test('escapes dangerous characters in prop values', () => {
+    const output = renderPreactSSR(Hello, { name: '<script>alert(1)</script>' });
+    expect(output).not.toContain('<script>alert');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// renderPreactIsland
+// ---------------------------------------------------------------------------
+
+describe('renderPreactIsland', () => {
+  test('throws when component has no __HS_ISLAND property', () => {
+    expect(() => renderPreactIsland(Hello, {})).toThrow(
+      'was not loaded with an island plugin'
+    );
+  });
+
+  test('returns an html_safe object', () => {
+    const jsId = 'island-test-1';
+    const esmName = 'hello-ssr';
+    (Hello as any).__HS_ISLAND = {
+      id: jsId,
+      render: (props: any, options: any = {}) => {
+        const ssrContent = renderPreactSSR(Hello, props);
+        const jsContent = `import { h as __hs_h, hydrate as __hs_hydrate } from 'preact';__hs_hydrate(__hs_h(Hello, ${JSON.stringify(props)}), document.getElementById("${jsId}"));`;
+        return buildIslandHtml(jsId, 'Hello', esmName, jsContent, ssrContent, options);
+      },
+    };
+
+    const result = renderPreactIsland(Hello, { name: 'World' });
+    expect(result).toHaveProperty('_kind', 'html_safe');
+  });
+
+  test('island output contains SSR-rendered HTML', () => {
+    const jsId = 'island-test-2';
+    const esmName = 'hello-ssr';
+    (Hello as any).__HS_ISLAND = {
+      id: jsId,
+      render: (props: any, options: any = {}) => {
+        const ssrContent = renderPreactSSR(Hello, props);
+        const jsContent = '';
+        return buildIslandHtml(jsId, 'Hello', esmName, jsContent, ssrContent, options);
+      },
+    };
+
+    const result = renderPreactIsland(Hello, { name: 'Alice', count: 7 });
+    expect(result.content).toContain('Hello Alice!');
+    expect(result.content).toContain('Count: 7');
+  });
+
+  test('island output contains the wrapper div with the correct id', () => {
+    const jsId = 'island-test-3';
+    (Hello as any).__HS_ISLAND = {
+      id: jsId,
+      render: (props: any, options: any = {}) =>
+        buildIslandHtml(jsId, 'Hello', 'hello', '', renderPreactSSR(Hello, props), options),
+    };
+
+    const result = renderPreactIsland(Hello, { name: 'Bob' });
+    expect(result.content).toContain(`<div id="${jsId}">`);
+  });
+
+  test('island output contains a hydration script tag', () => {
+    const jsId = 'island-test-4';
+    (Hello as any).__HS_ISLAND = {
+      id: jsId,
+      render: (props: any, options: any = {}) => {
+        const ssrContent = renderPreactSSR(Hello, props);
+        const jsContent = `import { h as __hs_h, hydrate as __hs_hydrate } from 'preact';__hs_hydrate(__hs_h(Hello, ${JSON.stringify(props)}), document.getElementById("${jsId}"));`;
+        return buildIslandHtml(jsId, 'Hello', 'hello', jsContent, ssrContent, options);
+      },
+    };
+
+    const result = renderPreactIsland(Hello, { name: 'World' });
+    expect(result.content).toContain('<script type="module"');
+    expect(result.content).toContain('hydrate');
+  });
+
+  test('ssr: false produces no SSR content', () => {
+    const jsId = 'island-test-5';
+    (Hello as any).__HS_ISLAND = {
+      id: jsId,
+      render: (props: any, options: any = {}) => {
+        if (options.ssr === false) {
+          return buildIslandHtml(jsId, 'Hello', 'hello', 'console.log("mount")', '', options);
+        }
+        return buildIslandHtml(jsId, 'Hello', 'hello', '', renderPreactSSR(Hello, props), options);
+      },
+    };
+
+    const result = renderPreactIsland(Hello, { name: 'World' }, { ssr: false, loading: undefined });
+    expect(result.content).not.toContain('Hello World!');
+    expect(result.content).toContain(`<div id="${jsId}"></div>`);
+  });
+
+  test('loading: lazy wraps the script in a template', () => {
+    const jsId = 'island-test-6';
+    (Hello as any).__HS_ISLAND = {
+      id: jsId,
+      render: (props: any, options: any = {}) =>
+        buildIslandHtml(jsId, 'Hello', 'hello', 'console.log(1)', renderPreactSSR(Hello, props), options),
+    };
+
+    const result = renderPreactIsland(Hello, { name: 'World' }, { ssr: true, loading: 'lazy' } as any);
+    expect(result.content).toContain('data-loading="lazy"');
+    expect(result.content).toContain('<template>');
+    expect(result.content).toContain('Hello World!');
+  });
+});

package/src/index.ts

@@ -1,36 +1,95 @@
 import { JS_IMPORT_MAP, JS_ISLAND_PUBLIC_PATH } from '@hyperspan/framework/client/js';
 import { assetHash } from '@hyperspan/framework/utils';
 import { IS_PROD } from '@hyperspan/framework/server';
-import { join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import type { Hyperspan as HS } from '@hyperspan/framework';
 import { html } from '@hyperspan/html';
+import { h } from 'preact';
+import { render as preactRenderToString } from 'preact-render-to-string';
 import debug from 'debug';
 
 const log = debug('hyperspan:plugin-preact');
 
+const CWD = process.cwd();
+
+/** Dev: stable `[name].js` via Bun default. Prod: hashed filenames for caching. */
+const ISLAND_JS_NAMING = IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined;
+
+function islandBundleBaseName(outputPath: string): string {
+  return String(outputPath.split('/').reverse()[0]!.replace(/\.js$/i, ''));
+}
+
+function pickEntryPointJsOutput(
+  outputs: ReadonlyArray<{ path: string; kind?: string }>,
+  entrySourcePath: string
+): { path: string } {
+  const js = outputs.filter((o) => o.path.endsWith('.js'));
+  const entry = js.find((o) => o.kind === 'entry-point');
+  if (entry) return entry;
+  const sourceBase = entrySourcePath.split('/').pop()!.replace(/\.(tsx|ts|jsx|js)$/i, '');
+  const byName = js.find((o) => {
+    const b = islandBundleBaseName(o.path);
+    return b === sourceBase || b.startsWith(`${sourceBase}-`);
+  });
+  if (byName) return byName;
+  if (js[0]) return js[0];
+  throw new Error('[Hyperspan] Preact island build produced no JS output');
+}
+
+/**
+ * Build the island wrapper HTML: a div for SSR content + a module script tag for client hydration.
+ * Exported so it can be imported by generated island module code and used directly in tests.
+ */
+export function buildIslandHtml(
+  jsId: string,
+  componentName: string,
+  esmName: string,
+  jsContent: string,
+  ssrContent: string,
+  options: { loading?: string } = {}
+): string {
+  const scriptTag = `<script type="module" id="${jsId}_script" data-source-id="${jsId}">import ${componentName} from "${esmName}";${jsContent}</script>`;
+  if (options.loading === 'lazy') {
+    return `<div id="${jsId}">${ssrContent}</div><div data-loading="lazy" style="height:1px;width:1px;overflow:hidden;"><template>\n${scriptTag}</template></div>`;
+  }
+  return `<div id="${jsId}">${ssrContent}</div>\n${scriptTag}`;
+}
+
+/**
+ * Render a Preact component to an HTML string (SSR).
+ * Exported for direct use in tests and external tooling.
+ */
+export function renderPreactSSR(Component: any, props: any = {}): string {
+  return preactRenderToString(h(Component, props));
+}
+
 // External ESM = https://esm.sh/preact@10.26.4/compat
-const PREACT_ISLAND_CACHE = new Map<string, string>();
+type PreactIslandCacheEntry = { contents: string; esmName: string };
+
+const PREACT_ISLAND_CACHE = new Map<string, PreactIslandCacheEntry>();
 
 /**
  * Build Preact client JS and copy to public folder
  */
 async function copyPreactToPublicFolder(config: HS.Config) {
   const currentNodeEnv = process.env.NODE_ENV || 'production';
-  const sourceFile = resolve(__dirname, './preact-client.ts');
+  const sourceFile = resolve(import.meta.dir, './preact-client.ts');
+  const outdir = resolve(CWD, config.publicDir, JS_ISLAND_PUBLIC_PATH.replace(/^\//, ''));
 
   // Preact client JS is always production mode
   process.env.NODE_ENV = 'production';
   const result = await Bun.build({
     entrypoints: [sourceFile],
-    outdir: join('./', config.publicDir, JS_ISLAND_PUBLIC_PATH),
-    naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
+    outdir,
+    naming: ISLAND_JS_NAMING,
     minify: true,
     format: 'esm',
     target: 'browser',
   });
   process.env.NODE_ENV = currentNodeEnv;
 
-  const builtFileName = String(result.outputs[0].path.split('/').reverse()[0]).replace('.js', '');
+  const preactEntry = pickEntryPointJsOutput(result.outputs, sourceFile);
+  const builtFileName = islandBundleBaseName(preactEntry.path);
   const builtFilePath = `${JS_ISLAND_PUBLIC_PATH}/${builtFileName}.js`;
 
   JS_IMPORT_MAP.set('preact', builtFilePath);
@@ -51,7 +110,7 @@ async function copyPreactToPublicFolder(config: HS.Config) {
 export function preactPlugin(): HS.Plugin {
   return async (config: HS.Config) => {
     try {
-      log('plguin loaded');
+      log('plugin loaded');
       // Ensure Preact can be loaded on the client
       if (!JS_IMPORT_MAP.has('preact')) {
         await copyPreactToPublicFolder(config);
@@ -66,11 +125,17 @@ export function preactPlugin(): HS.Plugin {
             log('tsx file loaded', args.path);
             const jsId = assetHash(args.path);
 
+            if (!JS_IMPORT_MAP.has('preact')) {
+              await copyPreactToPublicFolder(config);
+            }
+
             // Cache: Avoid re-processing the same file
             if (PREACT_ISLAND_CACHE.has(jsId)) {
+              const hit = PREACT_ISLAND_CACHE.get(jsId)!;
+              JS_IMPORT_MAP.set(hit.esmName, `${JS_ISLAND_PUBLIC_PATH}/${hit.esmName}.js`);
               log('tsx file cached', args.path);
               return {
-                contents: PREACT_ISLAND_CACHE.get(jsId) || '',
+                contents: hit.contents,
                 loader: 'js',
               };
             }
@@ -78,10 +143,11 @@ export function preactPlugin(): HS.Plugin {
             log('tsx file not cached, building...', args.path);
             // We need to build the file to ensure we can ship it to the client with dependencies
             // Ironic, right? Calling Bun.build() inside of a plugin that runs on Bun.build()?
+            const islandOutdir = resolve(CWD, config.publicDir, JS_ISLAND_PUBLIC_PATH.replace(/^\//, ''));
             const result = await Bun.build({
               entrypoints: [args.path],
-              outdir: join('./', config.publicDir, JS_ISLAND_PUBLIC_PATH),
-              naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
+              outdir: islandOutdir,
+              naming: ISLAND_JS_NAMING,
               external: Array.from(JS_IMPORT_MAP.keys()),
               minify: true,
               format: 'esm',
@@ -89,12 +155,14 @@ export function preactPlugin(): HS.Plugin {
               env: 'APP_PUBLIC_*',
             });
 
+            const entryOut = pickEntryPointJsOutput(result.outputs, args.path);
+            const esmName = islandBundleBaseName(entryOut.path);
+
             // Add output file to import map
-            const esmName = String(result.outputs[0].path.split('/').reverse()[0]).replace('.js', '');
             JS_IMPORT_MAP.set(esmName, `${JS_ISLAND_PUBLIC_PATH}/${esmName}.js`);
             log('added to import map', esmName, `${JS_ISLAND_PUBLIC_PATH}/${esmName}.js`);
 
-            let contents = await result.outputs[0].text();
+            let contents = await Bun.file(entryOut.path).text();
 
             // Look for the default export
             const RE_EXPORT_DEFAULT = /export\{([^\s]+) as default\}/;
@@ -120,8 +188,6 @@ export function preactPlugin(): HS.Plugin {
               );
             }
 
-            log('component name', componentName);
-
             // Add to contents so this is in the client JS as well
             contents = `import { h as __hs_h, render as __hs_render, hydrate as __hs_hydrate } from 'preact';${contents}`;
 
@@ -133,18 +199,14 @@ export function preactPlugin(): HS.Plugin {
             // Finally, we need to export all of the functions that do this work in a special way so we don't change the default export or other functions in the module, so that only the Hyperspan renderIsland() function can use them.
             const moduleCode = `// hyperspan:processed
 import { render as __hs_renderToString } from 'preact-render-to-string';
+import { buildIslandHtml as __hs_buildIslandHtml } from '@hyperspan/plugin-preact';
 
 // Original file contents
 ${contents}
 
 // hyperspan:preact-plugin
 function __hs_renderIsland(jsContent = '', ssrContent = '', options = {}) {
-  const scriptTag = \`<script type="module" id="${jsId}_script" data-source-id="${jsId}">import ${componentName} from "${esmName}";\${jsContent}</script>\`;
-  if (options.loading === 'lazy') {
-    return \`<div id="${jsId}">\${ssrContent}</div><div data-loading="lazy" style="height:1px;width:1px;overflow:hidden;"><template>\n\${scriptTag}</template></div>\`;
-  }
-
-  return \`<div id="${jsId}">\${ssrContent}</div>\n\${scriptTag}\`;
+  return __hs_buildIslandHtml("${jsId}", "${componentName}", "${esmName}", jsContent, ssrContent, options);
 }
 ${componentName}.__HS_ISLAND = {
   id: "${jsId}",
@@ -162,7 +224,7 @@ ${componentName}.__HS_ISLAND = {
 }
 `;
 
-            PREACT_ISLAND_CACHE.set(jsId, moduleCode);
+            PREACT_ISLAND_CACHE.set(jsId, { contents: moduleCode, esmName });
 
             return {
               contents: moduleCode,

package/src/test-fixtures/minimal-island.tsx

@@ -0,0 +1,9 @@
+import { h } from 'preact';
+
+export default function MinimalIsland(props: { name?: string; count?: number }) {
+  return h(
+    'div',
+    { className: 'minimal-island-fixture' },
+    `Hello ${props.name ?? '?'} (${props.count ?? 0})`
+  );
+}

package/src/test-fixtures/uses-document-island.tsx

@@ -0,0 +1,8 @@
+import { h } from 'preact';
+
+/** Top-level DOM access (fires as soon as this module is evaluated, before any render). */
+void document.documentElement;
+
+export default function UsesDocumentIsland(_props: Record<string, never>) {
+  return h('div', { 'data-test': 'uses-document-island' }, 'fixture');
+}

package/src/test-fixtures/uses-window-vanilla.js

@@ -0,0 +1,6 @@
+'use strict';
+
+/** Top-level browser global access (fires as soon as this module is evaluated). */
+void window.__hyperspan_fixture__;
+
+export const marker = 'uses-window-vanilla';