@unhead/react 3.0.0-beta.4 → 3.0.0-beta.5

package/dist/client.d.mts

@@ -9,6 +9,6 @@ declare function createHead(options?: CreateClientHeadOptions): Unhead;
 declare function UnheadProvider({ children, head }: {
     children: ReactNode;
     head?: ReturnType<typeof createHead>;
-}): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead> | null>>;
+}): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead, unknown> | null>>;
 
 export { UnheadProvider, createHead };

package/dist/client.d.ts

@@ -9,6 +9,6 @@ declare function createHead(options?: CreateClientHeadOptions): Unhead;
 declare function UnheadProvider({ children, head }: {
     children: ReactNode;
     head?: ReturnType<typeof createHead>;
-}): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead> | null>>;
+}): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead, unknown> | null>>;
 
 export { UnheadProvider, createHead };

package/dist/client.mjs

@@ -1,15 +1,13 @@
 import { createElement } from 'react';
-import { createHead as createHead$1, createDebouncedFn, renderDOMHead } from 'unhead/client';
+import { createDomRenderer, createDebouncedFn, createHead as createHead$1 } from 'unhead/client';
 export { renderDOMHead } from 'unhead/client';
 import { U as UnheadContext } from './shared/react.DF9T1fqs.mjs';
 
 function createHead(options = {}) {
-  const head = createHead$1({
-    domOptions: {
-      render: createDebouncedFn(() => renderDOMHead(head), (fn) => setTimeout(fn, 0))
-    },
-    ...options
-  });
+  const domRenderer = createDomRenderer();
+  let head;
+  const debouncedRenderer = createDebouncedFn(() => domRenderer(head), (fn) => setTimeout(fn, 0));
+  head = createHead$1({ render: debouncedRenderer, ...options });
   return head;
 }
 function UnheadProvider({ children, head }) {

package/dist/server.d.mts

@@ -3,11 +3,11 @@ import { ReactNode } from 'react';
 import * as unhead_types from 'unhead/types';
 import { Unhead } from 'unhead/types';
 export { CreateServerHeadOptions, SSRHeadPayload, Unhead } from 'unhead/types';
-export { createHead, extractUnheadInputFromHtml, renderSSRHead, transformHtmlTemplate } from 'unhead/server';
+export { createHead, renderSSRHead, transformHtmlTemplate } from 'unhead/server';
 
 declare function UnheadProvider({ children, value }: {
     children: ReactNode;
     value: Unhead;
-}): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead> | null>>;
+}): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead, unknown> | null>>;
 
 export { UnheadProvider };

package/dist/server.d.ts

@@ -3,11 +3,11 @@ import { ReactNode } from 'react';
 import * as unhead_types from 'unhead/types';
 import { Unhead } from 'unhead/types';
 export { CreateServerHeadOptions, SSRHeadPayload, Unhead } from 'unhead/types';
-export { createHead, extractUnheadInputFromHtml, renderSSRHead, transformHtmlTemplate } from 'unhead/server';
+export { createHead, renderSSRHead, transformHtmlTemplate } from 'unhead/server';
 
 declare function UnheadProvider({ children, value }: {
     children: ReactNode;
     value: Unhead;
-}): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead> | null>>;
+}): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead, unknown> | null>>;
 
 export { UnheadProvider };

package/dist/server.mjs

@@ -1,6 +1,6 @@
 import { createElement } from 'react';
 import { U as UnheadContext } from './shared/react.DF9T1fqs.mjs';
