unhead 3.0.5 → 3.1.0

package/dist/stream/unplugin.d.mts

@@ -0,0 +1,81 @@
+import * as unplugin from 'unplugin';
+import { UnpluginOptions } from 'unplugin';
+
+declare const VIRTUAL_CLIENT_ID = "virtual:@unhead/streaming-client";
+declare const VIRTUAL_IIFE_ID = "virtual:@unhead/streaming-iife.js";
+type Nonce = string | (() => string | undefined);
+interface StreamingPluginOptions {
+    /** Framework package e.g. '@unhead/vue' */
+    framework: string;
+    /** Plugin name (optional, defaults to `${framework}:streaming`) */
+    name?: string;
+    /**
+     * File extension filter for transform hook, e.g. /\.vue$/. Optional;
+     * only required by frameworks whose client streaming support relies on
+     * source-level AST injection (React/Solid/Svelte). Vue does not use it.
+     */
+    filter?: RegExp;
+    /** Transform handler called for files matching `filter`. */
+    transform?: (code: string, id: string, options?: {
+        ssr?: boolean;
+    }) => {
+        code: string;
+        map?: any;
+    } | null | undefined | void;
+    /**
+     * How to load the streaming client (vite-only, ignored on webpack/rspack/rollup where
+     * index.html injection isn't available; frameworks inject the iife themselves in SSR).
+     * - 'async' (default): Non-blocking external script. In dev served from a virtual
+     *   module; in production emitted as a real asset chunk via `emitFile`.
+     * - 'inline': Inline the IIFE directly in HTML. Largest HTML, smallest TTFB,
+     *   always safe in production. Recommended for streaming SSR.
+     * - 'module': ES module dynamic import of the client bootstrap. Vite rewrites the
+     *   import path through its module graph so it survives production builds.
+     * @default 'async'
+     */
+    mode?: 'async' | 'inline' | 'module';
+    /**
+     * CSP nonce forwarded on every injected `<script>` tag. Pass a string or a
+     * function returning a string (useful when the nonce rotates per request).
+     * Omit to inject without a nonce.
+     */
+    nonce?: Nonce;
+    /**
+     * Stream key global name; must match `experimentalStreamKey` on the server
+     * head instance. Used by dev-mode warnings to detect when the server
+     * bootstrap script hasn't run (common misconfig).
+     * @default '__unhead__'
+     */
+    streamKey?: string;
+    /**
+     * Emit a warning when the client IIFE runs but no server bootstrap queue
+     * has been installed (i.e. server didn't call `wrapStream` /
+     * `renderSSRHeadShell`). Dev-only.
+     * @default true in dev, false in prod
+     */
+    warnOnMissingServerBootstrap?: boolean;
+}
+/**
+ * Builds the bundler-agnostic unplugin hook set for the streaming plugin. Exposed so
+ * framework wrappers (e.g. `@unhead/vue/bundler`) can bake in their own
+ * `framework`, `filter`, and `transform` while still using this factory
+ * to produce hooks that work across vite/webpack/rspack/rollup/esbuild via `createUnplugin`.
+ *
+ * SSR detection is bundler-specific:
+ * - vite build: `config.env.isSsrBuild`
+ * - vite dev (v6+ environments): `this.environment.name === 'ssr'` per-transform
+ * - webpack/rspack: `compiler.options.name === 'server'` or `target === 'node'`
+ */
+declare function buildStreamingPluginOptions(options: StreamingPluginOptions): UnpluginOptions;
+/**
+ * Internal cross-bundler unplugin factory. Framework wrappers pick a single bundler's
+ * output (`.vite`, `.webpack`, `.rspack`, etc.) to expose via their own subpath export.
+ *
+ * Consumers should prefer the unified framework bundler entry (e.g.
+ * `@unhead/{vue,react,svelte,solid-js}/bundler`) rather than importing this
+ * directly.
+ */
+declare const createStreamingPlugin: unplugin.UnpluginInstance<StreamingPluginOptions, boolean>;
+
+export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, buildStreamingPluginOptions, createStreamingPlugin };
+export type { Nonce, StreamingPluginOptions };

package/dist/stream/unplugin.d.ts

