@unhead/react 3.0.0-beta.9 → 3.0.0-rc.4

package/dist/client.d.mts

@@ -1,14 +1,15 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import * as unhead_types from 'unhead/types';
-import { CreateClientHeadOptions, Unhead } from 'unhead/types';
+import { Unhead, CreateClientHeadOptions } 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>;
+    head?: Unhead<any, any>;
 }): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead, unknown> | null>>;
 
 export { UnheadProvider, createHead };

package/dist/client.d.ts

@@ -1,14 +1,15 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import * as unhead_types from 'unhead/types';
-import { CreateClientHeadOptions, Unhead } from 'unhead/types';
+import { Unhead, CreateClientHeadOptions } 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>;
+    head?: Unhead<any, any>;
 }): react.FunctionComponentElement<react.ProviderProps<Unhead<unhead_types.ResolvableHead, unknown> | null>>;
 
 export { UnheadProvider, createHead };

package/dist/helmet.d.mts

@@ -0,0 +1,73 @@
+import react__default, { ReactNode } from 'react';
+
+interface HelmetProps {
+    children?: ReactNode;
+    /**
+     * A default title to use when no `<title>` child is provided.
+     *
+     * Equivalent to react-helmet's `defaultTitle`.
+     */
+    defaultTitle?: string;
+    /**
+     * A template for the title. Use `%s` as a placeholder for the page title.
+     *
+     * @example `%s | My Site`
+     */
+    titleTemplate?: string;
+    /**
+     * Called after the document head has been updated in the browser.
+     *
+     * Equivalent to react-helmet's `onChangeClientState`.
+     *
+     * @param newState - The new head state after rendering.
+     * @param addedTags - Always empty — unhead manages DOM diffing internally.
+     * @param removedTags - Always empty — unhead manages DOM diffing internally.
+     */
+    onChangeClientState?: (newState: Record<string, any>, addedTags: Record<string, HTMLElement[]>, removedTags: Record<string, HTMLElement[]>) => void;
+    /**
+     * Whether to encode special characters in attributes.
+     *
+     * @default true
+     * @deprecated Unhead handles encoding automatically. This prop is accepted for compatibility but has no effect.
+     */
+    encodeSpecialCharacters?: boolean;
+    /**
+     * Whether to defer DOM updates until the browser is idle.
+     *
+     * @default true
+     * @deprecated Unhead batches DOM updates automatically. This prop is accepted for compatibility but has no effect.
+     */
+    defer?: boolean;
+    title?: string;
+    base?: Record<string, any>;
+    meta?: Array<Record<string, any>>;
+    link?: Array<Record<string, any>>;
+    script?: Array<Record<string, any>>;
+    style?: Array<Record<string, any>>;
+    noscript?: Array<Record<string, any>>;
+    htmlAttributes?: Record<string, any>;
+    bodyAttributes?: Record<string, any>;
+}
+/**
+ * A react-helmet compatible component powered by unhead.
+ *
+ * Drop-in replacement for `<Helmet>` — import from `@unhead/react/helmet` instead of `react-helmet`.
+ *
+ * @example
+ * ```tsx
+ * import { Helmet } from '@unhead/react/helmet'
+ *
+ * <Helmet
+ *   defaultTitle="My Site"
+ *   titleTemplate="%s | My Site"
+ *   onChangeClientState={(newState) => console.log(newState)}
+ * >
+ *   <title>Page Title</title>
+ *   <meta name="description" content="Page description" />
+ * </Helmet>
+ * ```
+ */
+declare const Helmet: react__default.FC<HelmetProps>;
+
+export { Helmet };
+export type { HelmetProps };

package/dist/helmet.d.ts

