From 261f6dc20d1a2b9f713d5813d59c7f23d00316af Mon Sep 17 00:00:00 2001 From: Jacob Fletcher Date: Fri, 10 May 2024 10:00:14 -0400 Subject: [PATCH] docs: adds examples docs --- docs/examples/overview.mdx | 40 ++++++++++++++++++++++++++++++++++ docs/live-preview/client.mdx | 2 +- docs/live-preview/frontend.mdx | 4 ++-- docs/live-preview/server.mdx | 18 ++++++++++----- 4 files changed, 56 insertions(+), 8 deletions(-) create mode 100644 docs/examples/overview.mdx diff --git a/docs/examples/overview.mdx b/docs/examples/overview.mdx new file mode 100644 index 0000000000..fbda8c235f --- /dev/null +++ b/docs/examples/overview.mdx @@ -0,0 +1,40 @@ +--- +title: Examples +label: Overview +order: 10 +desc: +keywords: example, examples, starter, boilerplate, template, templates +--- + +Payload provides a vast array of examples to help you get started with your project no matter what you are working on. These examples are designed to be easy to get up and running, and to be easy to understand. They showcase nothing more than the specific features being demonstrated so you can easily decipher what is going on. + +Examples are changing every day, so be sure to check back often to see what new examples have been added. If you have a specific example you would like to see, please feel free to start a new [Discussion](https://github.com/payloadcms/payload/discussions) or open a new [PR](https://github.com/payloadcms/payload/pulls) to add it yourself. + +- [Auth](https://github.com/payloadcms/payload/tree/main/examples/auth) +- [Custom Server](https://github.com/payloadcms/payload/tree/main/examples/custom-server) +- [Draft Preview](https://github.com/payloadcms/payload/tree/main/examples/draft-preview) +- [Email](https://github.com/payloadcms/payload/tree/main/examples/email) +- [Form Builder](https://github.com/payloadcms/payload/tree/main/examples/form-builder) +- [Hierarchy](https://github.com/payloadcms/payload/tree/main/examples/hierarchy) +- [Live Preview](https://github.com/payloadcms/payload/tree/main/examples/live-preview) +- [Multi-tenant](https://github.com/payloadcms/payload/tree/main/examples/multi-tenant) +- [Nested Docs](https://github.com/payloadcms/payload/tree/main/examples/nested-docs) +- [Redirects](https://github.com/payloadcms/payload/tree/main/examples/redirects) +- [Tailwind / Shadcn-ui](https://github.com/payloadcms/payload/tree/main/examples/tailwind-shadcn-ui) +- [Tests](https://github.com/payloadcms/payload/tree/main/examples/testing) +- [Virtual Fields](https://github.com/payloadcms/payload/tree/main/examples/virtual-fields) +- [White-label Admin UI](https://github.com/payloadcms/payload/tree/main/examples/whitelabel) + +When necessary, some examples include a front-end. Examples that require a front-end share this folder structure: + +```plaintext +example/ +├── payload/ +├── next-app/ +├── next-pages/ +├── react-router/ +├── vue/ +├── svelte/ +``` + +...where `payload` is your Payload project, and the other directories are dedicated to their respective front-end framework. We are adding new examples every day, so if your framework of choice is not yet supported in any particular example, please feel free to start a new [Discussion](https://github.com/payloadcms/payload/discussions) or open a new [PR](https://github.com/payloadcms/payload/pulls) to add it yourself. diff --git a/docs/live-preview/client.mdx b/docs/live-preview/client.mdx index 1de5279f4f..da6d66b7fb 100644 --- a/docs/live-preview/client.mdx +++ b/docs/live-preview/client.mdx @@ -7,7 +7,7 @@ keywords: live preview, frontend, react, next.js, vue, nuxt.js, svelte, hook, us --- - If your front-end application supports Server Components like the [Next.js App Router](https://nextjs.org/docs/app), etc., we suggest setting up [server-side Live Preview](./server). + If your front-end application supports Server Components like the [Next.js App Router](https://nextjs.org/docs/app), etc., we suggest setting up [server-side Live Preview](./server) instead. While using Live Preview, the Admin panel emits a new `window.postMessage` event every time your document has changed. Your front-end application can listen for these events and re-render accordingly. diff --git a/docs/live-preview/frontend.mdx b/docs/live-preview/frontend.mdx index 5ef11bd56f..14416e3ce7 100644 --- a/docs/live-preview/frontend.mdx +++ b/docs/live-preview/frontend.mdx @@ -6,11 +6,11 @@ desc: Learn how to implement Live Preview in your front-end application. keywords: live preview, frontend, react, next.js, vue, nuxt.js, svelte, hook, useLivePreview --- -There are two ways to use Live Preview in your own application depending on whether your front-end framework supports server components: +There are two ways to use Live Preview in your own application depending on whether your front-end framework supports Server Components: - [Server-side Live Preview (suggested)](./server) - [Client-side Live Preview](./client) - We suggest using server-side Live Preview if your framework supports it, it is both simpler to setup and more performant to run than the client-side alternative. + We suggest using server-side Live Preview if your framework supports Server Components, it is both simpler to setup and more performant to run than the client-side alternative. diff --git a/docs/live-preview/server.mdx b/docs/live-preview/server.mdx index 850e09e257..4293b4fb93 100644 --- a/docs/live-preview/server.mdx +++ b/docs/live-preview/server.mdx @@ -20,7 +20,7 @@ If your front-end application is built with [React](#react), you can use the `Re ## React -If your front-end application is built with [React](https://react.dev) or [Next.js](https://nextjs.org), you can use the `RefreshRouteOnSave` component that Payload provides. +If your front-end application is built with server-side [React](https://react.dev) like [Next.js App Router](https://nextjs.org/docs/app), you can use the `RefreshRouteOnSave` component that Payload provides. First, install the `@payloadcms/live-preview-react` package: @@ -28,7 +28,7 @@ First, install the `@payloadcms/live-preview-react` package: npm install @payloadcms/live-preview-react ``` -Then, render `RefreshRouteOnSave` anywhere in your `page.tsx`. Here's an example: +Then, render the `RefreshRouteOnSave` component anywhere in your `page.tsx`. Here's an example: `page.tsx`: @@ -64,7 +64,13 @@ import React from 'react' export const RefreshRouteOnSave: React.FC = () => { const router = useRouter() - return + + return ( + router.refresh()} + serverURL={process.env.NEXT_PUBLIC_PAYLOAD_URL} + /> + ) } ``` @@ -153,13 +159,15 @@ export const RefreshRouteOnSave: React.FC<{ ## Example -{/* TODO: add example once beta has been release and an example can be created */} +For a working demonstration of this, check out the official [Live Preview Example](https://github.com/payloadcms/payload/tree/main/examples/live-preview/payload). There you will find a fully working example of how to implement Live Preview in your Next.js App Router application. ## Troubleshooting ### Updates do not appear as fast as client-side Live Preview -If you are noticing that updates feel less snappy than client-side Live Preview (i.e. the `useLivePreview` hook), this is because of how the two differ in how they work—instead of emitting events against form state as you type, server-side Live Preview refreshes the route after a new document is saved. You can use autosave to mimic this effect. Try decreasing the value of `versions.autoSave.interval` to make the experience feel more responsive: +If you are noticing that updates feel less snappy than client-side Live Preview (i.e. the `useLivePreview` hook), this is because of how the two differ in how they work—instead of emitting events against _form state_, server-side Live Preview refreshes the route after a new document is _saved_. + +Use [Autosave](../versions/autosave) to mimic this effect server-side. Try decreasing the value of `versions.autoSave.interval` to make the experience feel more responsive: ```ts // collection.ts