chore: setup as experimental feature

Author: maiieul

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

@@ -530,7 +530,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "```typescript\nexport interface QwikCityMockProps \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[goto?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[RouteNavigate](#routenavigate)\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[params?](#)\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[url?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nstring\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n</tbody></table>",
+      "content": "```typescript\nexport interface QwikCityMockProps \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[fallbackToMpa?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n{ default: boolean; }\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[goto?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[RouteNavigate](#routenavigate)\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[params?](#)\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[url?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nstring\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-city/src/runtime/src/qwik-city-component.tsx",
       "mdFile": "qwik-city.qwikcitymockprops.md"
     },
@@ -572,7 +572,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "```typescript\nexport interface QwikCityProps \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[viewTransition?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nboolean\n\n\n</td><td>\n\n_(Optional)_ Enable the ViewTransition API\n\nDefault: `true`\n\n\n</td></tr>\n</tbody></table>",
+      "content": "```typescript\nexport interface QwikCityProps \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[fallbackToMpa?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n{ default: boolean; }\n\n\n</td><td>\n\n_(Optional)_ Whether Qwik should fallback to MPA navigation if too many bundles are queued for preloading during SPA navigation.\n\n\n</td></tr>\n<tr><td>\n\n[viewTransition?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nboolean\n\n\n</td><td>\n\n_(Optional)_ Enable the ViewTransition API\n\nDefault: `true`\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/runtime/src/qwik-city-component.tsx",
       "mdFile": "qwik-city.qwikcityprops.md"
     },

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