@@ -0,0 +1,73 @@
+import react__default, { ReactNode } from 'react';
+
+interface HelmetProps {
+    children?: ReactNode;
+    /**
+     * A default title to use when no `<title>` child is provided.
+     *
+     * Equivalent to react-helmet's `defaultTitle`.
+     */
+    defaultTitle?: string;
+    /**
+     * A template for the title. Use `%s` as a placeholder for the page title.
+     *
+     * @example `%s | My Site`
+     */
+    titleTemplate?: string;
+    /**
+     * Called after the document head has been updated in the browser.
+     *
+     * Equivalent to react-helmet's `onChangeClientState`.
+     *
+     * @param newState - The new head state after rendering.
+     * @param addedTags - Always empty — unhead manages DOM diffing internally.
+     * @param removedTags - Always empty — unhead manages DOM diffing internally.
+     */
+    onChangeClientState?: (newState: Record<string, any>, addedTags: Record<string, HTMLElement[]>, removedTags: Record<string, HTMLElement[]>) => void;
+    /**
+     * Whether to encode special characters in attributes.
+     *
+     * @default true
+     * @deprecated Unhead handles encoding automatically. This prop is accepted for compatibility but has no effect.
+     */
+    encodeSpecialCharacters?: boolean;
+    /**
+     * Whether to defer DOM updates until the browser is idle.
+     *
+     * @default true
+     * @deprecated Unhead batches DOM updates automatically. This prop is accepted for compatibility but has no effect.
+     */
+    defer?: boolean;
+    title?: string;
+    base?: Record<string, any>;
+    meta?: Array<Record<string, any>>;
+    link?: Array<Record<string, any>>;
+    script?: Array<Record<string, any>>;
+    style?: Array<Record<string, any>>;
+    noscript?: Array<Record<string, any>>;
+    htmlAttributes?: Record<string, any>;
+    bodyAttributes?: Record<string, any>;
+}
+/**
+ * A react-helmet compatible component powered by unhead.
+ *
+ * Drop-in replacement for `<Helmet>` — import from `@unhead/react/helmet` instead of `react-helmet`.
+ *
+ * @example
+ * ```tsx
+ * import { Helmet } from '@unhead/react/helmet'
+ *
+ * <Helmet
+ *   defaultTitle="My Site"
+ *   titleTemplate="%s | My Site"
+ *   onChangeClientState={(newState) => console.log(newState)}
+ * >
+ *   <title>Page Title</title>
+ *   <meta name="description" content="Page description" />
+ * </Helmet>
+ * ```
+ */
+declare const Helmet: react__default.FC<HelmetProps>;
+
+export { Helmet };
+export type { HelmetProps };

package/dist/helmet.mjs

@@ -0,0 +1,152 @@
+import React, { useMemo, useCallback, useRef, useEffect, useContext } from 'react';
+import { createDomRenderer, createDebouncedFn, createHead } from 'unhead/client';
+import { ValidHeadTags, TagsWithInnerContent, HasElementTags } from 'unhead/utils';
+import { U as UnheadContext } from './shared/react.DF9T1fqs.mjs';
+
+let _singletonHead = null;
+function useHelmetHead() {
+  const ctx = useContext(UnheadContext);
+  if (ctx) {
+    return ctx;
+  }
+  if (!_singletonHead) {
+    if (typeof window === "undefined") {
+      throw new TypeError("Helmet requires UnheadProvider on the server. Wrap your app with <UnheadProvider>.");
+    }
+    const domRenderer = createDomRenderer();
+    let head;
+    const debouncedRenderer = createDebouncedFn(() => domRenderer(head), (fn) => setTimeout(fn, 0));
+    head = createHead({ render: debouncedRenderer });
+    _singletonHead = head;
+  }
+  return _singletonHead;
+}
+const Helmet = ({
+  children,
+  defaultTitle,
+  titleTemplate,
+  onChangeClientState,
+  title: titleProp,
+  base: baseProp,
+  meta: metaProp,
+  link: linkProp,
+  script: scriptProp,
+  style: styleProp,
+  noscript: noscriptProp,
+  htmlAttributes,
+  bodyAttributes,
+  // accepted for compat, intentionally unused
+  encodeSpecialCharacters: _encodeSpecialCharacters,
+  defer: _defer
+}) => {
+  const head = useHelmetHead();
+  const processedElements = useMemo(() => React.Children.toArray(children).filter(React.isValidElement), [children]);
+  const getHeadChanges = useCallback(() => {
+    const input = {};
+    if (titleTemplate) {
+      input.titleTemplate = titleTemplate;
+    }
+    if (titleProp != null) {
+      input.title = titleProp;
+    }
+    if (baseProp) {
+      input.base = baseProp;
+    }
+    if (metaProp) {
+      input.meta = [...metaProp];
+    }
+    if (linkProp) {
+      input.link = [...linkProp];
+    }
+    if (scriptProp) {
+      input.script = [...scriptProp];
+    }
+    if (styleProp) {
+      input.style = [...styleProp];
+    }
+    if (noscriptProp) {
+      input.noscript = [...noscriptProp];
+    }
+    if (htmlAttributes) {
+      input.htmlAttrs = htmlAttributes;
+    }
+    if (bodyAttributes) {
+      input.bodyAttrs = bodyAttributes;
+    }
+    let hasTitle = !!titleProp;
+    for (const element of processedElements) {
+      const reactElement = element;
+      const { type, props } = reactElement;
+      let tagName = String(type);
+      if (tagName === "html")
+        tagName = "htmlAttrs";
+      else if (tagName === "body")
+        tagName = "bodyAttrs";
+      if (!ValidHeadTags.has(tagName)) {
+        continue;
+      }
+      const data = { ...typeof props === "object" ? props : {} };
+      if (TagsWithInnerContent.has(tagName) && data.children != null) {
+        const contentKey = tagName === "script" ? "innerHTML" : "textContent";
+        data[contentKey] = Array.isArray(data.children) ? data.children.map(String).join("") : String(data.children);
+      }
+      delete data.children;
+      if (tagName === "title") {
+        hasTitle = true;
+      }
+      if (HasElementTags.has(tagName)) {
+        const key = tagName;
+        if (!Array.isArray(input[key])) {
+          input[key] = [];
+        }
+        input[key].push(data);
+      } else {
+        input[tagName] = data;
+      }
+    }
+    if (!hasTitle && defaultTitle) {
+      input.title = defaultTitle;
+    }
+    if (defaultTitle) {
+      input.templateParams = {
+        ...input.templateParams,
+        defaultTitle
+      };
+    }
+    return input;
+  }, [processedElements, titleTemplate, defaultTitle, titleProp, baseProp, metaProp, linkProp, scriptProp, styleProp, noscriptProp, htmlAttributes, bodyAttributes]);
+  const headRef = useRef(null);
+  const onChangeClientStateRef = useRef(onChangeClientState);
+  onChangeClientStateRef.current = onChangeClientState;
+  if (head.ssr && !headRef.current) {
+    headRef.current = head.push(getHeadChanges());
+  }
+  useEffect(() => {
+    const options = {
+      onRendered: () => {
+        const cb = onChangeClientStateRef.current;
+        if (!cb)
+          return;
+        const titleEl = document.querySelector("title");
+        const state = {
+          title: titleEl?.textContent || ""
+        };
+        for (const tag of ["meta", "link", "script", "style", "base"]) {
+          state[`${tag}Tags`] = Array.from(document.querySelectorAll(`head ${tag}`));
+        }
+        cb(state, {}, {});
+      }
+    };
+    headRef.current = head.push(getHeadChanges(), options);
+    return () => {
+      headRef.current?.dispose();
+      headRef.current = null;
+    };
+  }, [head]);
+  useEffect(() => {
+    headRef.current?.patch(getHeadChanges());
+  }, [getHeadChanges]);
+  return null;
+};
+
+export { Helmet };

