feat(router): documentHead via serverData

 the createRenderer type was already updated in the previous commit

Author: wmertens

.changeset/stale-corners-flow.md

@@ -0,0 +1,5 @@
+---
+'@qwik.dev/router': minor
+---
+
+feat: You can now put `documentHead` into the rendering 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/docs/(qwikrouter)/pages/index.mdx

@@ -121,6 +121,31 @@ export const head: DocumentHead = ({resolveValue, params}) => {
 };
 ```
 
+### Server-injected Head
+
+You can also pass `documentHead` to `createRenderer()` as part of the `serverData` option.
+
+The values passed will be used as the default values for `useDocumentHead()`, before the `head` exports are resolved.
+
+```tsx title="src/entry.ssr.tsx" {10}
+import { createRenderer } from "@qwik.dev/router";
+import Root from "./root";
+
+export default createRenderer((opts) => {
+  return {
+    app: <Root />,
+    options: {
+    ...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,
+  defaults?: DocumentHeadValue
 ) => {
-  const head = createDocumentHead();
+  const head = createDocumentHead(defaults);
   const getData = ((loaderOrAction: LoaderInternal | ActionInternal) => {
     const id = loaderOrAction.__id;
     if (loaderOrAction.__brand === 'server_loader') {
@@ -92,11 +93,11 @@ const mergeArray = (
   }
 };
 
-export const createDocumentHead = (): ResolvedDocumentHead => ({
-  title: '',
-  meta: [],
-  links: [],
-  styles: [],
-  scripts: [],
-  frontmatter: {},
+export const createDocumentHead = (defaults?: DocumentHeadValue): ResolvedDocumentHead => ({
+  title: defaults?.title || '',
+  meta: [...(defaults?.meta || [])],
+  links: [...(defaults?.links || [])],
+  styles: [...(defaults?.styles || [])],
+  scripts: [...(defaults?.scripts || [])],
+  frontmatter: { ...defaults?.frontmatter },
 });

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

@@ -40,6 +40,7 @@ export type {
   RouteData,
   RouteLocation,
   RouteNavigate,
+  ServerData,
   StaticGenerate,
   StaticGenerateHandler,
   ValidatorErrorKeyDotNotation,

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;

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

@@ -19,6 +19,13 @@ export default createRenderer((opts) => {
         lang: "en-us",
         ...opts.containerAttributes,
       },
+      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";' }],
+      },
+    },
   });
 }

starters/apps/qwikrouter-test/src/routes/(common)/index.tsx

@@ -1,5 +1,4 @@
 import { component$ } from "@qwik.dev/core";
-import type { DocumentHead } from "@qwik.dev/router";
 // @ts-ignore
 import ImageJpeg from "../../media/MyTest.jpeg?jsx";
 // @ts-ignore
@@ -18,7 +17,3 @@ export default component$(() => {
     </div>
   );
 });
-
-export const head: DocumentHead = {
-  title: "Welcome to Qwik Router",
-};

starters/e2e/qwikrouter/head.e2e.ts

@@ -0,0 +1,12 @@
+import { expect, test } from "@playwright/test";
+
+test.describe("Qwik Router documentHead", () => {
+  test("pass documentHead to Qwik", async ({ page }) => {
+    await page.goto("/qwikrouter-test/");
+    // injected title via renderToStream serverData
+    await expect(page).toHaveTitle("Qwik Router Test - Qwik");
+    const meta = page.locator("meta[name='hello']");
+    await expect(meta).toHaveAttribute("content", "world");
+    expect(await page.evaluate(() => (window as any).hello)).toBe("world");
+  });
+});

starters/e2e/qwikrouter/page.e2e.ts

@@ -27,7 +27,7 @@ function tests() {
     /***********  Home Page  ***********/
     await assertPage(ctx, {
       pathname: "/qwikrouter-test/",
-      title: "Welcome to Qwik Router - Qwik",
+      title: "Qwik Router Test - Qwik",
       layoutHierarchy: ["root"],
       h1: "Welcome to Qwik Router",
       activeHeaderLink: false,