@@ -1781,6 +1781,21 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
+[fallbackToMpa?](#)
+
+</td><td>
+
+</td><td>
+
+\{ default: boolean; }
+
+</td><td>
+
+_(Optional)_
+
+</td></tr>
+<tr><td>
+
 [goto?](#)
 
 </td><td>
@@ -1988,6 +2003,21 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
+[fallbackToMpa?](#)
+
+</td><td>
+
+</td><td>
+
+\{ default: boolean; }
+
+</td><td>
+
+_(Optional)_ Whether Qwik should fallback to MPA navigation if too many bundles are queued for preloading during SPA navigation.
+
+</td></tr>
+<tr><td>
+
 [viewTransition?](#)
 
 </td><td>

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

@@ -106,6 +106,23 @@
       "content": "```typescript\ndirname(path: string): string;\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\npath\n\n\n</td><td>\n\nstring\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n\n**Returns:**\n\nstring",
       "mdFile": "qwik.path.dirname.md"
     },
+    {
+      "name": "enableFallbackToMpa",
+      "id": "experimentalfeatures-enablefallbacktompa",
+      "hierarchy": [
+        {
+          "name": "ExperimentalFeatures",
+          "id": "experimentalfeatures-enablefallbacktompa"
+        },
+        {
+          "name": "enableFallbackToMpa",
+          "id": "experimentalfeatures-enablefallbacktompa"
+        }
+      ],
+      "kind": "EnumMember",
+      "content": "",
+      "mdFile": "qwik.experimentalfeatures.enablefallbacktompa.md"
+    },
     {
       "name": "enableRequestRewrite",
       "id": "experimentalfeatures-enablerequestrewrite",
@@ -147,7 +164,7 @@
         }
       ],
       "kind": "Enum",
-      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\nUse `__EXPERIMENTAL__.x` to check if feature `x` is enabled. It will be replaced with `true` or `false` via an exact string replacement.\n\nAdd experimental features to this enum definition.\n\n\n```typescript\nexport declare enum ExperimentalFeatures \n```\n\n\n<table><thead><tr><th>\n\nMember\n\n\n</th><th>\n\nValue\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nenableRequestRewrite\n\n\n</td><td>\n\n`\"enableRequestRewrite\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable request.rewrite()\n\n\n</td></tr>\n<tr><td>\n\nnoSPA\n\n\n</td><td>\n\n`\"noSPA\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Disable SPA navigation handler in Qwik City\n\n\n</td></tr>\n<tr><td>\n\npreventNavigate\n\n\n</td><td>\n\n`\"preventNavigate\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the usePreventNavigate hook\n\n\n</td></tr>\n<tr><td>\n\nvalibot\n\n\n</td><td>\n\n`\"valibot\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the Valibot form validation\n\n\n</td></tr>\n</tbody></table>",
+      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\nUse `__EXPERIMENTAL__.x` to check if feature `x` is enabled. It will be replaced with `true` or `false` via an exact string replacement.\n\nAdd experimental features to this enum definition.\n\n\n```typescript\nexport declare enum ExperimentalFeatures \n```\n\n\n<table><thead><tr><th>\n\nMember\n\n\n</th><th>\n\nValue\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nenableFallbackToMpa\n\n\n</td><td>\n\n`\"enableFallbackToMpa\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable falling back to MPA when SPA navigation is slow, which can happen with a big page during preloading\n\n\n</td></tr>\n<tr><td>\n\nenableRequestRewrite\n\n\n</td><td>\n\n`\"enableRequestRewrite\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable request.rewrite()\n\n\n</td></tr>\n<tr><td>\n\nnoSPA\n\n\n</td><td>\n\n`\"noSPA\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Disable SPA navigation handler in Qwik City\n\n\n</td></tr>\n<tr><td>\n\npreventNavigate\n\n\n</td><td>\n\n`\"preventNavigate\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the usePreventNavigate hook\n\n\n</td></tr>\n<tr><td>\n\nvalibot\n\n\n</td><td>\n\n`\"valibot\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the Valibot form validation\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/optimizer/src/plugins/plugin.ts",
       "mdFile": "qwik.experimentalfeatures.md"
     },

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

@@ -328,6 +328,8 @@ string
 
 string
 
+## enableFallbackToMpa
+
 ## enableRequestRewrite
 
 ## EntryStrategy
@@ -374,6 +376,19 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
+enableFallbackToMpa
+
+</td><td>
+
+`"enableFallbackToMpa"`
+
+</td><td>
+
+**_(ALPHA)_** Enable falling back to MPA when SPA navigation is slow, which can happen with a big page during preloading
+
+</td></tr>
+<tr><td>
+
 enableRequestRewrite
 
 </td><td>

packages/qwik-city/src/runtime/src/contexts.ts

@@ -29,3 +29,5 @@ export const RouteInternalContext =
 
 export const RoutePreventNavigateContext =
   /*#__PURE__*/ createContextId<RoutePreventNavigate>('qc-p');
+
+export const fallbackToMpaContext = /*#__PURE__*/ createContextId<{ default: boolean }>('qc-f');

packages/qwik-city/src/runtime/src/link-component.tsx

@@ -9,6 +9,7 @@ import {
   untrack,
   type EventHandler,
   type QwikVisibleEvent,
+  useContext,
 } from '@builder.io/qwik';
 import { getClientNavPath, shouldPreload } from './utils';
 import { loadClientData } from './use-endpoint';
@@ -17,6 +18,7 @@ import { preloadRouteBundles } from './client-navigate';
 import { isDev } from '@builder.io/qwik';
 // @ts-expect-error we don't have types for the preloader yet
 import { p as preload, f as setMpaFallbackHref } from '@builder.io/qwik/preloader';
+import { fallbackToMpaContext } from './contexts';
 
 /** @public */
 export const Link = component$<LinkProps>((props) => {
@@ -35,10 +37,11 @@ export const Link = component$<LinkProps>((props) => {
     ...linkProps
   } = (() => props)();
 
-  // We need an RFC to assess whether or not we want to provide the ability to pass a number to customize the MPA fallback threshold.
-  // This depends on how well this feature is received in real projects, but also on what the threshold is based on: number of bundles needed to be preloaded for the next route, or the size of these bundles.
-  // In the future, we might be able to speed up SPA so much that falling back to MPA will never make sense.
-  const fallbackToMpa = untrack(() => Boolean(fallbackToMpaProp ?? true));
+  const defaultFallbackToMpa = useContext(fallbackToMpaContext).default;
+
+  const fallbackToMpa = __EXPERIMENTAL__.enableFallbackToMpa
+    ? untrack(() => Boolean(fallbackToMpaProp ?? defaultFallbackToMpa))
+    : undefined;
 
   const clientNavPath = untrack(() => getClientNavPath({ ...linkProps, reload }, loc));
   linkProps.href = clientNavPath || originalHref;
@@ -74,11 +77,8 @@ export const Link = component$<LinkProps>((props) => {
     : undefined;
 
   const preventDefault = clientNavPath
-    ? sync$((event: MouseEvent, target: HTMLAnchorElement) => {
+    ? sync$((event: MouseEvent) => {
         if (!(event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)) {
-          if (fallbackToMpa) {
-            setMpaFallbackHref(target.href);
-          }
           event.preventDefault();
         }
       })
@@ -96,15 +96,15 @@ export const Link = component$<LinkProps>((props) => {
             await nav(elm.href, { forceReload: reload, replaceState, scroll });
             elm.removeAttribute('aria-pressed');
           }
-          if (fallbackToMpa) {
-            setMpaFallbackHref(null);
-          }
         }
       })
     : undefined;
 
-  const handlePreload = $((_: any, elm: HTMLAnchorElement) => {
-    const url = new URL(elm.href);
+  const handlePreload = $((_: any, target: HTMLAnchorElement) => {
+    if (fallbackToMpa) {
+      setMpaFallbackHref(target.href);
+    }
+    const url = new URL(target.href);
     preloadRouteBundles(url.pathname, 1);
   });
 

packages/qwik-city/src/runtime/src/qwik-city-component.tsx

@@ -24,6 +24,7 @@ import {
   DocumentHeadContext,
   RouteActionContext,
   RouteInternalContext,
+  fallbackToMpaContext,
   RouteLocationContext,
   RouteNavigateContext,
   RoutePreventNavigateContext,
@@ -89,6 +90,12 @@ export interface QwikCityProps {
    * @see https://caniuse.com/mdn-api_viewtransition
    */
   viewTransition?: boolean;
+
+  /**
+   * Whether Qwik should fallback to MPA navigation if too many bundles are queued for preloading
+   * during SPA navigation.
+   */
+  fallbackToMpa?: { default: boolean };
 }
 
 // Gets populated by registerPreventNav on the client
@@ -307,6 +314,7 @@ export const QwikCityProvider = component$<QwikCityProps>((props) => {
   useContextProvider(RouteActionContext, actionState);
   useContextProvider(RouteInternalContext, routeInternal);
   useContextProvider<any>(RoutePreventNavigateContext, registerPreventNav);
+  useContextProvider(fallbackToMpaContext, props.fallbackToMpa ?? { default: false });
 
   useTask$(({ track }) => {
     async function run() {
@@ -646,6 +654,7 @@ export interface QwikCityMockProps {
   url?: string;
   params?: Record<string, string>;
   goto?: RouteNavigate;
+  fallbackToMpa?: { default: boolean };
 }
 
 /** @public */
@@ -693,6 +702,8 @@ export const QwikCityMockProvider = component$<QwikCityMockProps>((props) => {
   useContextProvider(RouteStateContext, loaderState);
   useContextProvider(RouteActionContext, actionState);
   useContextProvider(RouteInternalContext, routeInternal);
+  console.log('props.fallbackToMpa', props.fallbackToMpa?.default);
+  useContextProvider(fallbackToMpaContext, props.fallbackToMpa ?? { default: false });
 
   return <Slot />;
 });

packages/qwik-city/src/runtime/src/qwik-city.runtime.api.md

@@ -331,6 +331,10 @@ export const QWIK_CITY_SCROLLER = "_qCityScroller";
 
 // @public (undocumented)
 export interface QwikCityMockProps {
+    // (undocumented)
+    fallbackToMpa?: {
+        default: boolean;
+    };
     // (undocumented)
     goto?: RouteNavigate;
     // (undocumented)
@@ -360,6 +364,9 @@ export interface QwikCityPlan {
 
 // @public (undocumented)
 export interface QwikCityProps {
+    fallbackToMpa?: {
+        default: boolean;
+    };
     viewTransition?: boolean;
 }
 

packages/qwik/src/optimizer/src/plugins/plugin.ts

@@ -66,6 +66,11 @@ const CLIENT_STRIP_CTX_NAME = [
  * @alpha
  */
 export enum ExperimentalFeatures {
+  /**
+   * Enable falling back to MPA when SPA navigation is slow, which can happen with a big page during
+   * preloading
+   */
+  enableFallbackToMpa = 'enableFallbackToMpa',
   /** Enable the usePreventNavigate hook */
   preventNavigate = 'preventNavigate',
   /** Enable the Valibot form validation */

packages/qwik/src/optimizer/src/qwik.optimizer.api.md

@@ -52,6 +52,7 @@ export type EntryStrategy = InlineEntryStrategy | HoistEntryStrategy | SingleEnt
 
 // @alpha
 export enum ExperimentalFeatures {
+    enableFallbackToMpa = "enableFallbackToMpa",
     enableRequestRewrite = "enableRequestRewrite",
     noSPA = "noSPA",
     preventNavigate = "preventNavigate",