Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Stop blocking navigation on a slow route chunk (DEV-4092) (#84964)

Romeo Van Snick49b6b75d3fbb
diff --git a/frontend/src/metabase/app.tsx b/frontend/src/metabase/app.tsx
index e404a6e872d..fc3b2e1225c 100644
--- a/frontend/src/metabase/app.tsx
+++ b/frontend/src/metabase/app.tsx
@@ -139,7 +139,7 @@ async function _init(
<RouterProvider
routes={routes}
onLocationChange={mirrorLocation}
- hydrateFallback={<DelayedLoadingSpinner />}
+ loadingFallback={<DelayedLoadingSpinner />}
/>
</MetabotProvider>
</AppThemeProvider>
diff --git a/frontend/src/metabase/router/RouterProvider.tsx b/frontend/src/metabase/router/RouterProvider.tsx
index 116e1baacae..6eba6a4bad9 100644
--- a/frontend/src/metabase/router/RouterProvider.tsx
+++ b/frontend/src/metabase/router/RouterProvider.tsx
@@ -72,14 +72,14 @@ function useLocationMirror(
export function RouterProvider({
routes,
onLocationChange,
- hydrateFallback,
+ loadingFallback,
}: {
routes: RouteObject[];
onLocationChange?: LocationMirror;
- hydrateFallback?: ReactNode;
+ loadingFallback?: ReactNode;
}): JSX.Element {
const [router] = useState(() =>
- createAppRouter(routes, getBasename() || undefined, hydrateFallback),
+ createAppRouter(routes, getBasename() || undefined, loadingFallback),
);
useLocationMirror(router, onLocationChange);
@@ -98,21 +98,21 @@ export function RouterProviderMemory({
basename,
routerHolder,
onLocationChange,
- hydrateFallback,
+ loadingFallback,
}: {
routes: RouteObject[];
initialRoute: string;
basename?: string;
routerHolder?: MemoryTestRouterHolder;
onLocationChange?: LocationMirror;
- hydrateFallback?: ReactNode;
+ loadingFallback?: ReactNode;
}): JSX.Element {
const [router] = useState(() => {
const created = createMemoryAppRouter(
routes,
initialRoute,
basename,
- hydrateFallback,
+ loadingFallback,
);
if (routerHolder) {
routerHolder.current = created;
diff --git a/frontend/src/metabase/router/create-router.tsx b/frontend/src/metabase/router/create-router.tsx
index 86c60783be5..65b79dee0b0 100644
--- a/frontend/src/metabase/router/create-router.tsx
+++ b/frontend/src/metabase/router/create-router.tsx
@@ -7,6 +7,7 @@ import {
} from "react-router";
import { AppShell } from "./AppShell";
+import { withChunkFallback } from "./lazy-page";
import { setRouter, setRouterExpected } from "./navigator";
export type MemoryTestRouter = DataRouter;
@@ -24,15 +25,17 @@ export type MemoryTestRouterHolder = { current: MemoryTestRouter | null };
* relative redux navigation resolves from the root (see `AppShell`) and as the
* seat for anything the app shell needs above the route tree.
*
- * `hydrateFallback` is what the router shows before it initializes. That window
- * is empty unless the first URL matches a `lazy` route, in which case the whole
- * tree, chrome included, waits on the chunk. Without a fallback the page is
- * blank for that time. The router cannot build one itself, so the app passes it
- * in.
+ * `loadingFallback` is what stands in for a page whose chunk has not arrived.
+ * The router shows it before it initializes, which is only ever a wait on a
+ * chunk: the first URL matching a `lazy` route makes the whole tree, chrome
+ * included, wait on it, and without a fallback the page is blank for that time.
+ * `withChunkFallback` then shows the same thing in a single page's place once a
+ * navigation has waited long enough. The router cannot build one itself, so the
+ * app passes it in.
*/
function withAppShell(
routes: RouteObject[],
- hydrateFallback?: ReactNode,
+ loadingFallback?: ReactNode,
): RouteObject[] {
// Every router this module builds gets an `AppShell`, and every `AppShell`
// registers a `navigate`. That is what lets the navigator hold a navigation
@@ -41,8 +44,8 @@ function withAppShell(
return [
{
element: <AppShell />,
- hydrateFallbackElement: hydrateFallback,
- children: routes,
+ hydrateFallbackElement: loadingFallback,
+ children: withChunkFallback(routes, loadingFallback),
},
];
}
@@ -59,10 +62,10 @@ function register(router: DataRouter): DataRouter {
export function createAppRouter(
routes: RouteObject[],
basename?: string,
- hydrateFallback?: ReactNode,
+ loadingFallback?: ReactNode,
): DataRouter {
return register(
- createBrowserRouter(withAppShell(routes, hydrateFallback), { basename }),
+ createBrowserRouter(withAppShell(routes, loadingFallback), { basename }),
);
}
@@ -70,13 +73,13 @@ export function createMemoryAppRouter(
routes: RouteObject[],
initialRoute: string,
basename?: string,
- hydrateFallback?: ReactNode,
+ loadingFallback?: ReactNode,
): DataRouter {
const entry = initialRoute.startsWith("/")
? initialRoute
: `/${initialRoute}`;
return register(
- createMemoryRouter(withAppShell(routes, hydrateFallback), {
+ createMemoryRouter(withAppShell(routes, loadingFallback), {
basename,
initialEntries: [entry],
}),
diff --git a/frontend/src/metabase/router/lazy-page.tsx b/frontend/src/metabase/router/lazy-page.tsx
new file mode 100644
index 00000000000..ad380e5858a
--- /dev/null
+++ b/frontend/src/metabase/router/lazy-page.tsx
@@ -0,0 +1,166 @@
+import { type ComponentType, type ReactNode, Suspense } from "react";
+import {
+ type BaseRouteObject,
+ type LazyRouteFunction,
+ Outlet,
+ type RouteObject,
+} from "react-router";
+
+import { isProduction } from "metabase/env";
+
+/**
+ * How long a navigation into a code-split route waits for its chunk before it
+ * commits without it.
+ *
+ * `route.lazy` holds the location until the module resolves. On a fast
+ * connection that reads as an instant navigation. On a slow one the click does
+ * nothing at all for as long as the fetch takes: the old page stays on screen,
+ * the URL does not move, and nothing says the app is working. Past this point
+ * the location commits and the page shows a loading fallback until the chunk
+ * lands.
+ */
+export const CHUNK_WAIT_MS = 1000;
+
+type LazyFunction = LazyRouteFunction<BaseRouteObject>;
+
+type LazyPage = {
+ Component: ComponentType;
+ load: () => Promise<unknown>;
+};
+
+const pages = new WeakMap<LazyFunction, LazyPage>();
+
+/**
+ * Caps how long each `lazy` route in the tree blocks a navigation, and renders
+ * `fallback` where the page goes for as long as the chunk is still on its way.
+ *
+ * Every `lazy` in the app resolves to a `Component` and nothing else. A loader
+ * or any other route property cannot be deferred this way: the router needs
+ * those before it commits, and this commits first. One that resolves anything
+ * else says so in the console outside production.
+ */
+export function withChunkFallback(
+ routes: RouteObject[],
+ fallback?: ReactNode,
+): RouteObject[] {
+ return routes.map((route) => {
+ const lazy =
+ typeof route.lazy === "function"
+ ? timeBoxed(route.lazy, fallback)
+ : route.lazy;
+
+ return route.index
+ ? { ...route, lazy }
+ : {
+ ...route,
+ lazy,
+ children:
+ route.children && withChunkFallback(route.children, fallback),
+ };
+ });
+}
+
+function timeBoxed(load: LazyFunction, fallback?: ReactNode): LazyFunction {
+ const { Component, load: start } = pageFor(load, fallback);
+ return () => waitForChunk(start()).then(() => ({ Component }));
+}
+
+/**
+ * One wrapper per loader, so routes that share a chunk still share a component.
+ * A dozen routes mount the query builder, and moving between two of them must
+ * not remount it.
+ */
+function pageFor(load: LazyFunction, fallback?: ReactNode): LazyPage {
+ const cached = pages.get(load);
+ if (cached) {
+ return cached;
+ }
+
+ let loading: Promise<unknown> | null = null;
+ let failure: unknown = null;
+ let Loaded: ComponentType | null = null;
+
+ const start = () =>
+ (loading ??= load().then(
+ (route) => {
+ warnOnDroppedProperties(route);
+ Loaded = route.Component ?? Outlet;
+ },
+ (error) => {
+ failure = error;
+ throw error;
+ },
+ ));
+
+ /**
+ * The chunk's component, suspending for as long as the module is on its way.
+ *
+ * `Loaded` is set one step before the step that commits the location, so a
+ * chunk that arrives before the wait runs out renders without suspending:
+ * nothing waits, and the fallback never mounts.
+ *
+ * A chunk that failed keeps failing, for every route that shares it, until
+ * the page is reloaded. react-router caches a rejected `lazy` per route, so
+ * this is wider, but a chunk fails by its URL and every route in it asks for
+ * the same one. Dropping the failure to let a later mount try again is what
+ * cannot be done: React re-renders a component that throws, which would make
+ * the retry a fetch loop.
+ */
+ function Chunk() {
+ if (failure) {
+ throw failure;
+ }
+
+ if (!Loaded) {
+ throw start();
+ }
+
+ return <Loaded />;
+ }
+
+ function LazyPage() {
+ return (
+ <Suspense fallback={fallback}>
+ <Chunk />
+ </Suspense>
+ );
+ }
+
+ const page = { Component: LazyPage, load: start };
+ pages.set(load, page);
+ return page;
+}
+
+function warnOnDroppedProperties(route: object): void {
+ if (isProduction) {
+ return;
+ }
+
+ const dropped = Object.keys(route).filter((key) => key !== "Component");
+ if (dropped.length > 0) {
+ console.warn(
+ `A lazy route resolved ${dropped.join(", ")}, which the chunk fallback drops. Only Component survives it.`,
+ );
+ }
+}
+
+/**
+ * Resolves when the chunk arrives or when the wait runs out, whichever is
+ * first. A chunk that fails still rejects, so the router reports a failed
+ * fetch the way it did before there was a wait to run out.
+ */
+function waitForChunk(loading: Promise<unknown>): Promise<void> {
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(resolve, CHUNK_WAIT_MS);
+ loading.then(
+ () => {
+ clearTimeout(timer);
+ resolve();
+ },
+ (error) => {
+ clearTimeout(timer);
+ reject(error);
+ },
+ );
+ });
+}
diff --git a/frontend/src/metabase/router/lazy-route.unit.spec.tsx b/frontend/src/metabase/router/lazy-route.unit.spec.tsx
index f0d2f96ea22..2ae847b0293 100644
--- a/frontend/src/metabase/router/lazy-route.unit.spec.tsx
+++ b/frontend/src/metabase/router/lazy-route.unit.spec.tsx
@@ -1,5 +1,8 @@
+import { useEffect } from "react";
+
import { act, render, renderRoutes, screen } from "__support__/ui";
import {
+ type MemoryTestRouterHolder,
type NavigateFunction,
type RouteObject,
RouterProviderMemory,
@@ -7,6 +10,8 @@ import {
useNavigate,
} from "metabase/router";
+import { CHUNK_WAIT_MS } from "./lazy-page";
+
function Home() {
return <span data-testid="home">home</span>;
}
@@ -70,7 +75,7 @@ describe("a lazy route", () => {
<RouterProviderMemory
routes={makeRoutes()}
initialRoute="/split"
- hydrateFallback={<span data-testid="hydrating">loading</span>}
+ loadingFallback={<span data-testid="hydrating">loading</span>}
/>,
);
@@ -161,6 +166,36 @@ describe("a lazy route", () => {
expect(router?.location.pathname).toBe("/split");
});
+ // The wait is a cap, not a delay. A chunk that comes back inside it commits
+ // the way it always did, and the page mounts with no fallback in between: one
+ // that mounted here would flash on every first visit to a route.
+ it("does not mount the fallback when the chunk arrives inside the wait", async () => {
+ const fallbackMounted = jest.fn();
+
+ function Fallback() {
+ useEffect(() => fallbackMounted(), []);
+ return <span data-testid="loading">loading</span>;
+ }
+
+ const routerHolder: MemoryTestRouterHolder = { current: null };
+
+ render(
+ <RouterProviderMemory
+ routes={makeRoutes()}
+ initialRoute="/"
+ routerHolder={routerHolder}
+ loadingFallback={<Fallback />}
+ />,
+ );
+
+ await act(async () => {
+ routerHolder.current?.navigate("/split");
+ });
+
+ expect(screen.getByTestId("split")).toBeInTheDocument();
+ expect(fallbackMounted).not.toHaveBeenCalled();
+ });
+
// react-router resolves `lazy` onto the route object itself, so the cost is
// paid once per chunk rather than on every navigation into the subtree.
it("is synchronous again on the second visit", async () => {
@@ -184,6 +219,106 @@ describe("a lazy route", () => {
});
});
+/**
+ * What happens when the chunk does not come back quickly. The point of the wait
+ * running out is that a slow network can no longer leave a click looking like
+ * nothing happened: the location commits, and the page shows a spinner until
+ * the chunk lands.
+ */
+describe("a lazy route whose chunk is slow", () => {
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ it("commits the location once the wait runs out, then shows the page", async () => {
+ jest.useFakeTimers();
+ const chunk = deferChunk();
+ const routerHolder: MemoryTestRouterHolder = { current: null };
+
+ render(
+ <RouterProviderMemory
+ routes={[
+ { path: "/", element: <Home /> },
+ { path: "/split", lazy: () => chunk.promise },
+ ]}
+ initialRoute="/"
+ routerHolder={routerHolder}
+ loadingFallback={<span data-testid="loading">loading</span>}
+ />,
+ );
+
+ act(() => {
+ routerHolder.current?.navigate("/split");
+ });
+
+ expect(routerHolder.current?.state.location.pathname).toBe("/");
+ expect(screen.getByTestId("home")).toBeInTheDocument();
+
+ await act(async () => {
+ jest.advanceTimersByTime(CHUNK_WAIT_MS);
+ });
+
+ expect(routerHolder.current?.state.location.pathname).toBe("/split");
+ expect(screen.getByTestId("loading")).toBeInTheDocument();
+ expect(screen.queryByTestId("home")).not.toBeInTheDocument();
+
+ await act(async () => {
+ chunk.resolve();
+ });
+
+ expect(screen.getByTestId("split")).toBeInTheDocument();
+ expect(screen.queryByTestId("loading")).not.toBeInTheDocument();
+ });
+
+ // The wait is per chunk, not per route: the routes that share a loader share
+ // the component that stands in for it, so moving between two of them is still
+ // one mount. A dozen query builder routes depend on that.
+ it("keeps one component across the routes that share a chunk", async () => {
+ const mount = jest.fn();
+
+ function Split() {
+ useEffect(() => mount(), []);
+ return <span data-testid="split">split</span>;
+ }
+
+ const load = async () => ({ Component: Split });
+ const { router } = renderRoutes(
+ [
+ { path: "/one", lazy: load },
+ { path: "/two", lazy: load },
+ ],
+ { initialRoute: "/one" },
+ );
+
+ expect(await screen.findByTestId("split")).toBeInTheDocument();
+
+ await act(async () => {
+ router?.navigate("/two");
+ });
+ await screen.findByTestId("split");
+
+ expect(router?.location.pathname).toBe("/two");
+ expect(mount).toHaveBeenCalledTimes(1);
+ });
+});
+
+/**
+ * A chunk that arrives when the test says so, standing in for a fetch that is
+ * still in flight when the wait runs out.
+ */
+function deferChunk() {
+ let resolve: () => void = () => undefined;
+
+ const promise = new Promise<{ Component: () => JSX.Element }>((settle) => {
+ resolve = () => settle({ Component: Split });
+ });
+
+ return {
+ promise,
+ resolve: () => resolve(),
+ };
+}
+
/**
* Renders with a `useNavigate` handle, so a test can navigate and then read the
* pending state in the same tick, the way a promise callback does.
diff --git a/frontend/src/metabase/router/use-is-navigating.ts b/frontend/src/metabase/router/use-is-navigating.ts
index e5a56ab4ecd..d9a7e677caf 100644
--- a/frontend/src/metabase/router/use-is-navigating.ts
+++ b/frontend/src/metabase/router/use-is-navigating.ts
@@ -6,9 +6,10 @@ import { UNSAFE_NavigationContext, useNavigation } from "react-router";
*
* A `route.lazy` route resolves its module before committing the location, which
* opens a window where the old page is still mounted at the old URL while the
- * router is already on its way somewhere else. Anything that navigates in that
- * window replaces the pending navigation rather than queueing behind it, and the
- * destination the user asked for is lost.
+ * router is already on its way somewhere else. The window is capped at
+ * `CHUNK_WAIT_MS`, but a slow connection reaches that cap. Anything that
+ * navigates in that window replaces the pending navigation rather than queueing
+ * behind it, and the destination the user asked for is lost.
*
* Effects that keep a URL in sync with state have to sit that window out. See
* `useDashboardUrlQuery`, which already does the same for a navigation held by a
diff --git a/frontend/src/metabase/routes.tsx b/frontend/src/metabase/routes.tsx
index 23a75040137..a0bf8869d92 100644
--- a/frontend/src/metabase/routes.tsx
+++ b/frontend/src/metabase/routes.tsx
@@ -90,8 +90,10 @@ export function LegacyBrowseRedirect() {
* them is visited.
*
* A `lazy` route makes that first navigation asynchronous: the router resolves
- * the module before it commits the location. It resolves the route in place, so
- * every later navigation to the query builder is synchronous again.
+ * the module before it commits the location, or gives up waiting for it and
+ * shows a spinner in the page's place (see `withChunkFallback`). It resolves the
+ * route in place, so every later navigation to the query builder is synchronous
+ * again.
*/
const queryBuilder = () =>
loadQueryBuilder().then(({ QueryBuilder }) => ({ Component: QueryBuilder }));