-export { createHead, extractUnheadInputFromHtml, renderSSRHead, transformHtmlTemplate } from 'unhead/server';
+export { createHead, renderSSRHead, transformHtmlTemplate } from 'unhead/server';
 
 function UnheadProvider({ children, value }) {
   return createElement(UnheadContext.Provider, { value }, children);

package/dist/stream/client.d.mts

@@ -0,0 +1,15 @@
+import { ReactNode } from 'react';
+import { Unhead } from 'unhead/types';
+export { CreateStreamableClientHeadOptions, UnheadStreamQueue, createStreamableHead } from 'unhead/stream/client';
+
+declare function UnheadProvider({ value, children }: {
+    value: Unhead;
+    children: ReactNode;
+}): ReactNode;
+/**
+ * Client-side HeadStream - renders empty script with suppressHydrationWarning
+ * to match server-side structure without hydration mismatch errors.
+ */
+declare function HeadStream(): ReactNode;
+
+export { HeadStream, UnheadProvider };

package/dist/stream/client.d.ts

@@ -0,0 +1,15 @@
+import { ReactNode } from 'react';
+import { Unhead } from 'unhead/types';
+export { CreateStreamableClientHeadOptions, UnheadStreamQueue, createStreamableHead } from 'unhead/stream/client';
+
+declare function UnheadProvider({ value, children }: {
+    value: Unhead;
+    children: ReactNode;
+}): ReactNode;
+/**
+ * Client-side HeadStream - renders empty script with suppressHydrationWarning
+ * to match server-side structure without hydration mismatch errors.
+ */
+declare function HeadStream(): ReactNode;
+
+export { HeadStream, UnheadProvider };

package/dist/stream/client.mjs

@@ -0,0 +1,12 @@
+import { createElement } from 'react';
+import { U as UnheadContext } from '../shared/react.DF9T1fqs.mjs';
+export { createStreamableHead } from 'unhead/stream/client';
+
+function UnheadProvider({ value, children }) {
+  return createElement(UnheadContext.Provider, { value }, children);
+}
+function HeadStream() {
+  return createElement("script", { suppressHydrationWarning: true });
+}
+
+export { HeadStream, UnheadProvider };

package/dist/stream/server.d.mts

@@ -0,0 +1,56 @@
+import { Writable } from 'node:stream';
+import { ReactNode } from 'react';
+import { StreamableHeadContext, CreateStreamableServerHeadOptions } from 'unhead/stream/server';
+export { BaseStreamableHeadContext, CreateStreamableServerHeadOptions, StreamableHeadContext, StreamingTemplateParts, WebStreamableHeadContext, prepareStreamingTemplate, renderSSRHeadShell, renderSSRHeadSuspenseChunk, wrapStream } from 'unhead/stream/server';
+import { Unhead, ResolvableHead } from 'unhead/types';
+
+declare function UnheadProvider({ value, children }: {
+    value: Unhead;
+    children: ReactNode;
+}): ReactNode;
+/**
+ * Streaming head component for React.
+ * Place inside Suspense boundaries after async components that use useHead.
+ */
+declare function HeadStream(): ReactNode;
+/**
+ * A pipe function from React's renderToPipeableStream
+ */
+type ReactPipeFunction = (writable: Writable) => void;
+/**
+ * React-specific context returned by createStreamableHead.
+ * Extends core StreamableHeadContext with React's wrap helper.
+ */
+interface ReactStreamableHeadContext<T = ResolvableHead> extends Pick<StreamableHeadContext<T>, 'head' | 'onShellReady'> {
+    /**
+     * Wrap React's pipe function to handle head injection automatically
+     * @param pipe - The pipe function from renderToPipeableStream
+     * @param template - The HTML template (from Vite's transformIndexHtml)
+     * @returns A new pipe function that handles shell rendering
+     */
+    wrap: (pipe: ReactPipeFunction, template: string) => (writable: Writable) => void;
+}
+/**
+ * Creates a head instance configured for React streaming SSR.
+ *
+ * Returns a context with:
+ * - `head`: The Unhead instance for UnheadProvider
+ * - `onShellReady`: Callback to pass to renderToPipeableStream
+ * - `wrap`: Wraps React's pipe to handle head injection
+ *
+ * @example
+ * ```tsx
+ * const { head, onShellReady, wrap } = createStreamableHead()
+ *
+ * const { pipe } = renderToPipeableStream(
+ *   <UnheadProvider value={head}><App /></UnheadProvider>,
+ *   { onShellReady }
+ * )
+ *
+ * return { pipe: wrap(pipe, template) }
+ * ```
+ */
+declare function createStreamableHead<T = ResolvableHead>(options?: CreateStreamableServerHeadOptions): ReactStreamableHeadContext<T>;
+
+export { HeadStream, UnheadProvider, createStreamableHead };
+export type { ReactStreamableHeadContext };

package/dist/stream/server.d.ts

@@ -0,0 +1,56 @@
+import { Writable } from 'node:stream';
+import { ReactNode } from 'react';
+import { StreamableHeadContext, CreateStreamableServerHeadOptions } from 'unhead/stream/server';
+export { BaseStreamableHeadContext, CreateStreamableServerHeadOptions, StreamableHeadContext, StreamingTemplateParts, WebStreamableHeadContext, prepareStreamingTemplate, renderSSRHeadShell, renderSSRHeadSuspenseChunk, wrapStream } from 'unhead/stream/server';
+import { Unhead, ResolvableHead } from 'unhead/types';
+
+declare function UnheadProvider({ value, children }: {
+    value: Unhead;
+    children: ReactNode;
+}): ReactNode;
+/**
+ * Streaming head component for React.
+ * Place inside Suspense boundaries after async components that use useHead.
+ */
+declare function HeadStream(): ReactNode;
+/**
+ * A pipe function from React's renderToPipeableStream
+ */
+type ReactPipeFunction = (writable: Writable) => void;
+/**
+ * React-specific context returned by createStreamableHead.
+ * Extends core StreamableHeadContext with React's wrap helper.
+ */
+interface ReactStreamableHeadContext<T = ResolvableHead> extends Pick<StreamableHeadContext<T>, 'head' | 'onShellReady'> {
+    /**
+     * Wrap React's pipe function to handle head injection automatically
+     * @param pipe - The pipe function from renderToPipeableStream
+     * @param template - The HTML template (from Vite's transformIndexHtml)
+     * @returns A new pipe function that handles shell rendering
+     */
+    wrap: (pipe: ReactPipeFunction, template: string) => (writable: Writable) => void;
+}
+/**
+ * Creates a head instance configured for React streaming SSR.
+ *
+ * Returns a context with:
+ * - `head`: The Unhead instance for UnheadProvider
+ * - `onShellReady`: Callback to pass to renderToPipeableStream
+ * - `wrap`: Wraps React's pipe to handle head injection
+ *
+ * @example
+ * ```tsx
+ * const { head, onShellReady, wrap } = createStreamableHead()
+ *
+ * const { pipe } = renderToPipeableStream(
+ *   <UnheadProvider value={head}><App /></UnheadProvider>,
+ *   { onShellReady }
+ * )
+ *
+ * return { pipe: wrap(pipe, template) }
+ * ```
+ */
+declare function createStreamableHead<T = ResolvableHead>(options?: CreateStreamableServerHeadOptions): ReactStreamableHeadContext<T>;
+
+export { HeadStream, UnheadProvider, createStreamableHead };
+export type { ReactStreamableHeadContext };

package/dist/stream/server.mjs

@@ -0,0 +1,51 @@
+import { PassThrough } from 'node:stream';
+import { createElement, useContext } from 'react';
+import { renderSSRHeadSuspenseChunk, createStreamableHead as createStreamableHead$1, prepareStreamingTemplate } from 'unhead/stream/server';
+export { prepareStreamingTemplate, renderSSRHeadShell, renderSSRHeadSuspenseChunk, wrapStream } from 'unhead/stream/server';
+import { U as UnheadContext } from '../shared/react.DF9T1fqs.mjs';
+
+function UnheadProvider({ value, children }) {
+  return createElement(UnheadContext.Provider, { value }, children);
+}
+function HeadStream() {
+  const head = useContext(UnheadContext);
+  if (!head) {
+    throw new Error("HeadStream: head context not found");
+  }
+  const update = renderSSRHeadSuspenseChunk(head);
+  return createElement("script", {
+    suppressHydrationWarning: true,
+    dangerouslySetInnerHTML: update ? { __html: update } : void 0
+  });
+}
+function createStreamableHead(options = {}) {
+  const { head, onShellReady, shellReady } = createStreamableHead$1(options);
+  return {
+    head,
+    onShellReady,
+    wrap: (pipe, template) => {
+      return (writable) => {
+        shellReady.then(async () => {
+          try {
+            const { shell, end } = await prepareStreamingTemplate(head, template);
+            writable.write(shell);
+            const passthrough = new PassThrough();
+            passthrough.on("data", (chunk) => writable.write(chunk));
+            passthrough.on("end", () => {
+              writable.write(end);
+              writable.end();
+            });
+            passthrough.on("error", (err) => {
+              writable.destroy(err);
+            });
+            pipe(passthrough);
+          } catch (err) {
+            writable.destroy(err instanceof Error ? err : new Error(String(err)));
+          }
+        });
+      };
+    }
+  };
+}
+
+export { HeadStream, UnheadProvider, createStreamableHead };

package/dist/stream/vite.d.mts

@@ -0,0 +1,27 @@
+import * as vite from 'vite';
+import { StreamingPluginOptions } from 'unhead/stream/vite';
+
+/**
+ * Vite plugin for React streaming SSR support.
+ * Automatically injects HeadStream components into React components that use useHead hooks.
+ *
+ * @returns Vite plugin configuration object with:
+ *   - `name`: Plugin identifier
+ *   - `enforce`: Plugin execution order ('pre')
+ *   - `transform`: Transform hook for processing JSX/TSX files
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { unheadReactPlugin } from '@unhead/react/stream/vite'
+ *
+ * export default {
+ *   plugins: [
+ *     unheadReactPlugin()
+ *   ]
+ * }
+ * ```
+ */
+declare function unheadReactPlugin(options?: Pick<StreamingPluginOptions, 'mode'>): vite.Plugin<any>;
+
+export { unheadReactPlugin as default, unheadReactPlugin };

package/dist/stream/vite.d.ts

@@ -0,0 +1,27 @@
+import * as vite from 'vite';
+import { StreamingPluginOptions } from 'unhead/stream/vite';
+
+/**
+ * Vite plugin for React streaming SSR support.
+ * Automatically injects HeadStream components into React components that use useHead hooks.
+ *
+ * @returns Vite plugin configuration object with:
+ *   - `name`: Plugin identifier
+ *   - `enforce`: Plugin execution order ('pre')
+ *   - `transform`: Transform hook for processing JSX/TSX files
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { unheadReactPlugin } from '@unhead/react/stream/vite'
+ *
+ * export default {
+ *   plugins: [
+ *     unheadReactPlugin()
+ *   ]
+ * }
+ * ```
+ */
+declare function unheadReactPlugin(options?: Pick<StreamingPluginOptions, 'mode'>): vite.Plugin<any>;
+
+export { unheadReactPlugin as default, unheadReactPlugin };

package/dist/stream/vite.mjs

@@ -0,0 +1,86 @@
+import MagicString from 'magic-string';
+import { findStaticImports } from 'mlly';
+import { parseSync, Visitor } from 'oxc-parser';
+import { createStreamingPlugin } from 'unhead/stream/vite';
+
+function transform(code, id, isSSR, s) {
+  const lang = id.endsWith(".tsx") ? "tsx" : id.endsWith(".jsx") ? "jsx" : "tsx";
+  const result = parseSync(id, code, { lang });
+  if (result.errors.length > 0)
+    return false;
+  const returns = [];
+  const visitor = new Visitor({
+    FunctionDeclaration: (node) => processFunction(node),
+    FunctionExpression: (node) => processFunction(node),
+    ArrowFunctionExpression: (node) => processFunction(node)
+  });
+  function processFunction(node) {
+    if (!node.body)
+      return;
+    const bodyCode = code.slice(node.body.start, node.body.end);
+    if (!bodyCode.includes("useHead") && !bodyCode.includes("useSeoMeta") && !bodyCode.includes("useHeadSafe"))
+      return;
+    if (node.body.type === "JSXElement" || node.body.type === "JSXFragment") {
+      returns.push({ jsxStart: node.body.start, jsxEnd: node.body.end });
+      return;
+    }
+    const innerVisitor = new Visitor({
+      ReturnStatement(innerNode) {
+        if (!innerNode.argument)
+          return;
+        let arg = innerNode.argument;
+        if (arg.type === "ParenthesizedExpression" && arg.expression)
+          arg = arg.expression;
+        if (arg.type === "JSXElement" || arg.type === "JSXFragment")
+          returns.push({ jsxStart: arg.start, jsxEnd: arg.end });
+      }
+    });
+    innerVisitor.visit(node.body);
+  }
+  visitor.visit(result.program);
+  if (returns.length === 0)
+    return false;
+  returns.sort((a, b) => b.jsxStart - a.jsxStart);
+  for (const ret of returns) {
+    const jsxCode = code.slice(ret.jsxStart, ret.jsxEnd);
+    s.overwrite(ret.jsxStart, ret.jsxEnd, `<><HeadStream />${jsxCode}</>`);
+  }
+  const importPath = isSSR ? "@unhead/react/stream/server" : "@unhead/react/stream/client";
+  const imports = findStaticImports(code);
+  const existing = imports.find((i) => i.specifier === importPath);
+  if (existing) {
+    if (!existing.imports?.includes("HeadStream")) {
+      const inner = existing.imports?.replace(/^\{\s*|\s*\}\s*$/g, "").trim() || "";
+      s.overwrite(existing.start, existing.end, `import { ${inner ? `${inner}, ` : ""}HeadStream } from '${importPath}'
+`);
+    }
+  } else {
+    const last = imports[imports.length - 1];
+    if (last)
+      s.appendLeft(last.end, `import { HeadStream } from '${importPath}'
+`);
+    else
+      s.prepend(`import { HeadStream } from '${importPath}'
+`);
+  }
+  return true;
+}
+function unheadReactPlugin(options) {
+  return createStreamingPlugin({
+    framework: "@unhead/react",
+    mode: options?.mode,
+    transform(code, id, opts) {
+      if (!/\.[jt]sx$/.test(id))
+        return null;
+      const s = new MagicString(code);
+      if (!transform(code, id, opts?.ssr ?? false, s))
+        return null;
+      return {
+        code: s.toString(),
+        map: s.generateMap({ includeContent: true, source: id })
+      };
+    }
+  });
+}
+
+export { unheadReactPlugin as default, unheadReactPlugin };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unhead/react",
   "type": "module",
-  "version": "3.0.0-beta.4",
+  "version": "3.0.0-beta.5",
   "description": "Full-stack <head> manager built for React.",
   "author": "Harlan Wilton <harlan@harlanzw.com>",
   "license": "MIT",
@@ -29,6 +29,14 @@
       "types": "./dist/client.d.ts",
       "default": "./dist/client.mjs"
     },
+    "./stream/server": {
+      "types": "./dist/stream/server.d.ts",
+      "default": "./dist/stream/server.mjs"
+    },
+    "./stream/client": {
+      "types": "./dist/stream/client.d.ts",
+      "default": "./dist/stream/client.mjs"
+    },
     "./utils": {
       "types": "./dist/utils.d.ts",
       "default": "./dist/utils.mjs"
@@ -36,6 +44,10 @@
     "./plugins": {
       "types": "./dist/plugins.d.ts",
       "default": "./dist/plugins.mjs"
+    },
+    "./stream/vite": {
+      "types": "./dist/stream/vite.d.ts",
+      "default": "./dist/stream/vite.mjs"
     }
   },
   "main": "dist/index.mjs",
@@ -49,11 +61,20 @@
       "client": [
         "dist/client"
       ],
+      "stream/server": [
+        "dist/stream/server"
+      ],
+      "stream/client": [
+        "dist/stream/client"
+      ],
       "plugins": [
         "dist/plugins"
       ],
       "utils": [
         "dist/utils"
+      ],
+      "stream/vite": [
+        "dist/stream/vite"
       ]
     }
   },
@@ -62,7 +83,13 @@
     "dist"
   ],
   "peerDependencies": {
-    "react": ">=18.3.1"
+    "react": ">=18.3.1",
+    "vite": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
   },
   "build": {
     "external": [
@@ -70,14 +97,18 @@
     ]
   },
   "dependencies": {
-    "unhead": "3.0.0-beta.4"
+    "magic-string": "^0.30.21",
+    "mlly": "^1.8.0",
+    "oxc-parser": "^0.106.0",
+    "unhead": "3.0.0-beta.5"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.1",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.3",
-    "react-dom": "^19.2.3"
+    "react-dom": "^19.2.3",
+    "vite": "7.2.2"
   },
   "scripts": {
     "build": "unbuild",