feat(core): dynamic modulepreload

Author: wmertens

Diff for: packages/docs/src/entry.ssr.tsx

@@ -5,6 +5,14 @@ import Root from './root';
 export default function (opts: RenderToStreamOptions) {
   return renderToStream(<Root />, {
     manifest,
+    // TODO make this the default
+    prefetchStrategy: {
+      implementation: {
+        linkInsert: 'html-append',
+        linkRel: 'modulepreload',
+        prefetchEvent: null,
+      },
+    },
     qwikLoader: {
       // The docs can be long so make sure to intercept events before the end of the document.
       position: 'top',

Diff for: packages/docs/src/root.tsx

@@ -1,11 +1,11 @@
 import { component$, useContextProvider, useStore } from '@builder.io/qwik';
-import { QwikCityProvider, RouterOutlet, ServiceWorkerRegister } from '@builder.io/qwik-city';
+import { QwikCityProvider, RouterOutlet } from '@builder.io/qwik-city';
+import { Insights } from '@builder.io/qwik-labs';
 import RealMetricsOptimization from './components/real-metrics-optimization/real-metrics-optimization';
 import { RouterHead } from './components/router-head/router-head';
+import { BUILDER_PUBLIC_API_KEY } from './constants';
 import { GlobalStore, type SiteStore } from './context';
 import './global.css';
-import { BUILDER_PUBLIC_API_KEY } from './constants';
-import { Insights } from '@builder.io/qwik-labs';
 
 export const uwu = /*javascript*/ `
 ;(function () {
@@ -55,7 +55,6 @@ export default component$(() => {
         <meta charset="utf-8" />
         <script dangerouslySetInnerHTML={uwu} />
         <RouterHead />
-        <ServiceWorkerRegister />
 
         <script dangerouslySetInnerHTML={`(${collectSymbols})()`} />
         <Insights publicApiKey={import.meta.env.PUBLIC_QWIK_INSIGHTS_KEY} />

Diff for: packages/docs/src/routes/api/qwik-server/api.json

@@ -82,7 +82,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "```typescript\nexport interface PrefetchImplementation \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[linkFetchPriority?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n'auto' \\| 'low' \\| 'high' \\| null\n\n\n</td><td>\n\n_(Optional)_ Value of the `<link fetchpriority=\"...\">` attribute when link is used. Defaults to `null` if links are inserted.\n\n\n</td></tr>\n<tr><td>\n\n[linkInsert?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n'js-append' \\| 'html-append' \\| null\n\n\n</td><td>\n\n_(Optional)_ `js-append`<!-- -->: Use JS runtime to create each `<link>` and append to the body.\n\n`html-append`<!-- -->: Render each `<link>` within html, appended at the end of the body.\n\n\n</td></tr>\n<tr><td>\n\n[linkRel?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n'prefetch' \\| 'preload' \\| 'modulepreload' \\| null\n\n\n</td><td>\n\n_(Optional)_ Value of the `<link rel=\"...\">` attribute when link is used. Defaults to `prefetch` if links are inserted.\n\n\n</td></tr>\n<tr><td>\n\n[prefetchEvent?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n'always' \\| null\n\n\n</td><td>\n\n_(Optional)_ Dispatch a `qprefetch` event with detail data containing the bundles that should be prefetched. The event dispatch script will be inlined into the document's HTML so any listeners of this event should already be ready to handle the event.\n\nThis implementation will inject a script similar to:\n\n```\n<script type=\"module\">\n  document.dispatchEvent(new CustomEvent(\"qprefetch\", { detail:{ \"bundles\": [...] } }))\n</script>\n```\nBy default, the `prefetchEvent` implementation will be set to `always`<!-- -->.\n\n\n</td></tr>\n<tr><td>\n\n[workerFetchInsert?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n'always' \\| 'no-link-support' \\| null\n\n\n</td><td>\n\n_(Optional)_ `always`<!-- -->: Always include the worker fetch JS runtime.\n\n`no-link-support`<!-- -->: Only include the worker fetch JS runtime when the browser doesn't support `<link>` prefetch/preload/modulepreload.\n\n\n</td></tr>\n</tbody></table>",
+      "content": "```typescript\nexport interface PrefetchImplementation \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[linkFetchPriority?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n'auto' \\| 'low' \\| 'high' \\| null\n\n\n</td><td>\n\n_(Optional)_ Value of the `<link fetchpriority=\"...\">` attribute when link is used. Defaults to `null`<!-- -->.\n\n\n</td></tr>\n<tr><td>\n\n[linkInsert?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n'js-append' \\| 'html-append' \\| null\n\n\n</td><td>\n\n_(Optional)_ `js-append`<!-- -->: Use JS runtime to create each `<link>` and append to the body.\n\n`html-append`<!-- -->: Render each `<link>` within html, appended at the end of the body.\n\nDefaults to `html-append`<!-- -->.\n\n\n</td></tr>\n<tr><td>\n\n[linkRel?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n'prefetch' \\| 'preload' \\| 'modulepreload' \\| null\n\n\n</td><td>\n\n_(Optional)_ Value of the `<link rel=\"...\">` attribute when link is used. Defaults to `modulepreload`<!-- -->.\n\n\n</td></tr>\n<tr><td>\n\n[prefetchEvent?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n'always' \\| null\n\n\n</td><td>\n\n_(Optional)_ Dispatch a `qprefetch` event with detail data containing the bundles that should be prefetched. The event dispatch script will be inlined into the document's HTML so any listeners of this event should already be ready to handle the event.\n\nThis implementation will inject a script similar to:\n\n```\n<script type=\"module\">\n  document.dispatchEvent(new CustomEvent(\"qprefetch\", { detail:{ \"bundles\": [...] } }))\n</script>\n```\nBy default, the `prefetchEvent` implementation will be set to `null`<!-- -->.\n\n\n</td></tr>\n<tr><td>\n\n[workerFetchInsert?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n'always' \\| 'no-link-support' \\| null\n\n\n</td><td>\n\n_(Optional)_ `always`<!-- -->: Always include the worker fetch JS runtime.\n\n`no-link-support`<!-- -->: Only include the worker fetch JS runtime when the browser doesn't support `<link>` prefetch/preload/modulepreload.\n\nDefaults to `null`<!-- -->.\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/server/types.ts",
       "mdFile": "qwik.prefetchimplementation.md"
     },
@@ -96,7 +96,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "```typescript\nexport interface PrefetchResource \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[imports](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[PrefetchResource](#prefetchresource)<!-- -->\\[\\]\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[url](#)\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>",
+      "content": "```typescript\nexport interface PrefetchResource \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[imports](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[PrefetchResource](#prefetchresource)<!-- -->\\[\\]\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[priority](#)\n\n\n</td><td>\n\n\n</td><td>\n\nboolean\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[url](#)\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/src/server/types.ts",
       "mdFile": "qwik.prefetchresource.md"
     },

Diff for: packages/docs/src/routes/api/qwik-server/index.md

@@ -243,7 +243,7 @@ Description
 
 </td><td>
 
-_(Optional)_ Value of the `<link fetchpriority="...">` attribute when link is used. Defaults to `null` if links are inserted.
+_(Optional)_ Value of the `<link fetchpriority="...">` attribute when link is used. Defaults to `null`.
 
 </td></tr>
 <tr><td>
@@ -262,6 +262,8 @@ _(Optional)_ `js-append`: Use JS runtime to create each `<link>` and append to t
 
 `html-append`: Render each `<link>` within html, appended at the end of the body.
 
+Defaults to `html-append`.
+
 </td></tr>
 <tr><td>
 
@@ -275,7 +277,7 @@ _(Optional)_ `js-append`: Use JS runtime to create each `<link>` and append to t
 
 </td><td>
 
-_(Optional)_ Value of the `<link rel="...">` attribute when link is used. Defaults to `prefetch` if links are inserted.
+_(Optional)_ Value of the `<link rel="...">` attribute when link is used. Defaults to `modulepreload`.
 
 </td></tr>
 <tr><td>
@@ -300,7 +302,7 @@ This implementation will inject a script similar to:
 </script>
 ```
 
-By default, the `prefetchEvent` implementation will be set to `always`.
+By default, the `prefetchEvent` implementation will be set to `null`.
 
 </td></tr>
 <tr><td>
@@ -319,6 +321,8 @@ _(Optional)_ `always`: Always include the worker fetch JS runtime.
 
 `no-link-support`: Only include the worker fetch JS runtime when the browser doesn't support `<link>` prefetch/preload/modulepreload.
 
+Defaults to `null`.
+
 </td></tr>
 </tbody></table>
 
@@ -362,6 +366,19 @@ Description
 </td></tr>
 <tr><td>
 
+[priority](#)
+
+</td><td>
+
+</td><td>
+
+boolean
+
+</td><td>
+
+</td></tr>
+<tr><td>
+
 [url](#)
 
 </td><td>

Diff for: packages/qwik/src/core/qrl/preload.ts

@@ -0,0 +1,164 @@
+/**
+ * Here we handle preloading of chunks.
+ *
+ * Given a symbol hash (in fact any string), we can find all the chunks that it depends on, via the
+ * bundle graph. We then generate preload link tags for each of those chunks.
+ *
+ * The priority is set to high for direct imports and low for indirect imports.
+ *
+ * There are several parts to this:
+ *
+ * - Load the bundle graph from the preload link tag that was injected during SSR
+ * - Given a string, find all the chunks that it depends on
+ * - Generate the preload link tags if needed
+ */
+
+import { isDev } from '@builder.io/qwik/build';
+import type { QwikBundleGraph } from '../../optimizer/src/types';
+import { QBaseAttr, QManifestHash } from '../util/markers';
+
+import { QContainerSelector } from '../util/markers';
+
+let bundlesP: Promise<void> | undefined;
+enum BundleImportState {
+  None,
+  Low,
+  Loading,
+}
+type BundleImport = {
+  $url$: string | null;
+  $state$: BundleImportState;
+  $imports$: string[];
+  $dynamicImports$: string[];
+};
+let bundles: Map<string, BundleImport> | undefined;
+type WantedBundle = {
+  name: string;
+  priority: boolean;
+};
+const wantedBundles: Set<WantedBundle> = new Set();
+
+const parseBundleGraph = (text: string, base: string) => {
+  try {
+    const graph = JSON.parse(text) as QwikBundleGraph;
+    bundles ||= new Map<string, BundleImport>();
+    let i = 0;
+    while (i < graph.length) {
+      const name = graph[i++] as string;
+      const url = name.endsWith('.js') ? `${base}${name}` : null;
+      const imports: string[] = [];
+      const dynamicImports: string[] = [];
+      let idx: number | string;
+      let collection = imports;
+      while (((idx = graph[i]), typeof idx === 'number')) {
+        if (idx === -1) {
+          collection = dynamicImports;
+        } else {
+          collection.push(graph[idx] as string);
+        }
+        i++;
+      }
+      bundles.set(name, {
+        $url$: url,
+        $state$: BundleImportState.None,
+        $imports$: imports,
+        $dynamicImports$: dynamicImports,
+      });
+    }
+    for (const { name, priority } of wantedBundles) {
+      preload(name, priority);
+    }
+    wantedBundles.clear();
+  } catch (e) {
+    console.error('Error parsing bundle graph', e, text);
+    throw e;
+  }
+};
+
+export const loadBundleGraph = (element: Element) => {
+  if (typeof window === 'undefined' || bundlesP) {
+    return;
+  }
+  const container = element.closest(QContainerSelector);
+  if (!container) {
+    return;
+  }
+  const hash = container.getAttribute(QManifestHash);
+  const base = container.getAttribute(QBaseAttr) || '/';
+  const link = hash && (container.querySelector(`link#qwik-bg-${hash}`) as HTMLLinkElement | null);
+  if (!link) {
+    bundlesP = Promise.reject('No preload link found');
+    // prevent uncaught promise rejection
+    bundlesP.catch(() => {});
+    return;
+  }
+  bundlesP = fetch(link.href)
+    .then((res) => res.text())
+    .then((text) => parseBundleGraph(text, base))
+    .catch((e) => {
+      console.error('Error loading bundle graph, retrying later', e);
+      setTimeout(() => {
+        bundlesP = undefined;
+      }, 60000);
+    });
+};
+
+const makePreloadLink = (bundle: BundleImport, priority: boolean) => {
+  const link = document.createElement('link');
+  link.rel = 'modulepreload';
+  link.href = bundle.$url$!;
+  link.fetchPriority = priority ? 'high' : 'low';
+  link.as = 'script';
+  document.head.appendChild(link);
+};
+
+const prioritizeLink = (url: string) => {
+  const link = document.querySelector(`link[href="${url}"]`) as HTMLLinkElement | null;
+  if (link) {
+    link.fetchPriority = 'high';
+  } else {
+    console.warn(`Preload link ${url} not found`);
+  }
+};
+
+const preloadBundle = (bundle: BundleImport, priority: boolean) => {
+  if (bundle.$state$ >= BundleImportState.Loading) {
+    return;
+  }
+  if (bundle.$url$) {
+    if (bundle.$state$ === BundleImportState.None) {
+      makePreloadLink(bundle, priority);
+    } else if (priority && bundle.$state$ === BundleImportState.Low) {
+      prioritizeLink(bundle.$url$!);
+    } else {
+      return;
+    }
+  }
+  bundle.$state$ = priority ? BundleImportState.Loading : BundleImportState.Low;
+};
+
+export const preload = (name: string, priority: boolean) => {
+  if (!bundles) {
+    wantedBundles.add({ name, priority });
+    return;
+  }
+  const bundle = bundles.get(name);
+  if (!bundle) {
+    isDev && console.warn(`Bundle ${name} not found`);
+    return;
+  }
+  const isReprioritize = priority && bundle.$state$ === BundleImportState.Low;
+  if (bundle.$state$ !== BundleImportState.None && !isReprioritize) {
+    // prevent loops
+    return;
+  }
+  preloadBundle(bundle, priority);
+  for (const importName of bundle.$imports$) {
+    preload(importName, priority);
+  }
+  if (!isReprioritize) {
+    for (const importName of bundle.$dynamicImports$) {
+      preload(importName, false);
+    }
+  }
+};

Diff for: packages/qwik/src/core/qrl/qrl-class.ts

@@ -15,6 +15,7 @@ import { getQFuncs, QInstance } from '../util/markers';
 import { isPromise, maybeThen } from '../util/promises';
 import { qDev, qSerialize, qTest, seal } from '../util/qdev';
 import { isArray, isFunction, type ValueOrPromise } from '../util/types';
+import { loadBundleGraph, preload } from './preload';
 import type { QRLDev } from './qrl';
 import type { QRL, QrlArgs, QrlReturn } from './qrl.public';
 
@@ -89,6 +90,10 @@ export const createQRL = <TYPE>(
     if (!_containerEl) {
       _containerEl = el;
     }
+    // try every time just in case
+    if (el) {
+      loadBundleGraph(el);
+    }
     return _containerEl;
   };
 
@@ -221,6 +226,7 @@ export const createQRL = <TYPE>(
   if (qDev) {
     seal(qrl);
   }
+  preload(hash, true);
   return qrl;
 };
 

Diff for: packages/qwik/src/core/util/markers.ts

@@ -29,7 +29,7 @@ export const getQFuncs = (document: Document, hash: string): Function[] => {
 
 export const QLocaleAttr = 'q:locale';
 export const QContainerAttr = 'q:container';
-
+export const QBaseAttr = 'q:base';
 export const QContainerSelector = '[q\\:container]';
 
 export const ResourceEvent = 'qResource';

Diff for: packages/qwik/src/optimizer/src/plugins/vite.ts

@@ -1136,6 +1136,20 @@ function absolutePathAwareJoin(path: Path, ...segments: string[]): string {
   return path.join(...segments);
 }
 
+const dynamicTag = '<dynamic>';
+/**
+ * This creates a compact array of dependencies for each bundle. It also contains the symbols. The
+ * format is:
+ *
+ * ```
+ *   [...(bundleName: string, ...directImports: index[], ...dynamicImports: [-1, ...index[]] | [])]
+ * ```
+ *
+ * (index is the position of the dependency in the bundleGraph array)
+ *
+ * This format allows any string to denote a set of dependencies, which is useful for symbols and
+ * SPA paths.
+ */
 export function convertManifestToBundleGraph(manifest: QwikManifest): QwikBundleGraph {
   const bundleGraph: QwikBundleGraph = [];
   const graph = manifest.bundles;
@@ -1171,19 +1185,12 @@ export function convertManifestToBundleGraph(manifest: QwikManifest): QwikBundle
       }
       clearTransitiveDeps(deps, new Set(), depName);
     }
-    let didAdd = false;
-    for (const depName of bundle.dynamicImports || []) {
-      // If we dynamically import a qrl segment that is not a handler, we'll probably need it soon
-      const dep = graph[depName];
-      if (!graph[depName]) {
-        // external dependency
-        continue;
-      }
-      if (dep.isTask) {
-        if (!didAdd) {
-          deps.add('<dynamic>');
-          didAdd = true;
-        }
+    const internalDynamicImports = bundle.dynamicImports?.filter((d) => graph[d]) || [];
+    // If we have a lot of dynamic imports, we don't know which ones are needed, so we don't add any
+    // This can happen with registry bundles like for routing
+    if (internalDynamicImports.length > 0 && internalDynamicImports.length < 10) {
+      deps.add(dynamicTag);
+      for (const depName of internalDynamicImports) {
         deps.add(depName);
       }
     }
@@ -1193,6 +1200,17 @@ export function convertManifestToBundleGraph(manifest: QwikManifest): QwikBundle
       bundleGraph.push(null!);
     }
   }
+  // Add the symbols to the bundle graph
+  for (const [symbol, chunkname] of Object.entries(manifest.mapping)) {
+    const bundle = map.get(chunkname);
+    if (!bundle) {
+      console.warn(`Chunk ${chunkname} for symbol ${symbol} not found in the bundle graph.`);
+    } else {
+      const idx = symbol.lastIndexOf('_');
+      const hash = idx === -1 ? symbol : symbol.slice(idx + 1);
+      bundleGraph.push(hash, bundle.index);
+    }
+  }
   // Second pass to to update dependency pointers
   for (const bundleName of names) {
     const bundle = map.get(bundleName);
@@ -1204,7 +1222,7 @@ export function convertManifestToBundleGraph(manifest: QwikManifest): QwikBundle
     let { index, deps } = bundle;
     index++;
     for (const depName of deps) {
-      if (depName === '<dynamic>') {
+      if (depName === dynamicTag) {
         bundleGraph[index++] = -1;
         continue;
       }