feat(next): regenerate live preview url on save (#13631)

Closes #12785.

Although your live preview URL can be dynamic based on document data, it
is never recalculated after initial mount. This means if your URL is
dependent of document data that was just changed, such as a "slug"
field, the URL of the iframe does not reflect that change as expected
until the window is refreshed or you navigate back.

This also means that server-side live preview will crash when your
front-end attempts to query using a slug that no longer exists. Here's
the general flow: slug changes, autosave runs, iframe refreshes (url has
old slug), 404.

Now, we execute your live preview function on submit within form state,
and the window responds to the new URL as expected, refreshing itself
without losing its connection.

Here's the result:


https://github.com/user-attachments/assets/7dd3b147-ab6c-4103-8b2f-14d6bc889625

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

Author: jacobsfletch

packages/next/src/utilities/initReq.ts

@@ -72,6 +72,7 @@ export const initReq = async function ({
       cookies,
       headers,
     })
+
     const i18n: I18nClient = await initI18n({
       config: config.i18n,
       context: 'client',

packages/next/src/views/Document/index.tsx

@@ -6,7 +6,6 @@ import type {
   DocumentViewServerProps,
   DocumentViewServerPropsOnly,
   EditViewComponent,
-  LivePreviewConfig,
   PayloadComponent,
   RenderDocumentVersionsProperties,
 } from 'payload'
@@ -18,6 +17,7 @@ import {
   LivePreviewProvider,
 } from '@payloadcms/ui'
 import { RenderServerComponent } from '@payloadcms/ui/elements/RenderServerComponent'
+import { handleLivePreview } from '@payloadcms/ui/rsc'
 import { isEditing as getIsEditing } from '@payloadcms/ui/shared'
 import { buildFormState } from '@payloadcms/ui/utilities/buildFormState'
 import { notFound, redirect } from 'next/navigation.js'
@@ -348,36 +348,14 @@ export const renderDocument = async ({
     viewType,
   }
 
-  const isLivePreviewEnabled = Boolean(
-    config.admin?.livePreview?.collections?.includes(collectionSlug) ||
-      config.admin?.livePreview?.globals?.includes(globalSlug) ||
-      collectionConfig?.admin?.livePreview ||
-      globalConfig?.admin?.livePreview,
-  )
-
-  const livePreviewConfig: LivePreviewConfig = {
-    ...(isLivePreviewEnabled ? config.admin.livePreview : {}),
-    ...(collectionConfig?.admin?.livePreview || {}),
-    ...(globalConfig?.admin?.livePreview || {}),
-  }
-
-  const livePreviewURL =
-    operation !== 'create'
-      ? typeof livePreviewConfig?.url === 'function'
-        ? await livePreviewConfig.url({
-            collectionConfig,
-            data: doc,
-            globalConfig,
-            locale,
-            req,
-            /**
-             * @deprecated
-             * Use `req.payload` instead. This will be removed in the next major version.
-             */
-            payload: initPageResult.req.payload,
-          })
-        : livePreviewConfig?.url
-      : ''
+  const { isLivePreviewEnabled, livePreviewConfig, livePreviewURL } = await handleLivePreview({
+    collectionSlug,
+    config,
+    data: doc,
+    globalSlug,
+    operation,
+    req,
+  })
 
   return {
     data: doc,
@@ -412,6 +390,7 @@ export const renderDocument = async ({
           breakpoints={livePreviewConfig?.breakpoints}
           isLivePreviewEnabled={isLivePreviewEnabled && operation !== 'create'}
           isLivePreviewing={entityPreferences?.value?.editViewType === 'live-preview'}
+          typeofLivePreviewURL={typeof livePreviewConfig?.url as 'function' | 'string' | undefined}
           url={livePreviewURL}
         >
           {showHeader && !drawerSlug && (

packages/payload/src/admin/forms/Form.ts

@@ -135,6 +135,12 @@ export type BuildFormStateArgs = {
    */
   renderAllFields?: boolean
   req: PayloadRequest
+  /**
+   * If true, will return a fresh URL for live preview based on the current form state.
+   * Note: this will run on every form state event, so if your `livePreview.url` function is long running or expensive,
+   * ensure it caches itself as needed.
+   */
+  returnLivePreviewURL?: boolean
   returnLockStatus?: boolean
   schemaPath: string
   select?: SelectType

packages/payload/src/config/types.ts

@@ -151,10 +151,14 @@ export type LivePreviewConfig = {
     width: number | string
   }[]
   /**
-   The URL of the frontend application. This will be rendered within an `iframe` as its `src`.
-   Payload will send a `window.postMessage()` to this URL with the document data in real-time.
-   The frontend application is responsible for receiving the message and updating the UI accordingly.
-   Use the `useLivePreview` hook to get started in React applications.
+   * The URL of the frontend application. This will be rendered within an `iframe` as its `src`.
+   * Payload will send a `window.postMessage()` to this URL with the document data in real-time.
+   * The frontend application is responsible for receiving the message and updating the UI accordingly.
+   * Use the `useLivePreview` hook to get started in React applications.
+   *
+   * Note: this function may run often if autosave is enabled with a small interval.
+   * For performance, avoid long-running tasks or expensive operations within this function,
+   * or if you need to do something more complex, cache your function as needed.
    */
   url?:
     | ((args: {

packages/payload/src/globals/config/types.ts

@@ -233,9 +233,7 @@ export type GlobalConfig<TSlug extends GlobalSlug = any> = {
 export interface SanitizedGlobalConfig
   extends Omit<DeepRequired<GlobalConfig>, 'endpoints' | 'fields' | 'slug' | 'versions'> {
   endpoints: Endpoint[] | false
-
   fields: Field[]
-
   /**
    * Fields in the database schema structure
    * Rows / collapsible / tabs w/o name `fields` merged to top, UIs are excluded

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

@@ -6,24 +6,17 @@ import './index.scss'
 
 const baseClass = 'live-preview-iframe'
 
-type Props = {
-  ref: React.RefObject<HTMLIFrameElement>
-  setIframeHasLoaded: (value: boolean) => void
-  url: string
-}
-
-export const IFrame: React.FC<Props> = (props) => {
-  const { ref, setIframeHasLoaded, url } = props
-
-  const { zoom } = useLivePreviewContext()
+export const IFrame: React.FC = () => {
+  const { iframeRef, setLoadedURL, url, zoom } = useLivePreviewContext()
 
   return (
     <iframe
       className={baseClass}
+      key={url}
       onLoad={() => {
-        setIframeHasLoaded(true)
+        setLoadedURL(url)
       }}
-      ref={ref}
+      ref={iframeRef}
       src={url}
       style={{
         transform: typeof zoom === 'number' ? `scale(${zoom}) ` : undefined,

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

@@ -12,22 +12,21 @@ import { useLivePreviewContext } from '../../../providers/LivePreview/context.js
 import { useLocale } from '../../../providers/Locale/index.js'
 import { ShimmerEffect } from '../../ShimmerEffect/index.js'
 import { DeviceContainer } from '../Device/index.js'
-import './index.scss'
 import { IFrame } from '../IFrame/index.js'
 import { LivePreviewToolbar } from '../Toolbar/index.js'
+import './index.scss'
 
 const baseClass = 'live-preview-window'
 
 export const LivePreviewWindow: React.FC<EditViewProps> = (props) => {
   const {
     appIsReady,
     breakpoint,
-    iframeHasLoaded,
     iframeRef,
     isLivePreviewing,
+    loadedURL,
     popupRef,
     previewWindowType,
-    setIframeHasLoaded,
     url,
   } = useLivePreviewContext()
 
@@ -38,10 +37,12 @@ export const LivePreviewWindow: React.FC<EditViewProps> = (props) => {
   const [formState] = useAllFormFields()
   const { id, collectionSlug, globalSlug } = useDocumentInfo()
 
-  // For client-side apps, send data through `window.postMessage`
-  // The preview could either be an iframe embedded on the page
-  // Or it could be a separate popup window
-  // We need to transmit data to both accordingly
+  /**
+   * For client-side apps, send data through `window.postMessage`
+   * The preview could either be an iframe embedded on the page
+   * Or it could be a separate popup window
+   * We need to transmit data to both accordingly
+   */
   useEffect(() => {
     if (!isLivePreviewing || !appIsReady) {
       return
@@ -79,21 +80,22 @@ export const LivePreviewWindow: React.FC<EditViewProps> = (props) => {
     url,
     collectionSlug,
     globalSlug,
-    iframeHasLoaded,
     id,
     previewWindowType,
     popupRef,
     appIsReady,
     iframeRef,
-    setIframeHasLoaded,
     mostRecentUpdate,
     locale,
     isLivePreviewing,
+    loadedURL,
   ])
 
-  // To support SSR, we transmit a `window.postMessage` event without a payload
-  // This is because the event will ultimately trigger a server-side roundtrip
-  // i.e., save, save draft, autosave, etc. will fire `router.refresh()`
+  /**
+   * To support SSR, we transmit a `window.postMessage` event without a payload
+   * This is because the event will ultimately trigger a server-side roundtrip
+   * i.e., save, save draft, autosave, etc. will fire `router.refresh()`
+   */
   useEffect(() => {
     if (!isLivePreviewing || !appIsReady) {
       return
@@ -114,30 +116,26 @@ export const LivePreviewWindow: React.FC<EditViewProps> = (props) => {
     }
   }, [mostRecentUpdate, iframeRef, popupRef, previewWindowType, url, isLivePreviewing, appIsReady])
 
-  if (previewWindowType === 'iframe') {
-    return (
-      <div
-        className={[
-          baseClass,
-          isLivePreviewing && `${baseClass}--is-live-previewing`,
-          breakpoint && breakpoint !== 'responsive' && `${baseClass}--has-breakpoint`,
-        ]
-          .filter(Boolean)
-          .join(' ')}
-      >
-        <div className={`${baseClass}__wrapper`}>
-          <LivePreviewToolbar {...props} />
-          <div className={`${baseClass}__main`}>
-            <DeviceContainer>
-              {url ? (
-                <IFrame ref={iframeRef} setIframeHasLoaded={setIframeHasLoaded} url={url} />
-              ) : (
-                <ShimmerEffect height="100%" />
-              )}
-            </DeviceContainer>
-          </div>
+  if (previewWindowType !== 'iframe') {
+    return null
+  }
+
+  return (
+    <div
+      className={[
+        baseClass,
+        isLivePreviewing && `${baseClass}--is-live-previewing`,
+        breakpoint && breakpoint !== 'responsive' && `${baseClass}--has-breakpoint`,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      <div className={`${baseClass}__wrapper`}>
+        <LivePreviewToolbar {...props} />
+        <div className={`${baseClass}__main`}>
+          <DeviceContainer>{url ? <IFrame /> : <ShimmerEffect height="100%" />}</DeviceContainer>
         </div>
       </div>
-    )
-  }
+    </div>
+  )
 }

packages/ui/src/exports/rsc/index.ts

@@ -9,6 +9,7 @@ export { CheckIcon } from '../../icons/Check/index.js'
 export { copyDataFromLocaleHandler } from '../../utilities/copyDataFromLocale.js'
 export { getColumns } from '../../utilities/getColumns.js'
 export { getFolderResultsComponentAndData } from '../../utilities/getFolderResultsComponentAndData.js'
+export { handleLivePreview } from '../../utilities/handleLivePreview.js'
 export { renderFilters, renderTable } from '../../utilities/renderTable.js'
 export { resolveFilterOptions } from '../../utilities/resolveFilterOptions.js'
 export { upsertPreferences } from '../../utilities/upsertPreferences.js'

packages/ui/src/forms/Form/types.ts

@@ -18,13 +18,13 @@ export type Preferences = {
 
 export type FormOnSuccess<T = unknown, C = Record<string, unknown>> = (
   json: T,
-  options?: {
+  ctx?: {
     /**
      * Arbitrary context passed to the onSuccess callback.
      */
     context?: C
     /**
-     * Form state at the time of the request used to retrieve the JSON response.
+     * The form state that was sent with the request when retrieving the `json` arg.
      */
     formState?: FormState
   },

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

@@ -12,12 +12,17 @@ export interface LivePreviewContextType {
   appIsReady: boolean
   breakpoint: LivePreviewConfig['breakpoints'][number]['name']
   breakpoints: LivePreviewConfig['breakpoints']
-  iframeHasLoaded: boolean
   iframeRef: React.RefObject<HTMLIFrameElement | null>
   isLivePreviewEnabled: boolean
   isLivePreviewing: boolean
   isPopupOpen: boolean
   listeningForMessages?: boolean
+  /**
+   * The URL that has finished loading in the iframe or popup.
+   * For example, if you set the `url`, it will begin to load into the iframe,
+   * but `loadedURL` will not be set until the iframe's `onLoad` event fires.
+   */
+  loadedURL?: string
   measuredDeviceSize: {
     height: number
     width: number
@@ -28,12 +33,17 @@ export interface LivePreviewContextType {
   setAppIsReady: (appIsReady: boolean) => void
   setBreakpoint: (breakpoint: LivePreviewConfig['breakpoints'][number]['name']) => void
   setHeight: (height: number) => void
-  setIframeHasLoaded: (loaded: boolean) => void
   setIsLivePreviewing: (isLivePreviewing: boolean) => void
+  setLoadedURL: (loadedURL: string) => void
   setMeasuredDeviceSize: (size: { height: number; width: number }) => void
   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
   size: {
@@ -44,6 +54,11 @@ export interface LivePreviewContextType {
     x: number
     y: number
   }
+  /**
+   * The live preview url property can be either a string or a function that returns a string.
+   * It is important to know which one it is, so that we can opt in/out of certain behaviors, e.g. calling the server to get the URL.
+   */
+  typeofLivePreviewURL?: 'function' | 'string'
   url: string | undefined
   zoom: number
 }
@@ -52,7 +67,6 @@ export const LivePreviewContext = createContext<LivePreviewContextType>({
   appIsReady: false,
   breakpoint: undefined,
   breakpoints: undefined,
-  iframeHasLoaded: false,
   iframeRef: undefined,
   isLivePreviewEnabled: undefined,
   isLivePreviewing: false,
@@ -67,12 +81,13 @@ export const LivePreviewContext = createContext<LivePreviewContextType>({
   setAppIsReady: () => {},
   setBreakpoint: () => {},
   setHeight: () => {},
-  setIframeHasLoaded: () => {},
   setIsLivePreviewing: () => {},
+  setLoadedURL: () => {},
   setMeasuredDeviceSize: () => {},
   setPreviewWindowType: () => {},
   setSize: () => {},
   setToolbarPosition: () => {},
+  setURL: () => {},
   setWidth: () => {},
   setZoom: () => {},
   size: {
@@ -83,6 +98,7 @@ export const LivePreviewContext = createContext<LivePreviewContextType>({
     x: 0,
     y: 0,
   },
+  typeofLivePreviewURL: undefined,
   url: undefined,
   zoom: 1,
 })