@@ -0,0 +1,81 @@
+import * as unplugin from 'unplugin';
+import { UnpluginOptions } from 'unplugin';
+
+declare const VIRTUAL_CLIENT_ID = "virtual:@unhead/streaming-client";
+declare const VIRTUAL_IIFE_ID = "virtual:@unhead/streaming-iife.js";
+type Nonce = string | (() => string | undefined);
+interface StreamingPluginOptions {
+    /** Framework package e.g. '@unhead/vue' */
+    framework: string;
+    /** Plugin name (optional, defaults to `${framework}:streaming`) */
+    name?: string;
+    /**
+     * File extension filter for transform hook, e.g. /\.vue$/. Optional;
+     * only required by frameworks whose client streaming support relies on
+     * source-level AST injection (React/Solid/Svelte). Vue does not use it.
+     */
+    filter?: RegExp;
+    /** Transform handler called for files matching `filter`. */
+    transform?: (code: string, id: string, options?: {
+        ssr?: boolean;
+    }) => {
+        code: string;
+        map?: any;
+    } | null | undefined | void;
+    /**
+     * How to load the streaming client (vite-only, ignored on webpack/rspack/rollup where
+     * index.html injection isn't available; frameworks inject the iife themselves in SSR).
+     * - 'async' (default): Non-blocking external script. In dev served from a virtual
+     *   module; in production emitted as a real asset chunk via `emitFile`.
+     * - 'inline': Inline the IIFE directly in HTML. Largest HTML, smallest TTFB,
+     *   always safe in production. Recommended for streaming SSR.
+     * - 'module': ES module dynamic import of the client bootstrap. Vite rewrites the
+     *   import path through its module graph so it survives production builds.
+     * @default 'async'
+     */
+    mode?: 'async' | 'inline' | 'module';
+    /**
+     * CSP nonce forwarded on every injected `<script>` tag. Pass a string or a
+     * function returning a string (useful when the nonce rotates per request).
+     * Omit to inject without a nonce.
+     */
+    nonce?: Nonce;
+    /**
+     * Stream key global name; must match `experimentalStreamKey` on the server
+     * head instance. Used by dev-mode warnings to detect when the server
+     * bootstrap script hasn't run (common misconfig).
+     * @default '__unhead__'
+     */
+    streamKey?: string;
+    /**
+     * Emit a warning when the client IIFE runs but no server bootstrap queue
+     * has been installed (i.e. server didn't call `wrapStream` /
+     * `renderSSRHeadShell`). Dev-only.
+     * @default true in dev, false in prod
+     */
+    warnOnMissingServerBootstrap?: boolean;
+}
+/**
+ * Builds the bundler-agnostic unplugin hook set for the streaming plugin. Exposed so
+ * framework wrappers (e.g. `@unhead/vue/bundler`) can bake in their own
+ * `framework`, `filter`, and `transform` while still using this factory
+ * to produce hooks that work across vite/webpack/rspack/rollup/esbuild via `createUnplugin`.
+ *
+ * SSR detection is bundler-specific:
+ * - vite build: `config.env.isSsrBuild`
+ * - vite dev (v6+ environments): `this.environment.name === 'ssr'` per-transform
+ * - webpack/rspack: `compiler.options.name === 'server'` or `target === 'node'`
+ */
+declare function buildStreamingPluginOptions(options: StreamingPluginOptions): UnpluginOptions;
+/**
+ * Internal cross-bundler unplugin factory. Framework wrappers pick a single bundler's
+ * output (`.vite`, `.webpack`, `.rspack`, etc.) to expose via their own subpath export.
+ *
+ * Consumers should prefer the unified framework bundler entry (e.g.
+ * `@unhead/{vue,react,svelte,solid-js}/bundler`) rather than importing this
+ * directly.
+ */
+declare const createStreamingPlugin: unplugin.UnpluginInstance<StreamingPluginOptions, boolean>;
+
+export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, buildStreamingPluginOptions, createStreamingPlugin };
+export type { Nonce, StreamingPluginOptions };

package/dist/stream/unplugin.mjs

