fix(ui): defer live preview iframe rendering (#15999)

When navigating to a document with live preview enabled, the respective
site is optimistically loaded regardless of whether the user is actively
previewing it.

This creates the following problems:
1. If the user's live preview URL is set up to proxy through an
endpoint, e.g. to enter draft mode before rendering the page, this will
be triggered preemptively, causing "draft mode" to persist for their
remaining session. For example, the user may revisit their site after
editing a page without live preview, and unexpectedly see draft content.
2. There are unnecessary performance and network costs of rendering the
iframe preemptively. Although the admin panel only dispatches events to
visible preview windows, the initial page load consumes resources
despite not being visible. For example, the underlying page is still
downloaded and rendered (if uncached), its db queries are still hit (if
dynamic), etc.

Now, the iframe window is conditionally mounted only when the user
toggles into live preview mode. To maintain fast loads thereafter, the
iframe doesn't unmount when toggled off. Live preview events themselves
are paused, but the window itself remains dormant until reactivated.

In the future we may also want to consider adding callbacks to the live
preview toggle event. That way you could reverse what your live preview
endpoint has done, e.g. exit draft mode.

Before:


https://github.com/user-attachments/assets/853708b4-3e53-4e7d-b848-c5879661d84c

After:


https://github.com/user-attachments/assets/491981dc-acae-420b-8b79-0aa8a763d4cc

Unrelated:
- Deflakes the `toggleLivePreview` test helper by making is
event-driven, e.g. it intercepts preference requests to ensure they are
fulfilled before moving on.

---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1213727956884077

Author: jacobsfletch

packages/ui/src/elements/LivePreview/Window/index.tsx

@@ -27,6 +27,7 @@ export const LivePreviewWindow: React.FC<EditViewProps> = (props) => {
     loadedURL,
     popupRef,
     previewWindowType,
+    shouldRenderIframe,
     url,
   } = useLivePreviewContext()
 
@@ -133,7 +134,9 @@ export const LivePreviewWindow: React.FC<EditViewProps> = (props) => {
       <div className={`${baseClass}__wrapper`}>
         <LivePreviewToolbar {...props} />
         <div className={`${baseClass}__main`}>
-          <DeviceContainer>{url ? <IFrame /> : <ShimmerEffect height="100%" />}</DeviceContainer>
+          <DeviceContainer>
+            {url && shouldRenderIframe ? <IFrame /> : <ShimmerEffect height="100%" />}
+          </DeviceContainer>
         </div>
       </div>
     </div>

packages/ui/src/providers/LivePreview/context.ts

@@ -42,14 +42,19 @@ export interface LivePreviewContextType {
   setPreviewWindowType: (previewWindowType: 'iframe' | 'popup') => void
   setSize: Dispatch<SizeReducerAction>
   setToolbarPosition: (position: { x: number; y: number }) => void
-
   /**
    * Sets the URL of the preview (either iframe or popup).
    * Will trigger a reload of the window.
    */
   setURL: (url: string) => void
   setWidth: (width: number) => void
   setZoom: (zoom: number) => void
+  /**
+   * Do not render the iframe until the user is actively live previewing. This will:
+   * 1. Prevent running through URL proxies set up on their `admin.livePreview.url` endpoint, e.g. to enter Next.js draft mode.
+   * 2. Avoid unnecessary performance and network costs of rendering the iframe before it's needed.
+   */
+  shouldRenderIframe?: boolean
   size: {
     height: number
     width: number
@@ -97,6 +102,7 @@ export const LivePreviewContext = createContext<LivePreviewContextType>({
   setURL: () => {},
   setWidth: () => {},
   setZoom: () => {},
+  shouldRenderIframe: undefined,
   size: {
     height: 0,
     width: 0,

packages/ui/src/providers/LivePreview/index.tsx

@@ -45,7 +45,27 @@ export const LivePreviewProvider: React.FC<LivePreviewProviderProps> = ({
   url: urlFromProps,
 }) => {
   const [previewWindowType, setPreviewWindowType] = useState<'iframe' | 'popup'>('iframe')
-  const [isLivePreviewing, setIsLivePreviewing] = useState(incomingIsLivePreviewing)
+
+  const [isLivePreviewing, _setIsLivePreviewing] =
+    useState<LivePreviewContextType['isLivePreviewing']>(incomingIsLivePreviewing)
+
+  const [shouldRenderIframe, setShouldRenderIframe] =
+    useState<LivePreviewContextType['shouldRenderIframe']>(isLivePreviewing)
+
+  /**
+   * Rendering the iframe is a one-way event, e.g. defer load and never unmount.
+   * This way, subsequent toggles will appear to load instantly.
+   */
+  const setIsLivePreviewing = useCallback<LivePreviewContextType['setIsLivePreviewing']>(
+    (livePreviewing) => {
+      if (livePreviewing) {
+        setShouldRenderIframe(true)
+      }
+
+      _setIsLivePreviewing(livePreviewing)
+    },
+    [],
+  )
 
   const breakpoints: LivePreviewConfig['breakpoints'] = useMemo(
     () => [
@@ -281,6 +301,7 @@ export const LivePreviewProvider: React.FC<LivePreviewProviderProps> = ({
         setURL: setLivePreviewURL,
         setWidth,
         setZoom,
+        shouldRenderIframe,
         size,
         toolbarPosition: position,
         typeofLivePreviewURL,

test/__helpers/e2e/live-preview/toggleLivePreview.ts

@@ -1,7 +1,9 @@
-import type { Page } from '@playwright/test'
+import type { Page, Route } from '@playwright/test'
 
 import { expect } from '@playwright/test'
 
+const endpoint = '**/api/payload-preferences/**'
+
 export const toggleLivePreview = async (
   page: Page,
   options?: {
@@ -15,15 +17,41 @@ export const toggleLivePreview = async (
     el.classList.contains('live-preview-toggler--active'),
   )
 
-  if (isActive && (options?.targetState === 'off' || !options?.targetState)) {
-    await toggler.click()
-    await expect(toggler).not.toHaveClass(/live-preview-toggler--active/)
-    await expect(page.locator('iframe.live-preview-iframe')).toBeHidden()
+  let hasSavedPrefs = false
+  let hasClickedToggler = false
+
+  const onRoute = async (route: Route) => {
+    const request = route.request()
+    const response = await route.fetch()
+
+    if (request.method() === 'POST' && response.status() === 200) {
+      hasSavedPrefs = true
+    }
+
+    await route.fulfill({ response })
   }
 
-  if (!isActive && (options?.targetState === 'on' || !options?.targetState)) {
-    await toggler.click()
-    await expect(toggler).toHaveClass(/live-preview-toggler--active/)
-    await expect(page.locator('iframe.live-preview-iframe')).toBeVisible()
+  await page.route(endpoint, onRoute)
+
+  try {
+    if (isActive && (options?.targetState === 'off' || !options?.targetState)) {
+      await toggler.click()
+      hasClickedToggler = true
+      await expect(toggler).not.toHaveClass(/live-preview-toggler--active/)
+      await expect(page.locator('iframe.live-preview-iframe')).toBeHidden()
+    }
+
+    if (!isActive && (options?.targetState === 'on' || !options?.targetState)) {
+      await toggler.click()
+      hasClickedToggler = true
+      await expect(toggler).toHaveClass(/live-preview-toggler--active/)
+      await expect(page.locator('iframe.live-preview-iframe')).toBeVisible()
+    }
+
+    if (hasClickedToggler) {
+      await expect.poll(() => hasSavedPrefs).toBeTruthy()
+    }
+  } finally {
+    await page.unroute(endpoint, onRoute)
   }
 }

test/_community/payload-types.ts

@@ -96,9 +96,6 @@ export interface Config {
     menu: MenuSelect<false> | MenuSelect<true>;
   };
   locale: null;
-  widgets: {
-    collections: CollectionsWidget;
-  };
   user: User;
   jobs: {
     tasks: unknown;
@@ -438,16 +435,6 @@ export interface MenuSelect<T extends boolean = true> {
   createdAt?: T;
   globalType?: T;
 }
-/**
- * This interface was referenced by `Config`'s JSON-Schema
- * via the `definition` "collections_widget".
- */
-export interface CollectionsWidget {
-  data?: {
-    [k: string]: unknown;
-  };
-  width: 'full';
-}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "auth".

test/live-preview/app/live-preview/(pages)/ssr/[slug]/page.tsx

@@ -19,6 +19,7 @@ type Args = {
 
 export default async function SSRPage({ params: paramsPromise }: Args) {
   const { slug = ' ' } = await paramsPromise
+
   const data = await getDoc<Page>({
     slug,
     collection: ssrPagesSlug,

test/live-preview/app/live-preview/_components/Media/Image/index.tsx

@@ -49,7 +49,7 @@ export const Image: React.FC<MediaProps> = (props) => {
 
     const filename = fullFilename
 
-    src = `${PAYLOAD_SERVER_URL}/api/media/file/${filename}`
+    src = `/api/media/file/${filename}`
   }
 
   if (!src) return null

test/live-preview/collections/Pages.ts

@@ -19,6 +19,8 @@ export const Pages: CollectionConfig = {
     delete: () => true,
   },
   admin: {
+    description:
+      'This collections does not use drafts or autosave. Changes are sent to the iframe window in real-time to use for fully client-side rendering.',
     useAsTitle: 'title',
     defaultColumns: ['id', 'title', 'slug', 'createdAt'],
     preview: (doc) => `/live-preview/${doc?.slug}`,

test/live-preview/collections/SSR.ts

@@ -20,6 +20,8 @@ export const SSR: CollectionConfig = {
     delete: () => true,
   },
   admin: {
+    description:
+      'This collections has drafts enabled, but not autosave. Changes need to be saved to trigger a full router refresh, which fetches draft content on the server.',
     useAsTitle: 'title',
     defaultColumns: ['id', 'title', 'slug', 'createdAt'],
     preview: (doc) => `/live-preview/ssr/${doc?.slug}`,

test/live-preview/collections/SSRAutosave.ts

@@ -27,6 +27,8 @@ export const SSRAutosave: CollectionConfig = {
     },
   },
   admin: {
+    description:
+      'This collections has drafts and autosave enabled. Changes will automatically trigger a full router refresh, which fetches draft content on the server.',
     useAsTitle: 'title',
     defaultColumns: ['id', 'title', 'slug', 'createdAt'],
     preview: (doc) => `/live-preview/ssr-autosave/${doc?.slug}`,