feat(ssr): pass additional documentHead via serverData

Author: wmertens

.changeset/quiet-friends-taste.md

@@ -0,0 +1,6 @@
+---
+'@qwik.dev/router': minor
+'@qwik.dev/core': minor
+---
+
+feat: You can now pass `documentHead` into the `renderToStream()` and `renderToString()` functions as part of the `serverData` option. This is useful for passing title, meta tags, scripts, etc. to the `useDocumentHead()` hook from within the server.

packages/docs/src/routes/api/qwik-server/api.json

@@ -166,7 +166,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "```typescript\nexport interface RenderOptions extends SerializeDocumentOptions \n```\n**Extends:** [SerializeDocumentOptions](#serializedocumentoptions)\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[base?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nstring \\| ((options: [RenderOptions](#renderoptions)<!-- -->) =&gt; string)\n\n\n</td><td>\n\n_(Optional)_ Specifies the root of the JS files of the client build. Setting a base, will cause the render of the `q:base` attribute in the `q:container` element.\n\n\n</td></tr>\n<tr><td>\n\n[containerAttributes?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nRecord&lt;string, string&gt;\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[containerTagName?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nstring\n\n\n</td><td>\n\n_(Optional)_ When set, the app is serialized into a fragment. And the returned html is not a complete document. Defaults to `html`\n\n\n</td></tr>\n<tr><td>\n\n[locale?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nstring \\| ((options: [RenderOptions](#renderoptions)<!-- -->) =&gt; string)\n\n\n</td><td>\n\n_(Optional)_ Language to use when rendering the document.\n\n\n</td></tr>\n<tr><td>\n\n[prefetchStrategy?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[PrefetchStrategy](#prefetchstrategy) \\| null\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[preloader?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[PreloaderOptions](#preloaderoptions) \\| false\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[qwikLoader?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[QwikLoaderOptions](#qwikloaderoptions)\n\n\n</td><td>\n\n_(Optional)_ Specifies if the Qwik Loader script is added to the document or not.\n\nDefaults to `{ include: true }`<!-- -->.\n\n\n</td></tr>\n<tr><td>\n\n[serverData?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nRecord&lt;string, any&gt;\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[snapshot?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nboolean\n\n\n</td><td>\n\n_(Optional)_ Defaults to `true`\n\n\n</td></tr>\n</tbody></table>",
+      "content": "```typescript\nexport interface RenderOptions extends SerializeDocumentOptions \n```\n**Extends:** [SerializeDocumentOptions](#serializedocumentoptions)\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[base?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nstring \\| ((options: [RenderOptions](#renderoptions)<!-- -->) =&gt; string)\n\n\n</td><td>\n\n_(Optional)_ Specifies the root of the JS files of the client build. Setting a base, will cause the render of the `q:base` attribute in the `q:container` element.\n\n\n</td></tr>\n<tr><td>\n\n[containerAttributes?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nRecord&lt;string, string&gt;\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[containerTagName?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nstring\n\n\n</td><td>\n\n_(Optional)_ When set, the app is serialized into a fragment. And the returned html is not a complete document. Defaults to `html`\n\n\n</td></tr>\n<tr><td>\n\n[locale?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nstring \\| ((options: [RenderOptions](#renderoptions)<!-- -->) =&gt; string)\n\n\n</td><td>\n\n_(Optional)_ Language to use when rendering the document.\n\n\n</td></tr>\n<tr><td>\n\n[prefetchStrategy?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[PrefetchStrategy](#prefetchstrategy) \\| null\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[preloader?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[PreloaderOptions](#preloaderoptions) \\| false\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[qwikLoader?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[QwikLoaderOptions](#qwikloaderoptions)\n\n\n</td><td>\n\n_(Optional)_ Specifies if the Qwik Loader script is added to the document or not.\n\nDefaults to `{ include: true }`<!-- -->.\n\n\n</td></tr>\n<tr><td>\n\n[serverData?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nRecord&lt;string, any&gt; &amp; { documentHead?: import('@qwik.dev/router').DocumentHeadValue; }\n\n\n</td><td>\n\n_(Optional)_ Metadata that can be retrieved during SSR with `useServerData()`<!-- -->.\n\n\n</td></tr>\n<tr><td>\n\n[snapshot?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nboolean\n\n\n</td><td>\n\n_(Optional)_ Defaults to `true`\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/server/types.ts",
       "mdFile": "core.renderoptions.md"
     },
@@ -381,4 +381,4 @@
       "mdFile": "core.versions.md"
     }
   ]
-}
+}

packages/docs/src/routes/api/qwik-server/index.mdx

@@ -749,11 +749,11 @@ Defaults to `{ include: true }`.
 
 </td><td>
 
-Record&lt;string, any&gt;
+Record&lt;string, any&gt; &amp; \{ documentHead?: import('@qwik.dev/router').DocumentHeadValue; }
 
 </td><td>
 
-_(Optional)_
+_(Optional)_ Metadata that can be retrieved during SSR with `useServerData()`.
 
 </td></tr>
 <tr><td>

packages/docs/src/routes/docs/(qwikrouter)/pages/index.mdx

