Merge pull request #7516 from QwikDev/preloader

feat(preloader): more sane configuration

Author: wmertens

.changeset/fair-cars-fry.md

@@ -16,29 +16,35 @@ FEAT: Major improvements to prefetching with automatic bundle preloading
 
 ⚠️ **ATTENTION:**
 
-**Keep** your service worker code as is (either `<ServiceWorkerRegister/>` or `<PrefetchServiceWorker/>`).
+- **Keep** your service worker code as is (either `<ServiceWorkerRegister/>` or `<PrefetchServiceWorker/>`).
+- **Configure** your server to provide long caching headers.
+
+Service Worker:
 
 This new implementation will use it to uninstall the current service worker to reduce the unnecessary duplication.
 
 The builtin service workers components are deprecated but still exist for backwards compatibility.
 
+Caching Headers:
+
+The bundles under build/ are named with their content hash and may therefore be cached indefinitely. Typically you should serve `build/**/*.js` with `Cache-Control: public, max-age=31536000, immutable`.
+
 ---
 
-You can configure the prefetch behavior in your SSR configuration:
+You can configure the preload behavior in your SSR configuration:
 
 ```ts
 // entry.ssr.ts
 export default function (opts: RenderToStreamOptions) {
   return renderToStream(<Root />, {
-    prefetchStrategy: {
-      implementation: {
-        // Enable debug logging for prefetch operations
-        debug: true,
-        // Maximum simultaneous preload links
-        maxSimultaneousPreloads: 5,
-        // Minimum probability threshold for preloading
-        minPreloadProbability: 0.25
-      },
+    preload: {
+      // Enable debug logging for preload operations
+      debug: true,
+      // Maximum simultaneous preload links
+      maxBufferPreloads: 5,
+      // Minimum probability threshold for preloading
+      preloadProbability: 0.25
+      // ...and more, see the type JSDoc on hover
     },
     ...opts,
   });
@@ -52,3 +58,4 @@ npm run qwik add service-worker
 ```
 
 This will add a basic service worker setup that you can customize for specific caching strategies, offline support, or other PWA features beyond just prefetching.
+

packages/docs/src/entry.ssr.tsx