@@ -0,0 +1,166 @@
+import { createUnplugin } from 'unplugin';
+
+const VIRTUAL_CLIENT_ID = "virtual:@unhead/streaming-client";
+const VIRTUAL_IIFE_ID = "virtual:@unhead/streaming-iife.js";
+const RESOLVED_ID = `\0${VIRTUAL_CLIENT_ID}`;
+const RESOLVED_IIFE_ID = `\0${VIRTUAL_IIFE_ID}`;
+const VIRTUAL_RE = /virtual:@unhead\/streaming/;
+const RESOLVED_RE = /^\0virtual:@unhead\/streaming/;
+let iifeCode;
+let iifeCodeLoading;
+async function loadIifeCode() {
+  if (iifeCode)
+    return;
+  iifeCodeLoading ||= import('unhead/stream/iife').then((mod) => {
+    iifeCode = mod.streamingIifeCode;
+  });
+  await iifeCodeLoading;
+}
+function resolveNonce(nonce) {
+  if (!nonce)
+    return void 0;
+  return typeof nonce === "function" ? nonce() : nonce;
+}
+function buildClientStub(framework, streamKey, warnOnMissing) {
+  const key = JSON.stringify(streamKey);
+  const warnBranch = warnOnMissing ? `else{console.warn('[unhead] streaming client loaded but window['+${key}+'] is undefined; did the server call wrapStream()/renderSSRHeadShell()?')}` : "";
+  return `import{createHead}from'${framework}/client'
+const s=window[${key}];if(s){const q=s._q;s._q=[];const h=createHead({document});q.forEach(e=>h.push(e));s.push=e=>h.push(e);s._head=h}${warnBranch}`;
+}
+function buildStreamingPluginOptions(options) {
+  const {
+    framework,
+    name,
+    mode = "async",
+    nonce,
+    streamKey = "__unhead__",
+    warnOnMissingServerBootstrap
+  } = options;
+  const state = {
+    isBuild: false,
+    ssr: false
+  };
+  function isSSRCall(hookThis, opts) {
+    const envName = hookThis?.environment?.name;
+    return envName === "ssr" || envName === "server" || opts?.ssr === true || state.ssr;
+  }
+  function warnEnabled() {
+    return warnOnMissingServerBootstrap ?? !state.isBuild;
+  }
+  return {
+    name: name ?? `${framework}:streaming`,
+    enforce: "pre",
+    async buildStart() {
+      await loadIifeCode();
+      if (mode === "async" && state.isBuild && typeof this.emitFile === "function") {
+        if (!iifeCode)
+          throw new Error("[unhead] Streaming IIFE not built. Run `pnpm build` in packages/unhead first.");
+        state.emittedIifeFileName = this.emitFile({
+          type: "asset",
+          name: "unhead-streaming.js",
+          source: iifeCode
+        });
+      }
+    },
+    resolveId: {
+      filter: { id: VIRTUAL_RE },
+      handler(id) {
+        if (id === VIRTUAL_CLIENT_ID || id === `/${VIRTUAL_CLIENT_ID}`)
+          return RESOLVED_ID;
+        if (id === VIRTUAL_IIFE_ID || id === `/${VIRTUAL_IIFE_ID}`)
+          return RESOLVED_IIFE_ID;
+      }
+    },
+    load: {
+      filter: { id: RESOLVED_RE },
+      handler(id, opts) {
+        const isSSR = isSSRCall(this, opts);
+        if (id === RESOLVED_ID) {
+          if (isSSR)
+            return { code: "export {}", moduleType: "js" };
+          return {
+            code: buildClientStub(framework, streamKey, warnEnabled()),
+            moduleType: "js"
+          };
+        }
+        if (id === RESOLVED_IIFE_ID) {
+          if (isSSR)
+            return { code: "", moduleType: "js" };
+          if (!iifeCode)
+            throw new Error("[unhead] Streaming IIFE not built. Run `pnpm build` in packages/unhead first.");
+          return { code: iifeCode, moduleType: "js" };
+        }
+      }
+    },
+    ...options.transform && options.filter ? {
+      transform: {
+        filter: { id: options.filter },
+        handler(code, id, opts) {
+          return options.transform(code, id, { ssr: isSSRCall(this, opts) });
+        }
+      }
+    } : {},
+    webpack(compiler) {
+      const { name: n, target } = compiler.options;
+      if (n === "server" || target === "node" || target === "async-node")
+        state.ssr = true;
+    },
+    rspack(compiler) {
+      const { name: n, target } = compiler.options;
+      if (n === "server" || target === "node" || target === "async-node")
+        state.ssr = true;
+    },
+    vite: {
+      apply(_config, env) {
+        if (env.isSsrBuild)
+          state.ssr = true;
+        if (env.command === "build")
+          state.isBuild = true;
+        return true;
+      },
+      configResolved(config) {
+        if (config.command === "build")
+          state.isBuild = true;
+      },
+      transformIndexHtml: {
+        // `order: 'pre'` is separate from the plugin-level `enforce: 'pre'`:
+        // it runs this HTML transform before other non-pre HTML transforms
+        // so the virtual module `<script>` tags we inject go through the
+        // full Vite plugin pipeline (resolveId/load) and aren't stripped or
+        // rewritten by downstream HTML transforms.
+        order: "pre",
+        handler() {
+          const nonceValue = resolveNonce(nonce);
+          const nonceAttr = nonceValue ? { nonce: nonceValue } : {};
+          if (mode === "inline") {
+            if (!iifeCode)
+              throw new Error("[unhead] Streaming IIFE not built. Run `pnpm build` in packages/unhead first.");
+            return [{
+              tag: "script",
+              attrs: nonceAttr,
+              children: iifeCode,
+              injectTo: "head-prepend"
+            }];
+          }
+          if (mode === "async") {
+            const src = state.isBuild && state.emittedIifeFileName ? `/${state.emittedIifeFileName}` : `/${VIRTUAL_IIFE_ID}`;
+            return [{
+              tag: "script",
+              attrs: { ...nonceAttr, async: true, src },
+              injectTo: "head-prepend"
+            }];
+          }
+          return [{
+            tag: "script",
+            attrs: nonceAttr,
+            children: `import("/${VIRTUAL_CLIENT_ID}")`,
+            injectTo: "head-prepend"
+          }];
+        }
+      }
+    }
+  };
+}
+const createStreamingPlugin = createUnplugin(buildStreamingPluginOptions);
+
+export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, buildStreamingPluginOptions, createStreamingPlugin };