package/dist/index.mjs

@@ -20,25 +20,25 @@ function useUnhead() {
   return instance;
 }
 function withSideEffects(input, options, fn) {
-  const unhead = options.head || useUnhead();
+  const head = options.head || useUnhead();
   const entryRef = useRef(null);
   const inputRef = useRef(input);
   inputRef.current = input;
-  if (unhead.ssr && !entryRef.current) {
-    entryRef.current = fn(unhead, input, options);
+  if (head.ssr && !entryRef.current) {
+    entryRef.current = fn(head, input, options);
   }
   useEffect(() => {
-    const entry = fn(unhead, inputRef.current, options);
+    const entry = fn(head, inputRef.current, options);
     entryRef.current = entry;
     return () => {
       entry.dispose();
       entryRef.current = null;
     };
-  }, [unhead]);
+  }, [head]);
   useEffect(() => {
     entryRef.current?.patch(input);
   }, [input]);
-  if (unhead.ssr) {
+  if (head.ssr) {
     return entryRef.current;
   }
   const proxyRef = useRef(null);

package/dist/stream/server.d.mts

@@ -2,7 +2,7 @@ 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';
+import { ResolvableHead, Unhead } from 'unhead/types';
 
 declare function UnheadProvider({ value, children }: {
     value: Unhead;

package/dist/stream/server.d.ts

@@ -2,7 +2,7 @@ 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';
+import { ResolvableHead, Unhead } from 'unhead/types';
 
 declare function UnheadProvider({ value, children }: {
     value: Unhead;

package/dist/stream/server.mjs

@@ -1,5 +1,5 @@
 import { PassThrough } from 'node:stream';
-import { createElement, useContext } from 'react';
+import { useContext, createElement } 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';

package/dist/stream/vite.mjs

@@ -2,6 +2,7 @@ import MagicString from 'magic-string';
 import { parseAndWalk } from 'oxc-walker';
 import { createStreamingPlugin } from 'unhead/stream/vite';
 
+const FILTER_RE = /\.[jt]sx$/;
 function transform(code, id, isSSR, s) {
   const lang = id.endsWith(".tsx") ? "tsx" : id.endsWith(".jsx") ? "jsx" : "tsx";
   const returns = [];
@@ -84,7 +85,7 @@ import { HeadStream } from '${importPath}'`);
 function unheadReactPlugin(options) {
   return createStreamingPlugin({
     framework: "@unhead/react",
-    filter: /\.[jt]sx$/,
+    filter: FILTER_RE,
     mode: options?.mode,
     transform(code, id, opts) {
       const s = new MagicString(code);

package/dist/vite.d.mts

@@ -0,0 +1,33 @@
+import { VitePluginOptions } from '@unhead/bundler/vite';
+import { StreamingPluginOptions } from 'unhead/stream/vite';
+import { Plugin } from 'vite';
+
+interface UnheadReactViteOptions extends VitePluginOptions {
+    /**
+     * Enable streaming SSR support.
+     * Set to `true` or a config object to enable.
+     * @default false
+     */
+    streaming?: true | Pick<StreamingPluginOptions, 'mode'> | false;
+}
+/**
+ * Unified Vite plugin for `@unhead/react`.
+ *
+ * Combines build optimizations (tree-shaking, useSeoMeta transform, minification)
+ * with streaming SSR support into a single plugin.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import react from '@vitejs/plugin-react'
+ * import { Unhead } from '@unhead/react/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [react(), Unhead()],
+ * })
+ * ```
+ */
+declare function Unhead(options?: UnheadReactViteOptions): Plugin[];
+
+export { Unhead };
+export type { UnheadReactViteOptions };

package/dist/vite.d.ts

@@ -0,0 +1,33 @@
+import { VitePluginOptions } from '@unhead/bundler/vite';
+import { StreamingPluginOptions } from 'unhead/stream/vite';
+import { Plugin } from 'vite';
+
+interface UnheadReactViteOptions extends VitePluginOptions {
+    /**
+     * Enable streaming SSR support.
+     * Set to `true` or a config object to enable.
+     * @default false
+     */
+    streaming?: true | Pick<StreamingPluginOptions, 'mode'> | false;
+}
+/**
+ * Unified Vite plugin for `@unhead/react`.
+ *
+ * Combines build optimizations (tree-shaking, useSeoMeta transform, minification)
+ * with streaming SSR support into a single plugin.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import react from '@vitejs/plugin-react'
+ * import { Unhead } from '@unhead/react/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [react(), Unhead()],
+ * })
+ * ```
+ */
+declare function Unhead(options?: UnheadReactViteOptions): Plugin[];
+
+export { Unhead };
+export type { UnheadReactViteOptions };

package/dist/vite.mjs

@@ -0,0 +1,16 @@
+import { Unhead as Unhead$1 } from '@unhead/bundler/vite';
+import unheadReactPlugin from './stream/vite.mjs';
+import 'magic-string';
+import 'oxc-walker';
+import 'unhead/stream/vite';
+
+function Unhead(options = {}) {
+  const plugins = [...Unhead$1({ ...options, _framework: "@unhead/react" })];
+  if (options.streaming) {
+    const streamingOpts = typeof options.streaming === "object" ? options.streaming : void 0;
+    plugins.push(unheadReactPlugin(streamingOpts));
+  }
+  return plugins;
+}
+
+export { Unhead };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unhead/react",
   "type": "module",
-  "version": "3.0.0-beta.9",
+  "version": "3.0.0-rc.4",
   "description": "Full-stack <head> manager built for React.",
   "author": "Harlan Wilton <harlan@harlanzw.com>",
   "license": "MIT",
@@ -45,9 +45,17 @@
       "types": "./dist/plugins.d.ts",
       "default": "./dist/plugins.mjs"
     },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.mjs"
+    },
     "./stream/vite": {
       "types": "./dist/stream/vite.d.ts",
       "default": "./dist/stream/vite.mjs"
+    },
+    "./helmet": {
+      "types": "./dist/helmet.d.ts",
+      "default": "./dist/helmet.mjs"
     }
   },
   "main": "dist/index.mjs",
@@ -73,8 +81,14 @@
       "utils": [
         "dist/utils"
       ],
+      "vite": [
+        "dist/vite"
+      ],
       "stream/vite": [
         "dist/stream/vite"
+      ],
+      "helmet": [
+        "dist/helmet"
       ]
     }
   },
@@ -83,8 +97,8 @@
     "dist"
   ],
   "peerDependencies": {
-    "react": ">=18.3.1",
-    "vite": ">=6"
+    "react": ">=19.2.4",
+    "vite": ">=6.4.2"
   },
   "peerDependenciesMeta": {
     "vite": {
@@ -98,17 +112,18 @@
   },
   "dependencies": {
     "magic-string": "^0.30.21",
-    "oxc-parser": "^0.106.0",
+    "oxc-parser": "^0.124.0",
     "oxc-walker": "^0.7.0",
-    "unhead": "3.0.0-beta.9"
+    "@unhead/bundler": "3.0.0-rc.4",
+    "unhead": "3.0.0-rc.4"
   },
   "devDependencies": {
-    "@testing-library/react": "^16.3.1",
-    "@types/react": "^19.2.8",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
-    "vite": "^7.2.2"
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "vite": "^8.0.8"
   },
   "scripts": {
     "build": "unbuild",