fix: Editor content delayed by React 19 Suspense reveal throttle (#13817)

Lazy components now render synchronously once their chunk is loaded and share a
preload promise, so the editor no longer commits a fallback and waits out the
300ms retry throttle. Editor chunks are preloaded from the document route, the
sidebar hover, and the data loader. A lint rule blocks direct imports of the
editor chunk.
This commit is contained in:
Tom Moor authored and GitHub committed 2026-09-20 16:54:56 -04:00
1 parent 5693562624
commit ad04aed6ef
11 files changed
+118 -20

No files matched your search

+6 -1
View File
@@ -4,7 +4,7 @@
"plugins": ["oxc", "eslint", "typescript", "react"],
"overrides": [
{
"files": ["**/*.{jsx,tsx}"],
"files": ["**/*.{js,jsx,ts,tsx}"],
"rules": {
"no-restricted-globals": [
"error",
@@ -17,6 +17,11 @@
"error",
{
"paths": [
{
"name": "~/editor",
"allowTypeImports": true,
"message": "Import AsyncEditor from ~/components/AsyncEditor instead. A direct import pulls the editor into the importing chunk and bypasses the shared preload."
},
{
"name": "prosemirror-tables",
"importNames": [
+13
View File
@@ -0,0 +1,13 @@
import lazyWithRetry from "~/utils/lazyWithRetry";
/**
* The editor core is the largest chunk in the app and is kept out of the
* initial bundle. This module stays light so routes can preload the chunk
* without pulling editor dependencies into their own chunk.
*/
const AsyncEditor = lazyWithRetry(
// oxlint-disable-next-line no-restricted-imports -- the one place the chunk is loaded
() => import("~/editor")
);
export default AsyncEditor;
+2 -4
View File
@@ -8,6 +8,7 @@ import type { Optional } from "utility-types";
import EditorContainer from "@shared/editor/components/Styles";
import { AttachmentPreset } from "@shared/types";
import { ProsemirrorHelper } from "@shared/utils/ProsemirrorHelper";
import AsyncEditor from "~/components/AsyncEditor";
import ClickablePadding from "~/components/ClickablePadding";
import ErrorBoundary from "~/components/ErrorBoundary";
import PlaceholderDocument from "~/components/PlaceholderDocument";
@@ -17,11 +18,8 @@ import useEditorClickHandlers from "~/hooks/useEditorClickHandlers";
import useEmbeds from "~/hooks/useEmbeds";
import useStores from "~/hooks/useStores";
import { uploadFile, uploadFileFromUrl } from "~/utils/files";
import lazyWithRetry from "~/utils/lazyWithRetry";
import useShare from "@shared/hooks/useShare";
const LazyLoadedEditor = lazyWithRetry(() => import("~/editor"));
export type Props = Optional<
EditorProps,
"placeholder" | "defaultValue" | "onClickLink" | "embeds" | "extensions"
@@ -235,7 +233,7 @@ function Editor({ ref, ...props }: Props & { ref?: React.Ref<SharedEditor> }) {
// React 18 would hide mounted ancestors and destroy their effects,
// re-running provider setup and ref callbacks in a loop.
<React.Suspense fallback={<PlaceholderDocument delay={500} />}>
<LazyLoadedEditor
<AsyncEditor
key={props.extensions?.length || 0}
ref={mergeRefs([ref, localRef, handleRefChanged])}
uploadFile={handleUploadFile}
+5 -5
View File
@@ -1,9 +1,10 @@
import * as React from "react";
import type { LazyComponent as LazyComponentType } from "~/utils/lazyWithRetry";
import lazyWithRetry from "~/utils/lazyWithRetry";
// oxlint-disable no-explicit-any -- ComponentType<any> is the standard React pattern for generic component constraints
export interface LazyComponent<T extends React.ComponentType<any>> {
Component: React.LazyExoticComponent<T>;
Component: LazyComponentType<T>;
preload: () => Promise<{ default: T }>;
}
@@ -46,8 +47,7 @@ export function createLazyComponent<T extends React.ComponentType<any>>(
}))
: (factory as () => Promise<{ default: T }>);
return {
Component: lazyWithRetry(wrappedFactory, retries, interval),
preload: wrappedFactory,
};
const Component = lazyWithRetry(wrappedFactory, retries, interval);
return { Component, preload: Component.preload };
}
@@ -24,7 +24,7 @@ import useOnScreen from "~/hooks/useOnScreen";
import usePolicy from "~/hooks/usePolicy";
import useStores from "~/hooks/useStores";
import DocumentMenu from "~/menus/DocumentMenu";
import * as Scenes from "~/routes/scenes";
import { preloadEditor } from "~/routes/scenes";
import { documentEditPath } from "~/utils/routeHelpers";
import {
useDragDocument,
@@ -276,7 +276,7 @@ const DocumentLinkInner = observer(function DocumentLinkInner({
}, [expansion, node.id]);
const handlePrefetch = React.useCallback(() => {
void Scenes.Document.preload();
preloadEditor();
void prefetchDocument?.(node.id);
}, [prefetchDocument, node]);
@@ -438,7 +438,7 @@ function StarredLink({ star }: Props) {
const handlePrefetch = React.useCallback(() => {
if (documentId) {
void Scenes.Document.preload();
Scenes.preloadEditor();
void documents.prefetchDocument(documentId);
const document = documents.get(documentId);
const documentCollection = document?.collectionId
+16 -2
View File
@@ -1,7 +1,7 @@
import { observer } from "mobx-react";
import { Suspense } from "react";
import { Suspense, useEffect } from "react";
import type { RouteComponentProps } from "react-router-dom";
import { Switch, Redirect } from "react-router-dom";
import { Switch, Redirect, matchPath, useLocation } from "react-router-dom";
import DocumentNew from "~/scenes/DocumentNew";
import Error404 from "~/scenes/Errors/Error404";
import AuthenticatedLayout from "~/components/AuthenticatedLayout";
@@ -54,6 +54,20 @@ function AuthenticatedRoutes() {
useKeyboardShortcutsQuery();
const team = useCurrentTeam();
const can = usePolicy(team);
const location = useLocation();
// Warm the editor chunks alongside the scene chunk so a document can render
// as soon as its data arrives.
useEffect(() => {
if (
matchPath(location.pathname, {
path: [`/doc/${documentSlug}`, `/d/${documentSlug}`],
})
) {
Scenes.preloadEditor();
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []);
return (
<WebsocketProvider>
+4 -2
View File
@@ -1,4 +1,6 @@
import AsyncEditor from "~/components/AsyncEditor";
import { createLazyComponent as lazy } from "~/components/LazyLoad";
import AsyncMultiplayerEditor from "~/scenes/Document/components/AsyncMultiplayerEditor";
/**
* Lazy-loaded scenes for the authenticated routes. Defined separately from the
@@ -21,6 +23,6 @@ export const Trash = lazy(() => import("~/scenes/Trash"));
*/
export function preloadEditor() {
void Document.preload();
void import("~/scenes/Document/components/MultiplayerEditor");
void import("~/editor");
void AsyncMultiplayerEditor.preload();
void AsyncEditor.preload();
}
@@ -19,6 +19,7 @@ import useCurrentUser from "~/hooks/useCurrentUser";
import usePolicy from "~/hooks/usePolicy";
import useQuery from "~/hooks/useQuery";
import useStores from "~/hooks/useStores";
import { preloadEditor } from "~/routes/scenes";
import type { Properties } from "~/types";
import Logger from "~/utils/Logger";
import {
@@ -106,6 +107,10 @@ function DataLoader({ match, children }: Props) {
useDocumentSidebar();
React.useEffect(() => {
preloadEditor();
}, []);
React.useEffect(() => {
async function fetchDocument() {
try {
File renamed without changes.
@@ -24,20 +24,81 @@ export function isStaleChunkError(error: unknown): boolean {
return staleChunkErrorPattern.test(message);
}
/**
* A promise that carries the status fields React's `use` hook reads, so a
* fulfilled load can be unwrapped synchronously without suspending.
*/
type TrackedPromise<T> = Promise<T> &
(
| React.PendingReactPromise<T>
| React.FulfilledReactPromise<T>
| React.RejectedReactPromise<T>
);
export type LazyComponent<T extends React.ComponentType<any>> = React.FC<
React.ComponentPropsWithRef<T>
> & {
/**
* Starts loading the chunk. Once the returned promise settles, rendering
* the component no longer suspends.
*/
preload: () => ComponentPromise<T>;
};
/**
* Lazy load a component with automatic retry on failure.
*
* Unlike `React.lazy`, a component whose chunk has already loaded renders
* synchronously instead of suspending. This matters because React throttles
* the reveal of a resolved Suspense boundary for up to 300ms after the fallback
* was shown, which delays content that is otherwise ready to paint.
*
* @param component A function that returns a promise of a component.
* @param retries The number of retries, defaults to 3.
* @param interval The interval between retries in milliseconds, defaults to 1000.
* @returns A lazy component.
* @returns A lazy component with a `preload` method.
*/
export default function lazyWithRetry<T extends React.ComponentType<any>>(
component: () => ComponentPromise<T>,
retries?: number,
interval?: number
): React.LazyExoticComponent<T> {
return React.lazy(() => retry(component, retries, interval));
): LazyComponent<T> {
let promise: TrackedPromise<{ default: T }> | undefined;
const preload = () => {
if (!promise) {
const pending = retry(component, retries, interval) as TrackedPromise<{
default: T;
}>;
pending.status = "pending";
void pending.then(
(module) => {
const fulfilled = pending as React.FulfilledReactPromise<{
default: T;
}>;
fulfilled.status = "fulfilled";
fulfilled.value = module;
},
(reason) => {
const rejected = pending as React.RejectedReactPromise<{
default: T;
}>;
rejected.status = "rejected";
rejected.reason = reason;
}
);
promise = pending;
}
return promise;
};
const Lazy = (props: React.ComponentPropsWithRef<T>) => {
const { default: Component } = React.use(preload());
return <Component {...props} />;
};
Lazy.displayName = "Lazy";
return Object.assign(Lazy, { preload });
}
function retry<T extends React.ComponentType<any>>(