@@ -121,6 +121,32 @@ export const head: DocumentHead = ({resolveValue, params}) => {
 };
 ```
 
+### Server-injected Head
+
+You can also pass `documentHead` into the `renderToStream()` and `renderToString()` functions as part of the `serverData` option.
+
+The values passed will be used as the default values for the document head and are overridden by the `head` exports.
+
+```tsx title="src/entry.ssr.tsx" {10}
+import {
+  renderToStream,
+  type RenderToStreamOptions,
+} from "@qwik.dev/core/server";
+import Root from "./root";
+
+export default function (opts: RenderToStreamOptions) {
+  return renderToStream(<Root />, {
+    ...opts,
+    serverData: {
+      ...opts.serverData,
+      documentHead: {
+        title: "My App",
+      },
+    },
+  });
+}
+```
+
 ### Nested Layouts and Head
 
 In an advanced case, a [layout](/docs/(qwikrouter)/layout/index.mdx) may want to modify the document title of an already resolved document head. In the example below, the page component returns the title of `Foo`. The containing layout component can read the value of the page's document head and modify it. In this example, the layout component is adding `MyCompany - ` to the title, so that when rendered, the title will be `MyCompany - Foo`. Every layout in the stack has the opportunity to return a new value.

packages/qwik-router/src/runtime/src/head.ts

@@ -18,9 +18,10 @@ export const resolveHead = (
   endpoint: EndpointResponse | ClientPageData,
   routeLocation: RouteLocation,
   contentModules: ContentModule[],
-  locale: string
+  locale: string,
+  fromServer?: DocumentHeadValue
 ) => {
-  const head = createDocumentHead();
+  const head = createDocumentHead(fromServer);
   const getData = ((loaderOrAction: LoaderInternal | ActionInternal) => {
     const id = loaderOrAction.__id;
     if (loaderOrAction.__brand === 'server_loader') {
@@ -92,11 +93,12 @@ const mergeArray = (
   }
 };
 
-export const createDocumentHead = (): ResolvedDocumentHead => ({
+export const createDocumentHead = (fromServer?: DocumentHeadValue): ResolvedDocumentHead => ({
   title: '',
   meta: [],
   links: [],
   styles: [],
   scripts: [],
   frontmatter: {},
+  ...fromServer,
 });

packages/qwik-router/src/runtime/src/qwik-router-component.tsx

@@ -55,6 +55,7 @@ import type {
   ContentModule,
   ContentState,
   ContentStateInternal,
+  DocumentHeadValue,
   Editable,
   EndpointResponse,
   LoadedRoute,
@@ -150,6 +151,7 @@ export const QwikRouterProvider = component$<QwikRouterProps>((props) => {
   if (!urlEnv) {
     throw new Error(`Missing Qwik URL Env Data`);
   }
+  const serverHead = useServerData<DocumentHeadValue>('documentHead');
 
   if (isServer) {
     if (
@@ -217,7 +219,9 @@ export const QwikRouterProvider = component$<QwikRouterProps>((props) => {
     replaceState: false,
     scroll: true,
   });
-  const documentHead = useStore<Editable<ResolvedDocumentHead>>(createDocumentHead);
+  const documentHead = useStore<Editable<ResolvedDocumentHead>>(() =>
+    createDocumentHead(serverHead)
+  );
   const content = useStore<Editable<ContentState>>({
     headings: undefined,
     menu: undefined,
@@ -487,7 +491,13 @@ export const QwikRouterProvider = component$<QwikRouterProps>((props) => {
         (routeInternal as any).untrackedValue = { type: navType, dest: trackUrl };
 
         // Needs to be done after routeLocation is updated
-        const resolvedHead = resolveHead(clientPageData!, routeLocation, contentModules, locale);
+        const resolvedHead = resolveHead(
+          clientPageData!,
+          routeLocation,
+          contentModules,
+          locale,
+          serverHead
+        );
 
         // Update content
         content.headings = pageModule.headings;

packages/qwik/src/server/qwik.server.api.md

@@ -4,6 +4,7 @@
 
 ```ts
 
+import { DocumentHeadValue } from '@qwik.dev/router';
 import type { QwikManifest } from '@qwik.dev/core/optimizer';
 import type { ResolvedManifest } from '@qwik.dev/core/optimizer';
 import type { ServerQwikManifest } from '@qwik.dev/core/optimizer';
@@ -103,8 +104,9 @@ export interface RenderOptions extends SerializeDocumentOptions {
     // (undocumented)
     preloader?: PreloaderOptions | false;
     qwikLoader?: QwikLoaderOptions;
-    // (undocumented)
-    serverData?: Record<string, any>;
+    serverData?: Record<string, any> & {
+        documentHead?: DocumentHeadValue;
+    };
     snapshot?: boolean;
 }
 

packages/qwik/src/server/types.ts

@@ -168,7 +168,11 @@ export interface RenderOptions extends SerializeDocumentOptions {
    */
   containerTagName?: string;
   containerAttributes?: Record<string, string>;
-  serverData?: Record<string, any>;
+  /** Metadata that can be retrieved during SSR with `useServerData()`. */
+  serverData?: Record<string, any> & {
+    // note that this is leaking Qwik Router into Qwik but it's just types
+    documentHead?: import('@qwik.dev/router').DocumentHeadValue;
+  };
 }
 
 /** @public */

starters/apps/base/src/entry.ssr.tsx

@@ -22,6 +22,10 @@ export default function (opts: RenderToStreamOptions) {
     },
     serverData: {
       ...opts.serverData,
+      // These are the default values for the document head and are overridden by the `head` exports
+      // documentHead: {
+      //   title: "My App",
+      // },
     },
   });
 }

starters/apps/qwikrouter-test/src/entry.ssr.tsx

@@ -8,5 +8,14 @@ export default function (opts: RenderToStreamOptions) {
   return renderToStream(<Root />, {
     base: "/qwikrouter-test/build/",
     ...opts,
+    serverData: {
+      ...opts.serverData,
+      // ensure that documentHead injection works
+      documentHead: {
+        title: "Qwik Router Test",
+        meta: [{ name: "hello", content: "world" }],
+        scripts: [{ key: "hello", script: 'window.hello = "world";' }],
+      },
+    },
   });
 }