From 712647d74137d4c42a54db16d657ffeb3986a4e2 Mon Sep 17 00:00:00 2001 From: Jacob Fletcher Date: Fri, 24 Nov 2023 16:51:17 -0500 Subject: [PATCH] docs: adds live preview troubleshooting tips --- docs/live-preview/frontend.mdx | 52 ++++++++++++++++++++++++++++++++++ docs/live-preview/overview.mdx | 4 +++ 2 files changed, 56 insertions(+) diff --git a/docs/live-preview/frontend.mdx b/docs/live-preview/frontend.mdx index e034083316..1d8bab8ecd 100644 --- a/docs/live-preview/frontend.mdx +++ b/docs/live-preview/frontend.mdx @@ -187,3 +187,55 @@ For a working demonstration of this, check out the official [Live Preview Exampl - [Next.js App Router](https://github.com/payloadcms/payload/tree/main/examples/live-preview/next-app) - [Next.js Pages Router](https://github.com/payloadcms/payload/tree/main/examples/live-preview/next-pages) +## Troubleshooting + +### Relationships and/or uploads are not populating + +If you are using relationships or uploads in your front-end application, and your front-end application runs on a different domain than your Payload server, you may need to configure [CORS](../configuration/overview) to allow requests to be made between the two domains. This includes sites that are running on a different port or subdomain. Similarly, if you are protecting resources behind user authentication, you may also need to configure [CSRF](../authentication/overview#csrf-protection) to allow cookies to be sent between the two domains. For example: + +```ts +// payload.config.ts +{ + // ... + // If your site is running on a different domain than your Payload server, + // This will allows requests to be made between the two domains + cors: { + [ + 'http://localhost:3001' // Your front-end application + ], + }, + // If you are protecting resources behind user authentication, + // This will allow cookies to be sent between the two domains + csrf: { + [ + 'http://localhost:3001' // Your front-end application + ], + }, +} +``` + +### Relationships and/or uploads disappear after editing a document + +It is possible that either you are setting an improper [`depth`](../getting-started/concepts#depth) in your initial request and/or your `useLivePreview` hook, or they're mismatched. Ensure that the `depth` parameter is set to the correct value, and that it matches exactly in both places. For example: + +```tsx +// Your initial request +const { docs } = await payload.find({ + collection: 'pages', + depth: 1, // Ensure this is set to the proper depth for your application + where: { + slug: { + equals: 'home', + } + } +}) +``` + +```tsx +// Your hook +const { data } = useLivePreview({ + initialData: initialPage, + serverURL: PAYLOAD_SERVER_URL, + depth: 1, // Ensure this matches the depth of your initial request +}) +``` diff --git a/docs/live-preview/overview.mdx b/docs/live-preview/overview.mdx index a33b330b2c..292ec5053c 100644 --- a/docs/live-preview/overview.mdx +++ b/docs/live-preview/overview.mdx @@ -12,6 +12,10 @@ Live Preview works by rendering an iframe on the page that loads your front-end {/* IMAGE OF LIVE PREVIEW HERE */} + + Live Preview is currently in beta. You may use this feature in production, but please be aware that it is subject to change and may not be fully stable for all use cases. If you encounter any issues, please [report them](https://github.com/payloadcms/payload/issues/new?assignees=jacobsfletch&labels=possible-bug&projects=&title=Live%20Preview&template=1.bug_report.yml) with as much detail as possible. + + ## Setup Setting up Live Preview is easy. You first need to enable it through the `admin.livePreview` property of your Payload config. It takes the following options: