feat(core): allow qwikloader inlining

Author: wmertens

.changeset/heavy-mammals-drop.md

@@ -0,0 +1,5 @@
+---
+'@builder.io/qwik': minor
+---
+
+feat: the qwikloader can now be inlined again if required (for testing or specific network conditions). Pass `qwikLoader: 'inline'` to the render options.

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

@@ -137,8 +137,8 @@
           "id": "qwikloaderoptions"
         }
       ],
-      "kind": "Interface",
-      "content": "```typescript\nexport interface QwikLoaderOptions \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[include?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n'always' \\| 'never' \\| 'auto'\n\n\n</td><td>\n\n_(Optional)_ Whether to include the qwikloader script in the document. Normally you don't need to worry about this, but in case of multi-container apps using different Qwik versions, you might want to only enable it on one of the containers.\n\nDefaults to `'auto'`<!-- -->.\n\n\n</td></tr>\n<tr><td>\n\n[position?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n'top' \\| 'bottom'\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n</tbody></table>",
+      "kind": "TypeAlias",
+      "content": "```typescript\nexport type QwikLoaderOptions = 'module' | 'inline' | 'never' | {\n    include?: 'always' | 'never' | 'auto';\n    position?: 'top' | 'bottom';\n};\n```",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/server/types.ts",
       "mdFile": "qwik.qwikloaderoptions.md"
     },
@@ -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[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) \\| false\n\n\n</td><td>\n\n_(Optional)_ Specifies how preloading is handled. This ensures that code is instantly available when needed.\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 how the Qwik Loader is included in the document. This enables interactivity and lazy loading.\n\n`module`<!-- -->: Use a `<script>` tag to load the Qwik Loader. Subsequent page loads will have the script cached and instantly running.\n\n`inline`<!-- -->: This embeds the Qwik Loader script directly in the document. This adds about 3kB before compression, which typically is reduced to about 1.6kB with gzip.\n\n`never`<!-- -->: Do not include the Qwik Loader script. This is mostly useful when embedding multiple containers on the same page.\n\nDefaults to `module`<!-- -->.\n\nNote that the Qwik Loader is absolutely required for Qwik to work. There must be an instance of it loaded for any interactivity to happen.\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"
     },

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

@@ -545,60 +545,16 @@ Defaults to `5`
 ## QwikLoaderOptions
 
 ```typescript
-export interface QwikLoaderOptions
+export type QwikLoaderOptions =
+  | "module"
+  | "inline"
+  | "never"
+  | {
+      include?: "always" | "never" | "auto";
+      position?: "top" | "bottom";
+    };
 ```
 
-<table><thead><tr><th>
-
-Property
-
-</th><th>
-
-Modifiers
-
-</th><th>
-
-Type
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-[include?](#)
-
-</td><td>
-
-</td><td>
-
-'always' \| 'never' \| 'auto'
-
-</td><td>
-
-_(Optional)_ Whether to include the qwikloader script in the document. Normally you don't need to worry about this, but in case of multi-container apps using different Qwik versions, you might want to only enable it on one of the containers.
-
-Defaults to `'auto'`.
-
-</td></tr>
-<tr><td>
-
-[position?](#)
-
-</td><td>
-
-</td><td>
-
-'top' \| 'bottom'
-
-</td><td>
-
-_(Optional)_
-
-</td></tr>
-</tbody></table>
-
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/server/types.ts)
 
 ## Render
@@ -723,7 +679,7 @@ _(Optional)_
 
 </td><td>
 
-_(Optional)_
+_(Optional)_ Specifies how preloading is handled. This ensures that code is instantly available when needed.
 
 </td></tr>
 <tr><td>
@@ -738,9 +694,17 @@ _(Optional)_
 
 </td><td>
 
-_(Optional)_ Specifies if the Qwik Loader script is added to the document or not.
+_(Optional)_ Specifies how the Qwik Loader is included in the document. This enables interactivity and lazy loading.
+
+`module`: Use a `<script>` tag to load the Qwik Loader. Subsequent page loads will have the script cached and instantly running.
+
+`inline`: This embeds the Qwik Loader script directly in the document. This adds about 3kB before compression, which typically is reduced to about 1.6kB with gzip.
+
+`never`: Do not include the Qwik Loader script. This is mostly useful when embedding multiple containers on the same page.
+
+Defaults to `module`.
 
-Defaults to `{ include: true }`.
+Note that the Qwik Loader is absolutely required for Qwik to work. There must be an instance of it loaded for any interactivity to happen.
 
 </td></tr>
 <tr><td>

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

@@ -83,11 +83,10 @@ export interface PreloaderOptions {
 }
 
 // @public (undocumented)
-export interface QwikLoaderOptions {
+export type QwikLoaderOptions = 'module' | 'inline' | 'never' | {
     include?: 'always' | 'never' | 'auto';
-    // @deprecated (undocumented)
     position?: 'top' | 'bottom';
-}
+};
 
 // @public (undocumented)
 export type Render = RenderToString | RenderToStream;
@@ -101,7 +100,6 @@ export interface RenderOptions extends SerializeDocumentOptions {
     locale?: string | ((options: RenderOptions) => string);
     // @deprecated (undocumented)
     prefetchStrategy?: PrefetchStrategy | null;
-    // (undocumented)
     preloader?: PreloaderOptions | false;
     qwikLoader?: QwikLoaderOptions;
     // Warning: (ae-forgotten-export) The symbol "QwikPrefetchServiceWorkerOptions" needs to be exported by the entry point index.d.ts

packages/qwik/src/server/render.ts

@@ -20,6 +20,12 @@ import { manifest as builtManifest } from '@qwik-client-manifest';
 
 const DOCTYPE = '<!DOCTYPE html>';
 
+enum QwikLoaderInclude {
+  Module,
+  Inline,
+  Never,
+}
+
 /**
  * Creates a server-side `document`, renders to root node to the document, then serializes the
  * document to a string.
@@ -119,10 +125,22 @@ export async function renderToStream(
     ? injections.map((injection) => jsx(injection.tag, injection.attributes ?? {}))
     : [];
 
-  const includeMode = opts.qwikLoader?.include ?? 'auto';
+  let includeMode = opts.qwikLoader
+    ? typeof opts.qwikLoader === 'object'
+      ? opts.qwikLoader.include === 'never'
+        ? QwikLoaderInclude.Never
+        : QwikLoaderInclude.Module
+      : opts.qwikLoader === 'inline'
+        ? QwikLoaderInclude.Inline
+        : opts.qwikLoader === 'never'
+          ? QwikLoaderInclude.Never
+          : QwikLoaderInclude.Module
+    : QwikLoaderInclude.Module;
   const qwikLoaderChunk = resolvedManifest?.manifest.qwikLoader;
-  let didAddQwikLoader = false;
-  if (includeMode !== 'never' && qwikLoaderChunk) {
+  if (includeMode === QwikLoaderInclude.Module && !qwikLoaderChunk) {
+    includeMode = QwikLoaderInclude.Inline;
+  }
+  if (includeMode === QwikLoaderInclude.Module) {
     beforeContent.unshift(
       jsx('link', {
         rel: 'modulepreload',
@@ -136,7 +154,22 @@ export async function renderToStream(
         nonce,
       })
     );
-    didAddQwikLoader = true;
+  } else if (includeMode === QwikLoaderInclude.Inline) {
+    // It would be nice to keep track of HTML size and wait 30kB before inlining the script, skipping if ended and not needed.
+    const qwikLoaderScript = getQwikLoaderScript({
+      debug: opts.debug,
+    });
+    beforeContent.unshift(
+      jsx('script', {
+        id: 'qwikloader',
+        // Qwik only works when modules work
+        type: 'module',
+        // Execute asap, don't wait for domcontentloaded
+        async: true,
+        nonce,
+        dangerouslySetInnerHTML: qwikLoaderScript,
+      })
+    );
   }
   preloaderPre(buildBase, resolvedManifest, opts.preloader, beforeContent, nonce);
 
@@ -181,24 +214,6 @@ export async function renderToStream(
         );
       }
 
-      const needLoader = !snapshotResult || snapshotResult.mode !== 'static';
-      const includeLoader = includeMode === 'always' || (includeMode === 'auto' && needLoader);
-      if (!didAddQwikLoader && includeLoader) {
-        const qwikLoaderScript = getQwikLoaderScript({
-          debug: opts.debug,
-        });
-        children.push(
-          jsx('script', {
-            id: 'qwikloader',
-            // execute even before DOM order
-            async: true,
-            type: 'module',
-            dangerouslySetInnerHTML: qwikLoaderScript,
-            nonce,
-          })
-        );
-      }
-
       // We emit the events separately so other qwikloaders can see them
       const extraListeners = Array.from(containerState.$events$, (s) => JSON.stringify(s));
       if (extraListeners.length > 0) {

packages/qwik/src/server/types.ts

@@ -128,18 +128,16 @@ export interface RenderResult {
 }
 
 /** @public */
-export interface QwikLoaderOptions {
-  /**
-   * Whether to include the qwikloader script in the document. Normally you don't need to worry
-   * about this, but in case of multi-container apps using different Qwik versions, you might want
-   * to only enable it on one of the containers.
-   *
-   * Defaults to `'auto'`.
-   */
-  include?: 'always' | 'never' | 'auto';
-  /** @deprecated No longer used, the qwikloader is always loaded as soon as possible */
-  position?: 'top' | 'bottom';
-}
+export type QwikLoaderOptions =
+  | 'module'
+  | 'inline'
+  | 'never'
+  | {
+      /** @deprecated No longer used. */
+      include?: 'always' | 'never' | 'auto';
+      /** @deprecated No longer used. */
+      position?: 'top' | 'bottom';
+    };
 
 /**
  * @deprecated This is no longer used as the preloading happens automatically in qrl-class.ts.
@@ -167,12 +165,26 @@ export interface RenderOptions extends SerializeDocumentOptions {
   locale?: string | ((options: RenderOptions) => string);
 
   /**
-   * Specifies if the Qwik Loader script is added to the document or not.
+   * Specifies how the Qwik Loader is included in the document. This enables interactivity and lazy
+   * loading.
+   *
+   * `module`: Use a `<script>` tag to load the Qwik Loader. Subsequent page loads will have the
+   * script cached and instantly running.
+   *
+   * `inline`: This embeds the Qwik Loader script directly in the document. This adds about 3kB
+   * before compression, which typically is reduced to about 1.6kB with gzip.
+   *
+   * `never`: Do not include the Qwik Loader script. This is mostly useful when embedding multiple
+   * containers on the same page.
+   *
+   * Defaults to `module`.
    *
-   * Defaults to `{ include: true }`.
+   * Note that the Qwik Loader is absolutely required for Qwik to work. There must be an instance of
+   * it loaded for any interactivity to happen.
    */
   qwikLoader?: QwikLoaderOptions;
 
+  /** Specifies how preloading is handled. This ensures that code is instantly available when needed. */
   preloader?: PreloaderOptions | false;
 
   /** @deprecated Use `preloader` instead */