@@ -1,12 +1,13 @@
-import { renderToStream, type RenderToStreamOptions } from '@builder.io/qwik/server';
+import type { PreloaderOptions, RenderToStreamOptions } from '@builder.io/qwik/server';
+import { renderToStream } from '@builder.io/qwik/server';
 import Root from './root';
 
 // You can pass these as query parameters, as well as `preloadDebug`
 const preloaderSettings = [
-  'maxPreloads',
-  'minProbability',
-  'maxSimultaneousPreloads',
-  'minPreloadProbability',
+  'ssrPreloads',
+  'ssrPreloadProbability',
+  'maxBufferPreloads',
+  'preloadProbability',
 ] as const;
 
 export default function (opts: RenderToStreamOptions) {
@@ -15,21 +16,21 @@ export default function (opts: RenderToStreamOptions) {
   if (urlStr) {
     const { searchParams } = new URL(urlStr);
     if (searchParams.size) {
-      opts = {
+      const newOpts = {
         ...opts,
-        prefetchStrategy: {
-          ...opts.prefetchStrategy,
-          implementation: { ...opts.prefetchStrategy?.implementation },
+        preloader: {
+          ...(typeof opts.preloader === 'object' ? opts.preloader : undefined),
         },
-      };
-      if (searchParams.has('preloadDebug')) {
-        opts.prefetchStrategy!.implementation!.debug = true;
+      } as Omit<RenderToStreamOptions, 'preloader'> & { preloader: PreloaderOptions };
+      if (searchParams.has('preloaderDebug')) {
+        newOpts.preloader!.debug = true;
       }
       for (const type of preloaderSettings) {
         if (searchParams.has(type)) {
-          opts.prefetchStrategy!.implementation![type] = Number(searchParams.get(type));
+          newOpts.preloader[type] = Number(searchParams.get(type));
         }
       }
+      opts = newOpts;
     }
   }
   return renderToStream(<Root />, {

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[debug?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nboolean\n\n\n</td><td>\n\n_(Optional)_ If true, the preloader will log debug information to the console.\n\nDefaults to `false`\n\n\n</td></tr>\n<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 links are added. 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)_\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 links are added. The preloader itself will autodetect which attribute to use based on the browser capabilities.\n\nDefaults to `modulepreload`<!-- -->.\n\n\n</td></tr>\n<tr><td>\n\n[maxPreloads?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n_(Optional)_ Maximum number of preload links to add during SSR. These instruct the browser to preload likely bundles before the preloader script is active. This includes the 2 preloads used for the preloader script itself and the bundle information. Setting this to 0 will disable all preload links.\n\nDefaults to `5`\n\n\n</td></tr>\n<tr><td>\n\n[maxSimultaneousPreloads?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n_(Optional)_ Maximum number of simultaneous preload links that the preloader will maintain.\n\nDefaults to `5`\n\n\n</td></tr>\n<tr><td>\n\n[minPreloadProbability?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n_(Optional)_ The minimum probability for a bundle to be added to the preload queue.\n\nDefaults to `0.25` (25% probability)\n\n\n</td></tr>\n<tr><td>\n\n[minProbability?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n_(Optional)_ The minimum probability of a bundle to be added as a preload link during SSR.\n\nDefaults to `0.6` (60% probability)\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)_\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)_\n\n\n</td></tr>\n</tbody></table>",
+      "content": "> Warning: This API is now obsolete.\n> \n> Use `preloader` instead\n> \n\n\n```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)_\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)_\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)_\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)_\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)_\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"
     },
@@ -114,6 +114,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/server/types.ts",
       "mdFile": "qwik.prefetchstrategy.md"
     },
+    {
+      "name": "PreloaderOptions",
+      "id": "preloaderoptions",
+      "hierarchy": [
+        {
+          "name": "PreloaderOptions",
+          "id": "preloaderoptions"
+        }
+      ],
+      "kind": "Interface",
+      "content": "```typescript\nexport interface PreloaderOptions \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[debug?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nboolean\n\n\n</td><td>\n\n_(Optional)_ Log preloader debug information to the console.\n\nDefaults to `false`\n\n\n</td></tr>\n<tr><td>\n\n[maxBufferPreloads?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n_(Optional)_ Maximum number of simultaneous preload links that the preloader will maintain. If you set this higher, the browser will have all JS files in memory sooner, but it will contend with other resource downloads. Furthermore, if a bundle suddenly becomes more likely, it will have to wait longer to be preloaded.\n\nBundles that reach 100% probability (static imports of other bundles) will always be preloaded immediately, no limit.\n\nDefaults to `25`\n\n\n</td></tr>\n<tr><td>\n\n[preloadProbability?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n_(Optional)_ The minimum probability for a bundle to be added to the preload queue.\n\nDefaults to `0.35` (35% probability)\n\n\n</td></tr>\n<tr><td>\n\n[ssrPreloadProbability?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n_(Optional)_ The minimum probability for a bundle to be added as a preload link during SSR.\n\nDefaults to `0.7` (70% probability)\n\n\n</td></tr>\n<tr><td>\n\n[ssrPreloads?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n_(Optional)_ Maximum number of preload links to add during SSR. These instruct the browser to preload likely bundles before the preloader script is active. This most likely includes the core and the preloader script itself. Setting this to 0 will disable all preload links.\n\nPreload links can delay LCP, which is a Core Web Vital, but it can increase TTI, which is not a Core Web Vital but more noticeable to the user.\n\nDefaults to `5`\n\n\n</td></tr>\n</tbody></table>",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/server/types.ts",
+      "mdFile": "qwik.preloaderoptions.md"
+    },
     {
       "name": "QwikLoaderOptions",
       "id": "qwikloaderoptions",
@@ -152,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[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[qwikPrefetchServiceWorker?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nQwikPrefetchServiceWorkerOptions\n\n\n</td><td>\n\n_(Optional)_\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) \\| boolean\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[qwikPrefetchServiceWorker?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nQwikPrefetchServiceWorkerOptions\n\n\n</td><td>\n\n_(Optional)_\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>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/server/types.ts",
       "mdFile": "qwik.renderoptions.md"
     },