tabshift/payloadcms
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

chore: bump prettier, re-enable prettier for docs (#11695)

Browse Source 
## Introducing Prettier for docs

Prettier [was originally disabled for our docs as it didn't support MDX
2.0](1fa636417f),
outputting invalid MDX syntax.

This has since been fixed - prettier now supports MDX 2.0.

## Reducing print width

This also reduces the print width for the docs folder from 100 to 70.
Our docs code field are very narrow - this should help make code more
readable.

**Before**
![CleanShot 2025-03-13 at 19 58
11@2x](https://github.com/user-attachments/assets/0ae9e27b-cddf-44e5-a978-c8e24e99a314)

**After**

![CleanShot 2025-03-13 at 19 59
19@2x](https://github.com/user-attachments/assets/0e424f99-002c-4adc-9b37-edaeef239b0d)



**Before**
![CleanShot 2025-03-13 at 20 00
05@2x](https://github.com/user-attachments/assets/614e51b3-aa0d-45e7-98f4-fcdb1a778bcf)

**After**

![CleanShot 2025-03-13 at 20 00
16@2x](https://github.com/user-attachments/assets/be46988a-2cba-43fc-a8cd-fd3c781da930)
This commit is contained in:
Alessio Gravili
2025-03-14 11:13:08 -06:00
committed by GitHub
parent 9ea8a7acf0
commit 9f9db3ff81
121 changed files with 3721 additions and 3404 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
docs/live-preview/client.mdx
View File

@@ -7,7 +7,9 @@ keywords: live preview, frontend, react, next.js, vue, nuxt.js, svelte, hook, us
---
<Banner type="info">
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.
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.
</Banner>
While using Live Preview, the [Admin Panel](../admin/overview) 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.
@@ -18,12 +20,12 @@ By default, all hooks accept the following args:
| Path | Description |
| ------------------ | -------------------------------------------------------------------------------------- |
| **`serverURL`** * | The URL of your Payload server. |
| **`serverURL`** \* | The URL of your Payload server. |
| **`initialData`** | The initial data of the document. The live data will be merged in as changes are made. |
| **`depth`** | The depth of the relationships to fetch. Defaults to `0`. |
| **`apiRoute`** | The path of your API route as defined in `routes.api`. Defaults to `/api`. |
_* An asterisk denotes that a property is required._
_\* An asterisk denotes that a property is required._
And return the following values:
@@ -33,15 +35,19 @@ And return the following values:
| **`isLoading`** | A boolean that indicates whether or not the document is loading. |
<Banner type="info">
If your front-end is tightly coupled to required fields, you should ensure that your UI does not
break when these fields are removed. For example, if you are rendering something like
`data.relatedPosts[0].title`, your page will break once you remove the first related post. To get
around this, use conditional logic, optional chaining, or default values in your UI where needed.
For example, `data?.relatedPosts?.[0]?.title`.
If your front-end is tightly coupled to required fields, you should ensure
that your UI does not break when these fields are removed. For example, if you
are rendering something like `data.relatedPosts[0].title`, your page will
break once you remove the first related post. To get around this, use
conditional logic, optional chaining, or default values in your UI where
needed. For example, `data?.relatedPosts?.[0]?.title`.
</Banner>
<Banner type="info">
It is important that the `depth` argument matches exactly with the depth of your initial page request. The depth property is used to populated relationships and uploads beyond their IDs. See [Depth](../queries/depth) for more information.
It is important that the `depth` argument matches exactly with the depth of
your initial page request. The depth property is used to populated
relationships and uploads beyond their IDs. See [Depth](../queries/depth) for
more information.
</Banner>
## Frameworks
@@ -89,8 +95,9 @@ export const PageClient: React.FC<{
```
<Banner type="warning">
**Reminder:**
If you are using [React Server Components](https://react.dev/reference/rsc/server-components), we strongly suggest setting up [server-side Live Preview](./server) instead.
**Reminder:** If you are using [React Server
Components](https://react.dev/reference/rsc/server-components), we strongly
suggest setting up [server-side Live Preview](./server) instead.
</Banner>
### Vue
@@ -140,19 +147,19 @@ npm install @payloadcms/live-preview
This package provides the following functions:
| Path | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **`subscribe`** | Subscribes to the Admin Panel's `window.postMessage` events and calls the provided callback function. |
| **`unsubscribe`** | Unsubscribes from the Admin Panel's `window.postMessage` events. |
| **`ready`** | Sends a `window.postMessage` event to the Admin Panel to indicate that the front-end is ready to receive messages. |
| **`isLivePreviewEvent`** | Checks if a `MessageEvent` originates from the Admin Panel and is a Live Preview event, i.e. debounced form state. |
| Path | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| **`subscribe`** | Subscribes to the Admin Panel's `window.postMessage` events and calls the provided callback function. |
| **`unsubscribe`** | Unsubscribes from the Admin Panel's `window.postMessage` events. |
| **`ready`** | Sends a `window.postMessage` event to the Admin Panel to indicate that the front-end is ready to receive messages. |
| **`isLivePreviewEvent`** | Checks if a `MessageEvent` originates from the Admin Panel and is a Live Preview event, i.e. debounced form state. |
The `subscribe` function takes the following args:
| Path | Description |
| ------------------ | ------------------------------------------------------------------------------------------- |
| **`callback`** * | A callback function that is called with `data` every time a change is made to the document. |
| **`serverURL`** * | The URL of your Payload server. |
| **`callback`** \* | A callback function that is called with `data` every time a change is made to the document. |
| **`serverURL`** \* | The URL of your Payload server. |
| **`initialData`** | The initial data of the document. The live data will be merged in as changes are made. |
| **`depth`** | The depth of the relationships to fetch. Defaults to `0`. |
@@ -233,8 +240,9 @@ export const useLivePreview = <T extends any>(props: {
```
<Banner type="info">
When building your own hook, ensure that the args and return values are consistent with the ones
listed at the top of this document. This will ensure that all hooks follow the same API.
When building your own hook, ensure that the args and return values are
consistent with the ones listed at the top of this document. This will ensure
that all hooks follow the same API.
</Banner>
## Example

4
docs/live-preview/frontend.mdx
View File

@@ -12,5 +12,7 @@ There are two ways to use Live Preview in your own application depending on whet
- [Client-side Live Preview](./client)
<Banner type="info">
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.
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.
</Banner>

43
docs/live-preview/overview.mdx
View File

@@ -22,16 +22,19 @@ const config = buildConfig({
// highlight-start
livePreview: {
url: 'http://localhost:3000',
collections: ['pages']
collections: ['pages'],
},
// highlight-end
}
},
})
```
<Banner type="warning">
**Reminder:**
Alternatively, you can define the `admin.livePreview` property on individual [Collection Admin Configs](../configuration/collections#admin-options) and [Global Admin Configs](../configuration/globals#admin-options). Settings defined here will be merged into the top-level as overrides.
**Reminder:** Alternatively, you can define the `admin.livePreview` property
on individual [Collection Admin
Configs](../configuration/collections#admin-options) and [Global Admin
Configs](../configuration/globals#admin-options). Settings defined here will
be merged into the top-level as overrides.
</Banner>
## Options
@@ -42,12 +45,12 @@ The following options are available:
| Path | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`url`** * | String, or function that returns a string, pointing to your front-end application. This value is used as the iframe `src`. [More details](#url). |
| **`url`** \* | String, or function that returns a string, pointing to your front-end application. This value is used as the iframe `src`. [More details](#url). |
| **`breakpoints`** | Array of breakpoints to be used as “device sizes” in the preview window. Each item appears as an option in the toolbar. [More details](#breakpoints). |
| **`collections`** | Array of collection slugs to enable Live Preview on. |
| **`globals`** | Array of global slugs to enable Live Preview on. |
_* An asterisk denotes that a property is required._
_\* An asterisk denotes that a property is required._
### URL
@@ -66,7 +69,7 @@ const config = buildConfig({
url: 'http://localhost:3000', // highlight-line
collections: ['pages'],
},
}
},
})
```
@@ -101,13 +104,13 @@ const config = buildConfig({
The following arguments are provided to the `url` function:
| Path | Description |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| **`data`** | The data of the Document being edited. This includes changes that have not yet been saved. |
| **`locale`** | The locale currently being edited (if applicable). [More details](../configuration/localization). |
| **`collectionConfig`** | The Collection Admin Config of the Document being edited. [More details](../configuration/collections#admin-options). |
| **`globalConfig`** | The Global Admin Config of the Document being edited. [More details](../configuration/globals#admin-options). |
| **`req`** | The Payload Request object. |
| Path | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **`data`** | The data of the Document being edited. This includes changes that have not yet been saved. |
| **`locale`** | The locale currently being edited (if applicable). [More details](../configuration/localization). |
| **`collectionConfig`** | The Collection Admin Config of the Document being edited. [More details](../configuration/collections#admin-options). |
| **`globalConfig`** | The Global Admin Config of the Document being edited. [More details](../configuration/globals#admin-options). |
| **`req`** | The Payload Request object. |
You can return either an absolute URL or relative URL from this function. If you don't know the URL of your frontend at build-time, you can return a relative URL, and in that case, Payload will automatically construct an absolute URL by injecting the protocol, domain, and port from your browser window. Returning a relative URL is helpful for platforms like Vercel where you may have preview deployment URLs that are unknown at build time.
@@ -143,7 +146,7 @@ const config = buildConfig({
],
// highlight-end
},
}
},
})
```
@@ -151,12 +154,12 @@ The following options are available for each breakpoint:
| Path | Description |
| --------------- | --------------------------------------------------------------------------- |
| **`label`** * | The label to display in the drop-down. This is what the user will see. |
| **`name`** * | The name of the breakpoint. |
| **`width`** * | The width of the breakpoint. This is used to set the width of the iframe. |
| **`height`** * | The height of the breakpoint. This is used to set the height of the iframe. |
| **`label`** \* | The label to display in the drop-down. This is what the user will see. |
| **`name`** \* | The name of the breakpoint. |
| **`width`** \* | The width of the breakpoint. This is used to set the width of the iframe. |
| **`height`** \* | The height of the breakpoint. This is used to set the height of the iframe. |
_* An asterisk denotes that a property is required._
_\* An asterisk denotes that a property is required._
The "Responsive" option is always available in the drop-down and requires no additional configuration. This is the default breakpoint that will be used on initial load. This option styles the iframe with a width and height of `100%` so that it fills the screen at its maximum size and automatically resizes as the window changes size.

21
docs/live-preview/server.mdx
View File

@@ -7,13 +7,20 @@ keywords: live preview, frontend, react, next.js, vue, nuxt.js, svelte, hook, us
---
<Banner type="info">
Server-side Live Preview is only for front-end frameworks that support the concept of Server Components, i.e. [React Server Components](https://react.dev/reference/rsc/server-components). If your front-end application is built with a client-side framework like the [Next.js Pages Router](https://nextjs.org/docs/pages), [React Router](https://reactrouter.com), [Vue 3](https://vuejs.org), etc., see [client-side Live Preview](./client).
Server-side Live Preview is only for front-end frameworks that support the
concept of Server Components, i.e. [React Server
Components](https://react.dev/reference/rsc/server-components). If your
front-end application is built with a client-side framework like the [Next.js
Pages Router](https://nextjs.org/docs/pages), [React
Router](https://reactrouter.com), [Vue 3](https://vuejs.org), etc., see
[client-side Live Preview](./client).
</Banner>
Server-side Live Preview works by making a roundtrip to the server every time your document is saved, i.e. draft save, autosave, or publish. While using Live Preview, the Admin Panel emits a new `window.postMessage` event which your front-end application can use to invoke this process. In Next.js, this means simply calling `router.refresh()` which will hydrate the HTML using new data straight from the [Local API](../local-api/overview).
<Banner type="warning">
It is recommended that you enable [Autosave](../versions/autosave) alongside Live Preview to make the experience feel more responsive.
It is recommended that you enable [Autosave](../versions/autosave) alongside
Live Preview to make the experience feel more responsive.
</Banner>
If your front-end application is built with [React](#react), you can use the `RefreshRouteOnChange` function that Payload provides. In the future, all other major frameworks like Vue and Svelte will be officially supported. If you are using any of these frameworks today, you can still integrate with Live Preview yourself using the underlying tooling that Payload provides. See [building your own router refresh component](#building-your-own-router-refresh-component) for more information.
@@ -43,7 +50,7 @@ export default async function Page() {
const page = await payload.findByID({
collection: 'pages',
id: '123',
draft: true
draft: true,
})
return (
@@ -87,10 +94,10 @@ npm install @payloadcms/live-preview
This package provides the following functions:
| Path | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **`ready`** | Sends a `window.postMessage` event to the Admin Panel to indicate that the front-end is ready to receive messages. |
| **`isDocumentEvent`** | Checks if a `MessageEvent` originates from the Admin Panel and is a document-level event, i.e. draft save, autosave, publish, etc. |
| Path | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **`ready`** | Sends a `window.postMessage` event to the Admin Panel to indicate that the front-end is ready to receive messages. |
| **`isDocumentEvent`** | Checks if a `MessageEvent` originates from the Admin Panel and is a document-level event, i.e. draft save, autosave, publish, etc. |
With these functions, you can build your own hook using your front-end framework of choice: