@hyperspan/plugin-vue 1.0.0

package/.prettierignore

@@ -0,0 +1 @@
+src/vue-client.ts

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hyperspan/plugin-vue",
+  "version": "1.0.0",
+  "description": "Hyperspan Plugin for Vue.js Client Islands",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "public": true,
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Vance Lucas <vance@vancelucas.com>",
+  "license": "BSD-3-Clause",
+  "keywords": [],
+  "homepage": "https://www.hyperspan.dev/docs/clientjs/islands",
+  "bugs": {
+    "url": "https://github.com/vlucas/hyperspan/issues"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vlucas/hyperspan.git"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "vue": "^3.5.0"
+  },
+  "peerDependencies": {
+    "@hyperspan/html": "^1.0.0",
+    "@hyperspan/framework": "^1.0.1"
+  },
+  "dependencies": {
+    "@vue/compiler-sfc": "^3.5.0",
+    "@vue/server-renderer": "^3.5.0",
+    "debug": "^4.4.3",
+    "vue": "^3.5.30"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,205 @@
+import { test, describe, expect } from 'bun:test';
+import { defineComponent, h } from 'vue';
+import { buildIslandHtml, renderVueSSR, renderVueIsland } from './index';
+
+// ---------------------------------------------------------------------------
+// Simple Vue components defined inline — no .vue compilation needed
+// ---------------------------------------------------------------------------
+
+const Hello = defineComponent({
+  props: {
+    name: { type: String, default: 'World' },
+    count: { type: Number, default: 0 },
+  },
+  render() {
+    return h('div', { class: 'hello' }, [
+      h('h1', `Hello ${this.name}!`),
+      h('p', `Count: ${this.count}`),
+    ]);
+  },
+});
+
+// ---------------------------------------------------------------------------
+// buildIslandHtml
+// ---------------------------------------------------------------------------
+
+describe('buildIslandHtml', () => {
+  const jsId = 'vue-abc123';
+  const componentName = '__hs_vue_component';
+  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>');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// renderVueSSR
+// ---------------------------------------------------------------------------
+
+describe('renderVueSSR', () => {
+  test('renders a component to an HTML string', async () => {
+    const output = await renderVueSSR(Hello, { name: 'World' });
+    expect(output).toContain('<div');
+    expect(output).toContain('Hello World!');
+  });
+
+  test('passes props to the component', async () => {
+    const output = await renderVueSSR(Hello, { name: 'Alice', count: 42 });
+    expect(output).toContain('Hello Alice!');
+    expect(output).toContain('Count: 42');
+  });
+
+  test('uses component defaults when props are omitted', async () => {
+    const output = await renderVueSSR(Hello, {});
+    expect(output).toContain('Hello World!');
+    expect(output).toContain('Count: 0');
+  });
+
+  test('returns a string', async () => {
+    const output = await renderVueSSR(Hello, {});
+    expect(typeof output).toBe('string');
+  });
+
+  test('Vue SSR output contains data-v- hydration markers', async () => {
+    // Vue SSR adds data-v- attributes for hydration matching
+    const output = await renderVueSSR(Hello, { name: 'World' });
+    // Just verify the component's root element is present
+    expect(output).toMatch(/class="hello"/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// renderVueIsland
+// ---------------------------------------------------------------------------
+
+describe('renderVueIsland', () => {
+  test('throws when component has no __HS_ISLAND property', async () => {
+    const Bare = defineComponent({ render: () => h('div') });
+    await expect(renderVueIsland(Bare, {})).rejects.toThrow('was not loaded with an island plugin');
+  });
+
+  test('returns an html_safe object', async () => {
+    const jsId = 'vue-island-1';
+    const mockComponent = defineComponent({ render: () => h('span') }) as any;
+    mockComponent.__HS_ISLAND = {
+      id: jsId,
+      render: async (props: any, options: any = {}) => {
+        const ssrContent = await renderVueSSR(Hello, props);
+        return buildIslandHtml(jsId, '__hs_vue_component', 'hello-vue', '', ssrContent, options);
+      },
+    };
+
+    const result = await renderVueIsland(mockComponent, { name: 'World' });
+    expect(result).toHaveProperty('_kind', 'html_safe');
+  });
+
+  test('island output contains SSR-rendered HTML', async () => {
+    const jsId = 'vue-island-2';
+    const mockComponent = defineComponent({ render: () => h('span') }) as any;
+    mockComponent.__HS_ISLAND = {
+      id: jsId,
+      render: async (props: any, options: any = {}) => {
+        const ssrContent = await renderVueSSR(Hello, props);
+        return buildIslandHtml(jsId, '__hs_vue_component', 'hello-vue', '', ssrContent, options);
+      },
+    };
+
+    const result = await renderVueIsland(mockComponent, { name: 'Vue', count: 9 });
+    expect(result.content).toContain('Hello Vue!');
+    expect(result.content).toContain('Count: 9');
+  });
+
+  test('island output contains the wrapper div with the correct id', async () => {
+    const jsId = 'vue-island-3';
+    const mockComponent = defineComponent({ render: () => h('span') }) as any;
+    mockComponent.__HS_ISLAND = {
+      id: jsId,
+      render: async (props: any, options: any = {}) => {
+        const ssrContent = await renderVueSSR(Hello, props);
+        return buildIslandHtml(jsId, '__hs_vue_component', 'hello-vue', '', ssrContent, options);
+      },
+    };
+
+    const result = await renderVueIsland(mockComponent, { name: 'World' });
+    expect(result.content).toContain(`<div id="${jsId}">`);
+  });
+
+  test('island output contains a hydration script tag', async () => {
+    const jsId = 'vue-island-4';
+    const esmName = 'hello-vue';
+    const mockComponent = defineComponent({ render: () => h('span') }) as any;
+    mockComponent.__HS_ISLAND = {
+      id: jsId,
+      render: async (props: any, options: any = {}) => {
+        const ssrContent = await renderVueSSR(Hello, props);
+        const jsContent = `import { createSSRApp as __hs_createSSRApp } from 'vue';__hs_createSSRApp(__hs_vue_component, ${JSON.stringify(props)}).mount(document.getElementById("${jsId}"));`;
+        return buildIslandHtml(jsId, '__hs_vue_component', esmName, jsContent, ssrContent, options);
+      },
+    };
+
+    const result = await renderVueIsland(mockComponent, { name: 'World' });
+    expect(result.content).toContain('<script type="module"');
+    expect(result.content).toContain('createSSRApp');
+  });
+
+  test('ssr: false produces no SSR content', async () => {
+    const jsId = 'vue-island-5';
+    const mockComponent = defineComponent({ render: () => h('span') }) as any;
+    mockComponent.__HS_ISLAND = {
+      id: jsId,
+      render: async (props: any, options: any = {}) => {
+        if (options.ssr === false) {
+          return buildIslandHtml(jsId, '__hs_vue_component', 'hello-vue', 'console.log("mount")', '', options);
+        }
+        const ssrContent = await renderVueSSR(Hello, props);
+        return buildIslandHtml(jsId, '__hs_vue_component', 'hello-vue', '', ssrContent, options);
+      },
+    };
+
+    const result = await renderVueIsland(mockComponent, { 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', async () => {
+    const jsId = 'vue-island-6';
+    const mockComponent = defineComponent({ render: () => h('span') }) as any;
+    mockComponent.__HS_ISLAND = {
+      id: jsId,
+      render: async (props: any, options: any = {}) => {
+        const ssrContent = await renderVueSSR(Hello, props);
+        return buildIslandHtml(jsId, '__hs_vue_component', 'hello-vue', 'console.log(1)', ssrContent, options);
+      },
+    };
+
+    const result = await renderVueIsland(mockComponent, { 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

@@ -0,0 +1,320 @@
+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 type { Hyperspan as HS } from '@hyperspan/framework';
+import { html } from '@hyperspan/html';
+import debug from 'debug';
+import { parse, compileScript, compileTemplate, rewriteDefault } from '@vue/compiler-sfc';
+import './types.d';
+
+const log = debug('hyperspan:plugin-vue');
+
+/**
+ * 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 Vue component to an HTML string (SSR).
+ * Exported for direct use in tests and external tooling.
+ */
+export async function renderVueSSR(Component: any, props: any = {}): Promise<string> {
+  const { createSSRApp } = await import('vue');
+  const { renderToString } = await import('@vue/server-renderer');
+  const app = createSSRApp(Component, props);
+  return renderToString(app);
+}
+
+const VUE_ISLAND_CACHE = new Map<string, string>();
+
+/**
+ * Compile a Vue SFC to JavaScript using @vue/compiler-sfc.
+ * Returns the combined script + template JS code ready to execute.
+ */
+async function compileVueSFC(
+  source: string,
+  filepath: string,
+  id: string,
+  ssr: boolean
+): Promise<string> {
+  const { descriptor, errors } = parse(source, { filename: filepath });
+
+  if (errors.length) {
+    throw new Error(
+      `Vue SFC parse errors in ${filepath}:\n${errors.map((e) => e.message).join('\n')}`
+    );
+  }
+
+  // Compile <script> / <script setup> block
+  let scriptCode = 'const __sfc__ = {};';
+  let bindingMetadata: Record<string, any> | undefined;
+  if (descriptor.script || descriptor.scriptSetup) {
+    const scriptResult = compileScript(descriptor, { id });
+    bindingMetadata = scriptResult.bindings;
+    // Rename `export default` to `const __sfc__ =` so we can augment it
+    scriptCode = rewriteDefault(scriptResult.content, '__sfc__');
+  }
+
+  // Compile <template> block
+  let templateCode = '';
+  if (descriptor.template) {
+    const templateResult = compileTemplate({
+      source: descriptor.template.content,
+      filename: filepath,
+      id,
+      ssr,
+      scoped: descriptor.styles.some((s) => s.scoped),
+      // Pass binding metadata so the template compiler knows which vars are
+      // <script setup> bindings and generates $setup.x refs instead of _ctx.x
+      compilerOptions: bindingMetadata ? { bindingMetadata } : undefined,
+    });
+
+    if (templateResult.errors.length) {
+      throw new Error(
+        `Vue SFC template errors in ${filepath}:\n${templateResult.errors.map((e) => (typeof e === 'string' ? e : e.message)).join('\n')}`
+      );
+    }
+
+    templateCode = templateResult.code;
+  }
+
+  // Combine: attach render/ssrRender to the component object, then export it
+  const renderKey = ssr ? 'ssrRender' : 'render';
+  return `${scriptCode}\n${templateCode}\n__sfc__.${renderKey} = ${renderKey};\nexport default __sfc__;\n`;
+}
+
+/**
+ * Build Vue client JS and copy to public folder
+ */
+async function copyVueToPublicFolder(config: HS.Config) {
+  const outdir = join('./', config.publicDir, JS_ISLAND_PUBLIC_PATH);
+  const devOutputFile = join(outdir, 'vue-client.js');
+
+  // In dev mode, skip the build if the file already exists to avoid
+  // conflicts with bun --watch (building vue triggers watch restarts)
+  if (!IS_PROD && (await Bun.file(devOutputFile).exists())) {
+    const builtFilePath = `${JS_ISLAND_PUBLIC_PATH}/vue-client.js`;
+    JS_IMPORT_MAP.set('vue', builtFilePath);
+    JS_IMPORT_MAP.set('vue/dist/vue.esm-bundler.js', builtFilePath);
+    return;
+  }
+
+  const currentNodeEnv = process.env.NODE_ENV || 'production';
+  const sourceFile = resolve(__dirname, './vue-client.ts');
+
+  // Vue client JS is always production mode
+  process.env.NODE_ENV = 'production';
+  const result = await Bun.build({
+    entrypoints: [sourceFile],
+    outdir,
+    naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
+    minify: true,
+    format: 'esm',
+    target: 'browser',
+    define: {
+      __VUE_OPTIONS_API__: 'true',
+      __VUE_PROD_DEVTOOLS__: 'false',
+      __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false',
+    },
+  });
+  process.env.NODE_ENV = currentNodeEnv;
+
+  const builtFileName = String(result.outputs[0].path.split('/').reverse()[0]).replace('.js', '');
+  const builtFilePath = `${JS_ISLAND_PUBLIC_PATH}/${builtFileName}.js`;
+
+  JS_IMPORT_MAP.set('vue', builtFilePath);
+  JS_IMPORT_MAP.set('vue/dist/vue.esm-bundler.js', builtFilePath);
+}
+
+/**
+ * Hyperspan Vue Plugin
+ */
+export function vuePlugin(): HS.Plugin {
+  return async (config: HS.Config) => {
+    try {
+      log('plugin loaded');
+      // Ensure Vue can be loaded on the client
+      if (!JS_IMPORT_MAP.has('vue')) {
+        await copyVueToPublicFolder(config);
+      }
+
+      // Define a Bun plugin to handle .vue files
+      await Bun.plugin({
+        name: 'Hyperspan Vue Loader',
+        async setup(build) {
+          // when a .vue file is imported...
+          build.onLoad({ filter: /\.vue$/ }, async (args) => {
+            log('vue file loaded', args.path);
+            const jsId = assetHash(args.path);
+
+            // Cache: Avoid re-processing the same file
+            if (VUE_ISLAND_CACHE.has(jsId)) {
+              log('vue file cached', args.path);
+              return {
+                contents: VUE_ISLAND_CACHE.get(jsId) || '',
+                loader: 'js',
+              };
+            }
+
+            log('vue file not cached, building...', args.path);
+
+            const source = await Bun.file(args.path).text();
+
+            // Compile the Vue SFC for server-side rendering
+            const ssrCode = await compileVueSFC(source, args.path, jsId, true);
+
+            const outdir = join('./', config.publicDir, JS_ISLAND_PUBLIC_PATH);
+            const baseName = args.path.split('/').pop()!.replace('.vue', '');
+
+            let esmName: string;
+            if (!IS_PROD) {
+              // In dev mode, write compiled JS directly — avoids nested Bun.build() inside
+              // Bun.plugin() onLoad which causes EISDIR conflicts under bun --watch.
+              // The browser import map resolves 'vue' to vue-client.js.
+              const clientCode = await compileVueSFC(source, args.path, jsId, false);
+              await Bun.write(join(outdir, `${baseName}.js`), clientCode);
+              esmName = baseName;
+            } else {
+              // Production: full bundle with tree-shaking and minification
+              const vueClientPlugin = {
+                name: 'vue-client-compiler',
+                setup(clientBuild: any) {
+                  clientBuild.onLoad(
+                    { filter: /\.vue$/ },
+                    async ({ path }: { path: string }) => {
+                      const src = await Bun.file(path).text();
+                      const clientId = assetHash(path);
+                      const compiledCode = await compileVueSFC(src, path, clientId, false);
+                      return { contents: compiledCode, loader: 'js' };
+                    }
+                  );
+                },
+              };
+
+              const clientResult = await Bun.build({
+                entrypoints: [args.path],
+                outdir,
+                naming: '[dir]/[name]-[hash].[ext]',
+                external: Array.from(JS_IMPORT_MAP.keys()),
+                minify: true,
+                format: 'esm',
+                target: 'browser',
+                plugins: [vueClientPlugin],
+                env: 'APP_PUBLIC_*',
+                define: {
+                  __VUE_OPTIONS_API__: 'true',
+                  __VUE_PROD_DEVTOOLS__: 'false',
+                  __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false',
+                },
+              });
+
+              esmName = String(clientResult.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`);
+
+            // Use a fixed component identifier throughout — no name extraction needed
+            // since we control the SSR module code and always rename to __sfc__.
+            const componentName = '__hs_vue_component';
+
+            // Build the final module code.
+            // The SSR compiled code is included inline for server-side rendering via @vue/server-renderer.
+            // The client script imports the ESM bundle and uses Vue's createSSRApp for hydration.
+            // Note: render() is async because Vue's renderToString() returns a Promise.
+            const moduleCode = `// hyperspan:processed
+function __hs_buildIslandHtml(jsId, componentName, esmName, jsContent, ssrContent, options) {
+  options = 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}\`;
+}
+
+// Server-side compiled Vue component
+${ssrCode}
+const ${componentName} = __sfc__;
+
+// hyperspan:vue-plugin
+function __hs_renderIsland(jsContent = '', ssrContent = '', options = {}) {
+  return __hs_buildIslandHtml("${jsId}", "__hs_vue_component", "${esmName}", jsContent, ssrContent, options);
+}
+${componentName}.__HS_ISLAND = {
+  id: "${jsId}",
+  render: async (props, options = {}) => {
+    // Dynamic imports keep vue/server-renderer out of the static module graph
+    // so the CSS-extraction bundler does not try to bundle them.
+    const { createSSRApp: __hs_createSSRApp } = await import('vue');
+    const { renderToString: __hs_renderToString } = await import('@vue/server-renderer');
+
+    if (options.ssr === false) {
+      const jsContent = \`import { createApp as __hs_createApp } from 'vue';__hs_createApp(__hs_vue_component, \${JSON.stringify(props)}).mount(document.getElementById("${jsId}"));\`;
+      return __hs_renderIsland(jsContent, '', options);
+    }
+
+    const app = __hs_createSSRApp(${componentName}, props);
+    const ssrContent = await __hs_renderToString(app);
+    const jsContent = \`import { createSSRApp as __hs_createSSRApp } from 'vue';__hs_createSSRApp(__hs_vue_component, \${JSON.stringify(props)}).mount(document.getElementById("${jsId}"));\`;
+    return __hs_renderIsland(jsContent, ssrContent, options);
+  }
+};
+`;
+
+            VUE_ISLAND_CACHE.set(jsId, moduleCode);
+
+            return {
+              contents: moduleCode,
+              loader: 'js',
+            };
+          });
+        },
+      });
+    } catch (e) {
+      log('ERROR: plugin build error', e);
+      console.error('[Hyperspan] @hyperspan/plugin-vue build error');
+      console.error(e);
+      throw e;
+    }
+  };
+}
+
+/**
+ * Render a Vue island component.
+ * Returns a Promise because Vue's renderToString() is async.
+ */
+export async function renderVueIsland(
+  Component: any,
+  props: any = {},
+  options = {
+    ssr: true,
+    loading: undefined,
+  }
+) {
+  // Render island with its own logic
+  if (Component.__HS_ISLAND?.render) {
+    return html.raw(await Component.__HS_ISLAND.render(props, options));
+  }
+
+  throw new Error(
+    `Module ${Component.name} was not loaded with an island plugin! Did you forget to install an island plugin and add it to the 'plugins' option in your hyperspan.config.ts file?`
+  );
+}

package/src/types.d.ts

@@ -0,0 +1,7 @@
+export declare global {
+  module '*.vue' {
+    import type { DefineComponent } from 'vue';
+    const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>;
+    export default component;
+  }
+}

package/src/vue-client.ts

@@ -0,0 +1 @@
+export * from 'vue';

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compileOnSave": true,
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "target": "es2019",
+    "lib": ["ESNext", "dom", "dom.iterable"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "esModuleInterop": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "composite": true,
+    "strict": true,
+    "declaration": true,
+    "sourceMap": true,
+    "downlevelIteration": true,
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowJs": true
+  },
+  "exclude": ["node_modules", "__tests__", "*.test.ts"]
+}