Merge pull request #7770 from QwikDev/documenthead-from-render

feat(ssr): pass additional `documentHead` via `serverData`

Author: wmertens

.changeset/quiet-friends-taste.md

@@ -0,0 +1,5 @@
+---
+'@qwik.dev/router': minor
+---
+
+feat: `createRenderer()` wraps the `renderToStream()` function with Qwik Router types, for nicer `entry.ssr` files.

.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.

e2e/adapters-e2e/src/entry.preview.tsx

@@ -11,7 +11,6 @@
  *
  */
 import { createQwikRouter } from '@qwik.dev/router/middleware/node';
-// make sure qwikCityPlan is imported before entry
 import render from './entry.ssr';
 
 /** The default export is the QwikCity adapter used by Vite preview. */

e2e/adapters-e2e/src/entry.ssr.tsx

@@ -9,25 +9,17 @@
  * - Npm run preview
  * - Npm run build
  */
-import { renderToStream, type RenderToStreamOptions } from '@qwik.dev/core/server';
+import { createRenderer } from '@qwik.dev/router';
 import Root from './root';
 
-export default function (opts: RenderToStreamOptions) {
-  return renderToStream(<Root />, {
+export default createRenderer((opts) => ({
+  jsx: <Root />,
+  options: {
     ...opts,
     // Use container attributes to set attributes on the html tag.
     containerAttributes: {
       lang: 'en-us',
       ...opts.containerAttributes,
     },
-    // prefetchStrategy: {
-    //   implementation: {
-    //     linkInsert: "html-append",
-    //     linkRel: "modulepreload",
-    //   },
-    // },
-    serverData: {
-      ...opts.serverData,
-    },
-  });
-}
+  },
+}));

packages/docs/src/entry.ssr.tsx

@@ -1,5 +1,4 @@
-import type { PreloaderOptions, RenderToStreamOptions } from '@qwik.dev/core/server';
-import { renderToStream } from '@qwik.dev/core/server';
+import { createRenderer } from '@qwik.dev/router';
 import Root from './root';
 
 // You can pass these as query parameters, as well as `preloadDebug`
@@ -10,9 +9,9 @@ const preloaderSettings = [
   'preloadProbability',
 ] as const;
 
-export default function (opts: RenderToStreamOptions) {
+export default createRenderer((opts) => {
   const { serverData } = opts;
-  const urlStr = serverData?.url;
+  const urlStr = serverData.url;
   if (urlStr) {
     const { searchParams } = new URL(urlStr);
     if (searchParams.size) {
@@ -21,7 +20,7 @@ export default function (opts: RenderToStreamOptions) {
         preloader: {
           ...(typeof opts.preloader === 'object' ? opts.preloader : undefined),
         },
-      } as Omit<RenderToStreamOptions, 'preloader'> & { preloader: PreloaderOptions };
+      };
       if (searchParams.has('preloaderDebug')) {
         newOpts.preloader!.debug = true;
       }
@@ -33,11 +32,14 @@ export default function (opts: RenderToStreamOptions) {
       opts = newOpts;
     }
   }
-  return renderToStream(<Root />, {
-    ...opts,
-    containerAttributes: {
-      lang: 'en',
-      ...opts.containerAttributes,
+  return {
+    jsx: <Root />,
+    options: {
+      ...opts,
+      containerAttributes: {
+        lang: 'en',
+        ...opts.containerAttributes,
+      },
     },
-  });
-}
+  };
+});

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

@@ -86,6 +86,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/types.ts",
       "mdFile": "router.contentmenu.md"
     },
+    {
+      "name": "createRenderer",
+      "id": "createrenderer",
+      "hierarchy": [
+        {
+          "name": "createRenderer",
+          "id": "createrenderer"
+        }
+      ],
+      "kind": "Function",
+      "content": "Creates the `render()` function that is required by `createQwikRouter()`<!-- -->. It requires a function that returns the `jsx` and `options` for the renderer.\n\n\n```typescript\ncreateRenderer: (getOptions: (options: RendererOptions) => {\n    jsx: JSXOutput;\n    options: RendererOutputOptions;\n}) => Render\n```\n\n\n<table><thead><tr><th>\n\nParameter\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\ngetOptions\n\n\n</td><td>\n\n(options: [RendererOptions](#rendereroptions)<!-- -->) =&gt; { jsx: JSXOutput; options: [RendererOutputOptions](#rendereroutputoptions)<!-- -->; }\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n**Returns:**\n\nRender\n\n\n\n```tsx\nconst renderer = createRenderer((opts) => {\n  if (opts.requestHeaders['x-hello'] === 'world') {\n    return { jsx: <Hello />, options: opts };\n  }\n  return { jsx: <Root />, options: {\n    ...opts,\n    serverData: {\n      ...opts.serverData,\n      documentHead: {\n        meta: [\n          { name: 'renderedAt', content: new Date().toISOString() },\n        ],\n      },\n    },\n  } };\n});\n```",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/create-renderer.ts",
+      "mdFile": "router.createrenderer.md"
+    },
     {
       "name": "DataValidator",
       "id": "datavalidator",
@@ -506,6 +520,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/types.ts",
       "mdFile": "router.preventnavigatecallback.md"
     },