package/dist/stream/vite.d.mts

@@ -1,31 +1,23 @@
 import { Plugin } from 'vite';
+import { StreamingPluginOptions } from './unplugin.mjs';
+export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, buildStreamingPluginOptions } from './unplugin.mjs';
+import 'unplugin';
 
-declare const VIRTUAL_CLIENT_ID = "virtual:@unhead/streaming-client";
-declare const VIRTUAL_IIFE_ID = "virtual:@unhead/streaming-iife.js";
-interface StreamingPluginOptions {
-    /** Framework package e.g. '@unhead/vue' */
-    framework: string;
-    /** Plugin name (optional, defaults to `${framework}:streaming`) */
-    name?: string;
-    /** File extension filter for transform hook, e.g. /\.vue$/ */
-    filter: RegExp;
-    /** Transform handler called for files matching `filter` */
-    transform: (code: string, id: string, options?: {
-        ssr?: boolean;
-    }) => {
-        code: string;
-        map?: any;
-    } | null | undefined | void;
-    /**
-     * How to load the streaming client:
-     * - 'async': Load as async script (non-blocking, may have brief queue delay)
-     * - 'inline': Inline the IIFE directly in HTML (larger HTML, but immediate execution)
-     * - 'module': Use ES module import (original behavior, waits for bundle)
-     * @default 'async'
-     */
-    mode?: 'async' | 'inline' | 'module';
-}
+/**
+ * @deprecated Import from `unhead/stream/unplugin` instead and call `.vite(options)`
+ * on the returned unplugin instance. The `unhead/stream/vite` subpath will be
+ * removed in a future major release.
+ *
+ * ```ts
+ * // Before
+ * import { createStreamingPlugin } from 'unhead/stream/vite'
+ * const plugin = createStreamingPlugin({ framework, filter, transform })
+ *
+ * // After
+ * import { createStreamingPlugin } from 'unhead/stream/unplugin'
+ * const plugin = createStreamingPlugin.vite({ framework, filter, transform })
+ * ```
+ */
 declare function createStreamingPlugin(options: StreamingPluginOptions): Plugin;
 
-export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, createStreamingPlugin };
-export type { StreamingPluginOptions };
+export { StreamingPluginOptions, createStreamingPlugin };

package/dist/stream/vite.d.ts

@@ -1,31 +1,23 @@
 import { Plugin } from 'vite';
+import { StreamingPluginOptions } from './unplugin.js';
+export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, buildStreamingPluginOptions } from './unplugin.js';
+import 'unplugin';
 
-declare const VIRTUAL_CLIENT_ID = "virtual:@unhead/streaming-client";
-declare const VIRTUAL_IIFE_ID = "virtual:@unhead/streaming-iife.js";
-interface StreamingPluginOptions {
-    /** Framework package e.g. '@unhead/vue' */
-    framework: string;
-    /** Plugin name (optional, defaults to `${framework}:streaming`) */
-    name?: string;
-    /** File extension filter for transform hook, e.g. /\.vue$/ */
-    filter: RegExp;
-    /** Transform handler called for files matching `filter` */
-    transform: (code: string, id: string, options?: {
-        ssr?: boolean;
-    }) => {
-        code: string;
-        map?: any;
-    } | null | undefined | void;
-    /**
-     * How to load the streaming client:
-     * - 'async': Load as async script (non-blocking, may have brief queue delay)
-     * - 'inline': Inline the IIFE directly in HTML (larger HTML, but immediate execution)
-     * - 'module': Use ES module import (original behavior, waits for bundle)
-     * @default 'async'
-     */
-    mode?: 'async' | 'inline' | 'module';
-}
+/**
+ * @deprecated Import from `unhead/stream/unplugin` instead and call `.vite(options)`
+ * on the returned unplugin instance. The `unhead/stream/vite` subpath will be
+ * removed in a future major release.
+ *
+ * ```ts
+ * // Before
+ * import { createStreamingPlugin } from 'unhead/stream/vite'
+ * const plugin = createStreamingPlugin({ framework, filter, transform })
+ *
+ * // After
+ * import { createStreamingPlugin } from 'unhead/stream/unplugin'
+ * const plugin = createStreamingPlugin.vite({ framework, filter, transform })
+ * ```
+ */
 declare function createStreamingPlugin(options: StreamingPluginOptions): Plugin;
 
