@unhead/react 3.0.0-beta.1 → 3.0.0-beta.11

package/dist/client.d.mts

@@ -3,12 +3,13 @@ import { ReactNode } from 'react';
 import * as unhead_types from 'unhead/types';
 import { CreateClientHeadOptions, Unhead } from 'unhead/types';
 export { CreateClientHeadOptions, Unhead } from 'unhead/types';
+import { ClientUnhead } from 'unhead/client';
 export { renderDOMHead } from 'unhead/client';
 
-declare function createHead(options?: CreateClientHeadOptions): Unhead;
+declare function createHead(options?: CreateClientHeadOptions): ClientUnhead;
 declare function UnheadProvider({ children, head }: {
     children: ReactNode;
-    head?: ReturnType<typeof createHead>;
-}): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead> | null>>;
+    head?: Unhead<any, any>;
+}): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead, unknown> | null>>;
 
 export { UnheadProvider, createHead };

package/dist/client.d.ts

@@ -3,12 +3,13 @@ import { ReactNode } from 'react';
 import * as unhead_types from 'unhead/types';
 import { CreateClientHeadOptions, Unhead } from 'unhead/types';
 export { CreateClientHeadOptions, Unhead } from 'unhead/types';
+import { ClientUnhead } from 'unhead/client';
 export { renderDOMHead } from 'unhead/client';
 
-declare function createHead(options?: CreateClientHeadOptions): Unhead;
+declare function createHead(options?: CreateClientHeadOptions): ClientUnhead;
 declare function UnheadProvider({ children, head }: {
     children: ReactNode;
-    head?: ReturnType<typeof createHead>;
-}): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead> | null>>;
+    head?: Unhead<any, any>;
+}): 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/index.mjs

@@ -22,20 +22,41 @@ function useUnhead() {
 function withSideEffects(input, options, fn) {
   const unhead = options.head || useUnhead();
   const entryRef = useRef(null);
-  if (!entryRef.current) {
+  const inputRef = useRef(input);
+  inputRef.current = input;
+  if (unhead.ssr && !entryRef.current) {
     entryRef.current = fn(unhead, input, options);
   }
-  const entry = entryRef.current;
-  useEffect(() => {
-    entry?.patch(input);
-  }, [input, entry]);
   useEffect(() => {
+    const entry = fn(unhead, inputRef.current, options);
+    entryRef.current = entry;
     return () => {
-      entry?.dispose();
+      entry.dispose();
       entryRef.current = null;
     };
-  }, [entry]);
-  return entry;
+  }, [unhead]);
+  useEffect(() => {
+    entryRef.current?.patch(input);
+  }, [input]);
+  if (unhead.ssr) {
+    return entryRef.current;
+  }
+  const proxyRef = useRef(null);
+  if (!proxyRef.current) {
+    proxyRef.current = {
+      patch: (newInput) => {
+        entryRef.current?.patch(newInput);
+      },
+      dispose: () => {
+        entryRef.current?.dispose();
+        entryRef.current = null;
+      },
+      _poll: (rm) => {
+        entryRef.current?._poll(rm);
+      }
+    };
+  }
+  return proxyRef.current;
 }
 function useHead(input = {}, options = {}) {
   return withSideEffects(input, options, useHead$1);

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,101 @@
+import MagicString from 'magic-string';
+import { parseAndWalk } from 'oxc-walker';
+import { createStreamingPlugin } from 'unhead/stream/vite';
+
+function transform(code, id, isSSR, s) {
+  const lang = id.endsWith(".tsx") ? "tsx" : id.endsWith(".jsx") ? "jsx" : "tsx";
+  const returns = [];
+  let currentFnHasHead = false;
+  const fnStack = [];
+  const importPath = isSSR ? "@unhead/react/stream/server" : "@unhead/react/stream/client";
+  let existingImport = null;
+  let lastImportEnd = -1;
+  const result = parseAndWalk(code, id, {
+    parseOptions: { lang },
+    enter(node) {
+      if (node.type === "ImportDeclaration") {
+        if (node.source.value === importPath) {
+          existingImport = {
+            start: node.start,
+            end: node.end,
+            specifiers: node.specifiers?.map((spec) => spec.local?.name).filter(Boolean) || []
+          };
+        }
+        if (node.end > lastImportEnd)
+          lastImportEnd = node.end;
+        this.skip();
+        return;
+      }
+      const isFn = node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression";
+      if (isFn) {
+        fnStack.push(currentFnHasHead);
+        if (!node.body) {
+          currentFnHasHead = false;
+          return;
+        }
+        const bodyCode = code.slice(node.body.start, node.body.end);
+        currentFnHasHead = bodyCode.includes("useHead") || bodyCode.includes("useSeoMeta") || bodyCode.includes("useHeadSafe");
+        if (currentFnHasHead && (node.body.type === "JSXElement" || node.body.type === "JSXFragment")) {
+          returns.push({ jsxStart: node.body.start, jsxEnd: node.body.end });
+        }
+        return;
+      }
+      if (currentFnHasHead && node.type === "ReturnStatement") {
+        if (!node.argument)
+          return;
+        let arg = node.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 });
+      }
+    },
+    leave(node) {
+      const isFn = node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression";
+      if (isFn) {
+        currentFnHasHead = fnStack.pop();
+      }
+    }
+  });
+  if (result.errors.length > 0)
+    return false;
+  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 foundImport = existingImport;
+  if (foundImport) {
+    if (!foundImport.specifiers.includes("HeadStream")) {
+      const inner = foundImport.specifiers.join(", ");
+      s.overwrite(foundImport.start, foundImport.end, `import { ${inner ? `${inner}, ` : ""}HeadStream } from '${importPath}'`);
+    }
+  } else if (lastImportEnd > -1) {
+    s.appendLeft(lastImportEnd, `
+import { HeadStream } from '${importPath}'`);
+  } else {
+    s.prepend(`import { HeadStream } from '${importPath}'
+`);
+  }
+  return true;
+}
+function unheadReactPlugin(options) {
+  return createStreamingPlugin({
+    framework: "@unhead/react",
+    filter: /\.[jt]sx$/,
+    mode: options?.mode,
+    transform(code, id, opts) {
+      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.1",
+  "version": "3.0.0-beta.11",
   "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.1"
+    "magic-string": "^0.30.21",
+    "oxc-parser": "^0.106.0",
+    "oxc-walker": "^0.7.0",
+    "unhead": "3.0.0-beta.11"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.1",
-    "@types/react": "^19.2.7",
+    "@types/react": "^19.2.8",
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.3",
-    "react-dom": "^19.2.3"
+    "react-dom": "^19.2.3",
+    "vite": "^7.3.1"
   },
   "scripts": {
     "build": "unbuild",