+    {
+      "name": "Q_ROUTE",
+      "id": "q_route",
+      "hierarchy": [
+        {
+          "name": "Q_ROUTE",
+          "id": "q_route"
+        }
+      ],
+      "kind": "Variable",
+      "content": "```typescript\nQ_ROUTE = \"q:route\"\n```",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/constants.ts",
+      "mdFile": "router.q_route.md"
+    },
     {
       "name": "QWIK_CITY_SCROLLER",
       "id": "qwik_city_scroller",
@@ -618,6 +646,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/types.ts",
       "mdFile": "router.qwikrouterconfig.md"
     },
+    {
+      "name": "QwikRouterEnvData",
+      "id": "qwikrouterenvdata",
+      "hierarchy": [
+        {
+          "name": "QwikRouterEnvData",
+          "id": "qwikrouterenvdata"
+        }
+      ],
+      "kind": "Interface",
+      "content": "```typescript\nexport interface QwikRouterEnvData \n```\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[ev](./router.qwikrouterenvdata.ev.md)\n\n\n</td><td>\n\n\n</td><td>\n\nRequestEvent\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[loadedRoute](./router.qwikrouterenvdata.loadedroute.md)\n\n\n</td><td>\n\n\n</td><td>\n\nLoadedRoute \\| null\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[params](./router.qwikrouterenvdata.params.md)\n\n\n</td><td>\n\n\n</td><td>\n\n[PathParams](#pathparams)\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[response](./router.qwikrouterenvdata.response.md)\n\n\n</td><td>\n\n\n</td><td>\n\nEndpointResponse\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[routeName](./router.qwikrouterenvdata.routename.md)\n\n\n</td><td>\n\n\n</td><td>\n\nstring\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/types.ts",
+      "mdFile": "router.qwikrouterenvdata.md"
+    },
     {
       "name": "QwikRouterMockProps",
       "id": "qwikroutermockprops",
@@ -674,6 +716,34 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/qwik-router-component.tsx",
       "mdFile": "router.qwikrouterprovider.md"
     },
+    {
+      "name": "RendererOptions",
+      "id": "rendereroptions",
+      "hierarchy": [
+        {
+          "name": "RendererOptions",
+          "id": "rendereroptions"
+        }
+      ],
+      "kind": "TypeAlias",
+      "content": "```typescript\nexport type RendererOptions = Omit<RenderOptions, 'serverData'> & {\n    serverData: ServerData;\n};\n```\n**References:** [ServerData](#serverdata)",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/create-renderer.ts",
+      "mdFile": "router.rendereroptions.md"
+    },
+    {
+      "name": "RendererOutputOptions",
+      "id": "rendereroutputoptions",
+      "hierarchy": [
+        {
+          "name": "RendererOutputOptions",
+          "id": "rendereroutputoptions"
+        }
+      ],
+      "kind": "TypeAlias",
+      "content": "```typescript\nexport type RendererOutputOptions = Omit<RenderOptions, 'serverData'> & {\n    serverData: ServerData & {\n        documentHead?: DocumentHeadValue;\n    } & Record<string, unknown>;\n};\n```\n**References:** [ServerData](#serverdata)<!-- -->, [DocumentHeadValue](#documentheadvalue)",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/create-renderer.ts",
+      "mdFile": "router.rendereroutputoptions.md"
+    },
     {
       "name": "ResolvedDocumentHead",
       "id": "resolveddocumenthead",
@@ -786,6 +856,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/server-functions.ts",
       "mdFile": "router.server_.md"
     },
+    {
+      "name": "ServerData",
+      "id": "serverdata",
+      "hierarchy": [
+        {
+          "name": "ServerData",
+          "id": "serverdata"
+        }
+      ],
+      "kind": "TypeAlias",
+      "content": "The server data that is provided by Qwik Router during SSR rendering. It can be retrieved with `useServerData(key)` in the server, but it is not available in the client.\n\n\n```typescript\nexport type ServerData = {\n    url: string;\n    requestHeaders: Record<string, string>;\n    locale: string | undefined;\n    nonce: string | undefined;\n    containerAttributes: Record<string, string> & {\n        [Q_ROUTE]: string;\n    };\n    qwikrouter: QwikRouterEnvData;\n};\n```\n**References:** [Q\\_ROUTE](#q_route)<!-- -->, [QwikRouterEnvData](#qwikrouterenvdata)",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/types.ts",
+      "mdFile": "router.serverdata.md"
+    },
     {
       "name": "ServerFunction",
       "id": "serverfunction",