-export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, createStreamingPlugin };
-export type { StreamingPluginOptions };
+export { StreamingPluginOptions, createStreamingPlugin };

package/dist/stream/vite.mjs

@@ -1,81 +1,9 @@
-const VIRTUAL_CLIENT_ID = "virtual:@unhead/streaming-client";
-const VIRTUAL_IIFE_ID = "virtual:@unhead/streaming-iife.js";
-const RESOLVED_ID = `\0${VIRTUAL_CLIENT_ID}`;
-const RESOLVED_IIFE_ID = `\0${VIRTUAL_IIFE_ID}`;
-const VIRTUAL_RE = /virtual:@unhead\/streaming/;
-const RESOLVED_RE = /^\0virtual:@unhead\/streaming/;
-let iifeCode;
-let iifeCodeLoaded = false;
+import { createStreamingPlugin as createStreamingPlugin$1 } from './unplugin.mjs';
+export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, buildStreamingPluginOptions } from './unplugin.mjs';
+import 'unplugin';
+
 function createStreamingPlugin(options) {
-  const { framework, name, mode = "async" } = options;
-  return {
-    name: name ?? `${framework}:streaming`,
-    enforce: "pre",
-    async configResolved() {
-      if (!iifeCodeLoaded) {
-        iifeCodeLoaded = true;
-        const mod = await import('unhead/stream/iife');
-        iifeCode = mod.streamingIifeCode;
-      }
-    },
-    resolveId: {
-      filter: { id: VIRTUAL_RE },
-      handler(id) {
-        if (id === VIRTUAL_CLIENT_ID || id === `/${VIRTUAL_CLIENT_ID}`)
-          return RESOLVED_ID;
-        if (id === VIRTUAL_IIFE_ID || id === `/${VIRTUAL_IIFE_ID}`)
-          return RESOLVED_IIFE_ID;
-      }
-    },
-    load: {
-      filter: { id: RESOLVED_RE },
-      handler(id, opts) {
-        if (id === RESOLVED_ID) {
-          if (opts?.ssr)
-            return { code: "export {}", moduleType: "js" };
-          return {
-            code: `import{createHead}from'${framework}/client'
-const s=window.__unhead__;if(s){const q=s._q;s._q=[];const h=createHead({document});q.forEach(e=>h.push(e));s.push=e=>h.push(e);s._head=h}`,
-            moduleType: "js"
-          };
-        }
-        if (id === RESOLVED_IIFE_ID) {
-          if (opts?.ssr)
-            return { code: "", moduleType: "js" };
-          if (!iifeCode)
-            throw new Error("[unhead] Streaming IIFE not built. Run `pnpm build` in packages/unhead first.");
-          return { code: iifeCode, moduleType: "js" };
-        }
-      }
-    },
-    transformIndexHtml() {
-      if (mode === "inline") {
-        if (!iifeCode)
-          throw new Error("[unhead] Streaming IIFE not built. Run `pnpm build` in packages/unhead first.");
-        return [{
-          tag: "script",
-          children: iifeCode,
-          injectTo: "head-prepend"
-        }];
-      }
-      if (mode === "async") {
-        return [{
-          tag: "script",
-          attrs: { async: true, src: `/${VIRTUAL_IIFE_ID}` },
-          injectTo: "head-prepend"
-        }];
-      }
-      return [{
-        tag: "script",
-        children: `import("/${VIRTUAL_CLIENT_ID}")`,
-        injectTo: "head-prepend"
-      }];
-    },
-    transform: {
-      filter: { id: options.filter },
-      handler: options.transform
-    }
-  };
+  return createStreamingPlugin$1.vite(options);
 }
 
-export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, createStreamingPlugin };
+export { createStreamingPlugin };