chore(release): payload/2.0.6

chore: properly separates server / client exports

.git-blame-ignore-revs

@@ -10,3 +10,9 @@ cdaa0acd61d3001407609915bd573b78565d5571
 
 # prettier write again
 dfac7395fed95fc5d8ebca21b786ce70821942bb
+
+# lint and format plugin-cloud
+fb7d1be2f3325d076b7c967b1730afcef37922c2
+
+# lint and format create-payload-app
+5fd3d430001efe86515262ded5e26f00c1451181

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,7 +2,7 @@
 
 <!-- Please include a summary of the pull request and any related issues it fixes. Please also include relevant motivation and context. -->
 
-- [ ] I have read and understand the [CONTRIBUTING.md](../CONTRIBUTING.md) document in this repository.
+- [ ] I have read and understand the [CONTRIBUTING.md](https://github.com/payloadcms/payload/blob/main/CONTRIBUTING.md) document in this repository.
 
 ## Type of change
 

.github/workflows/main.yml

@@ -170,7 +170,6 @@ jobs:
         run: pnpm dev:generate-graphql-schema graphql-schema-gen
 
   build-packages:
-    name: Build Packages
     runs-on: ubuntu-latest
     needs: core-build
     strategy:
@@ -206,3 +205,38 @@ jobs:
 
       - name: Build ${{ matrix.pkg }}
         run: pnpm turbo run build --filter=${{ matrix.pkg }}
+
+  plugins:
+    runs-on: ubuntu-latest
+    needs: core-build
+    strategy:
+      fail-fast: false
+      matrix:
+        pkg:
+          - plugin-cloud
+          - create-payload-app
+
+    steps:
+      - name: Use Node.js 18
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 8
+          run_install: false
+
+      - name: Restore build
+        uses: actions/cache@v3
+        with:
+          path: ./*
+          key: ${{ github.sha }}-${{ github.run_number }}
+
+      - name: Build ${{ matrix.pkg }}
+        run: pnpm turbo run build --filter=${{ matrix.pkg }}
+
+      - name: Test ${{ matrix.pkg }}
+        run: pnpm --filter ${{ matrix.pkg }} run test
+        if: matrix.pkg != 'create-payload-app' # degit doesn't work within GitHub Actions

CHANGELOG.md

@@ -121,6 +121,12 @@ This means that in some fringe cases, if you are creating a doc and then instant
 
 To avoid any issues, you can pass the `req.transactionID` through to your Local API calls, so that your Local API calls are included as part of the parent transaction.
 
+### ⚠️ Locales now have more functionality, and in some places, you might need to update custom code
+
+Payload's locales have become more powerful and now allow you to customize more aspects per locale such as a human-friendly label and if the locale is RTL or not. 
+
+This means that certain functions now return a different shape, such as `useLocale`. This hook used to return a string of the locale code you are currently editing, but it now returns an object with type of `Locale`.
+
 ### ⚠️ Admin panel CSS classes may have changed
 
 The revisions we've made in 2.0 required changes to both HTML and CSS within the admin panel. For this reason, if you were loading custom CSS into the admin panel to customize the look and feel, your stylesheets may need to be updated. If your CSS is targeting elements on the page using HTML selectors or class names, you may need to update these selectors based on the current markup. It may also be necessary to update your style definitions if the core Payload component you are targeting has undergone significant change.

README.md

@@ -26,7 +26,8 @@
 </h4>
 <hr/>
 
-### 🎉 Payload 2.0 is now available! Read more in the [announcement post](https://payloadcms.com/blog/payload-2-0).
+> [!IMPORTANT]
+> 🎉 <strong>Payload 2.0 is now available!<strong> Read more in the <a target="_blank" href="https://payloadcms.com/blog/payload-2-0" rel="dofollow"><strong>announcement post</strong></a>.
 
 <h3>Benefits over a regular CMS</h3>
 <ul>

docs/admin/components.mdx

@@ -129,7 +129,7 @@ To add a _new_ view to the Admin Panel, simply add another key to the `views` ob
 }
 ```
 
-_For more examples regarding how to customize components, look at the following [examples](https://github.com/payloadcms/payload/tree/master/test/admin/components)._
+_For more examples regarding how to customize components, look at the following [examples](https://github.com/payloadcms/payload/tree/main/test/admin/components)._
 
 For help on how to build your own custom view components, see [building a custom view component](#building-a-custom-view-component).
 
@@ -399,12 +399,12 @@ Your custom view components will be given all the props that a React Router `<Ro
 
 #### Example
 
-You can find examples of custom views in the [Payload source code `/test/admin/components/views` folder](https://github.com/payloadcms/payload/tree/master/test/admin/components/views). There, you'll find two custom views:
+You can find examples of custom views in the [Payload source code `/test/admin/components/views` folder](https://github.com/payloadcms/payload/tree/main/test/admin/components/views). There, you'll find two custom views:
 
 1. A custom view that uses the `DefaultTemplate`, which is the built-in Payload template that displays the sidebar and "eyebrow nav"
 1. A custom view that uses the `MinimalTemplate` - which is just a centered template used for things like logging in or out
 
-To see how to pass in your custom views to create custom views of your own, take a look at the `admin.components.views` property of the [Payload test admin config](https://github.com/payloadcms/payload/blob/master/test/admin/config.ts).
+To see how to pass in your custom views to create custom views of your own, take a look at the `admin.components.views` property of the [Payload test admin config](https://github.com/payloadcms/payload/blob/main/test/admin/config.ts).
 
 ### Fields
 

docs/admin/hooks.mdx

@@ -347,7 +347,7 @@ The `useForm` hook returns an object with the following properties: |
           value: <strong><code>rowIndex</code></strong>,
         },
         {
-          value: "The index of the row to add",
+          value: "The index of the row to add. If omitted, the row will be added to the end of the array.",
         },
       ],
       [

docs/admin/overview.mdx

@@ -28,25 +28,25 @@ When bundled, it is code-split, highly performant (even with 100+ fields), and w
 
 All options for the Admin panel are defined in your base Payload config file.
 
-| Option                | Description                                                                                                                                                                                                                                                  |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `user`                | The `slug` of a Collection that you want be used to log in to the Admin dashboard. [More](/docs/admin/overview#the-admin-user-collection)                                                                                                                    |
-| `buildPath`           | Specify an absolute path for where to store the built Admin panel bundle used in production. Defaults to `path.resolve(process.cwd(), 'build')`.                                                                                                             |
-| `meta`                | Base meta data to use for the Admin panel. Included properties are `titleSuffix`, `ogImage`, and `favicon`.                                                                                                                                                  |
-| `disable`             | If set to `true`, the entire Admin panel will be disabled.                                                                                                                                                                                                   |
-| `indexHTML`           | Optionally replace the entirety of the `index.html` file used by the Admin panel. Reference the [base index.html file](https://github.com/payloadcms/payload/blob/main/packages/payload/src/admin/index.html) to ensure your replacement has the appropriate HTML elements. |
-| `css`                 | Absolute path to a stylesheet that you can use to override / customize the Admin panel styling. [More](/docs/admin/customizing-css).                                                                                                                         |
-| `scss`                | Absolute path to a Sass variables / mixins stylesheet meant to override Payload styles to make for an easy re-skinning of the Admin panel. [More](/docs/admin/customizing-css#overriding-scss-variables).                                                    |
-| `dateFormat`          | Global date format that will be used for all dates in the Admin panel. Any valid [date-fns](https://date-fns.org/) format pattern can be used.                                                                                                               |
-| `avatar`              | Set account profile picture. Options: `gravatar`, `default` or a custom React component.                                                                                                                                                                     |
-| `autoLogin`           | Used to automate admin log-in for dev and demonstration convenience. [More](/docs/authentication/config).                                                                                                                                                    |
-| `livePreview`         | Enable real-time editing for instant visual feedback of your front-end application. [More](/docs/live-preview/overview).                                                                                                                                     |
-| `components`          | Component overrides that affect the entirety of the Admin panel. [More](/docs/admin/components)                                                                                                                                                              |
-| `webpack`             | Customize the Webpack config that's used to generate the Admin panel. [More](/docs/admin/webpack)                                                                                                                                                            |
-| `vite`                | Customize the Vite config that's used to generate the Admin panel. [More](/docs/admin/vite)                                                                                                                                                                  |
-| **`bundler`**         | The bundler that you would like to use to bundle the admin panel. Officially supported bundlers: [Webpack](/docs/admin/webpack) and [Vite](/docs/admin/vite).                                                                                                |
-| **`logoutRoute`**     | The route for the `logout` page.                                                                                                                                                                                                                             |
-| **`inactivityRoute`** | The route for the `logout` inactivity page.                                                                                                                                                                                                                  |
+| Option            | Description                                                                                                                                                                                                                                                                 |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bundler`         | The bundler that you would like to use to bundle the admin panel. Officially supported bundlers: [Webpack](/docs/admin/webpack) and [Vite](/docs/admin/vite).                                                                                                               |
+| `user`            | The `slug` of a Collection that you want be used to log in to the Admin dashboard. [More](/docs/admin/overview#the-admin-user-collection)                                                                                                                                   |
+| `buildPath`       | Specify an absolute path for where to store the built Admin panel bundle used in production. Defaults to `path.resolve(process.cwd(), 'build')`.                                                                                                                            |
+| `meta`            | Base meta data to use for the Admin panel. Included properties are `titleSuffix`, `ogImage`, and `favicon`.                                                                                                                                                                 |
+| `disable`         | If set to `true`, the entire Admin panel will be disabled.                                                                                                                                                                                                                  |
+| `indexHTML`       | Optionally replace the entirety of the `index.html` file used by the Admin panel. Reference the [base index.html file](https://github.com/payloadcms/payload/blob/main/packages/payload/src/admin/index.html) to ensure your replacement has the appropriate HTML elements. |
+| `css`             | Absolute path to a stylesheet that you can use to override / customize the Admin panel styling. [More](/docs/admin/customizing-css).                                                                                                                                        |
+| `scss`            | Absolute path to a Sass variables / mixins stylesheet meant to override Payload styles to make for an easy re-skinning of the Admin panel. [More](/docs/admin/customizing-css#overriding-scss-variables).                                                                   |
+| `dateFormat`      | Global date format that will be used for all dates in the Admin panel. Any valid [date-fns](https://date-fns.org/) format pattern can be used.                                                                                                                              |
+| `avatar`          | Set account profile picture. Options: `gravatar`, `default` or a custom React component.                                                                                                                                                                                    |
+| `autoLogin`       | Used to automate admin log-in for dev and demonstration convenience. [More](/docs/authentication/config).                                                                                                                                                                   |
+| `livePreview`     | Enable real-time editing for instant visual feedback of your front-end application. [More](/docs/live-preview/overview).                                                                                                                                                    |
+| `components`      | Component overrides that affect the entirety of the Admin panel. [More](/docs/admin/components)                                                                                                                                                                             |
+| `webpack`         | Customize the Webpack config that's used to generate the Admin panel. [More](/docs/admin/webpack)                                                                                                                                                                           |
+| `vite`            | Customize the Vite config that's used to generate the Admin panel. [More](/docs/admin/vite)                                                                                                                                                                                 |
+| `logoutRoute`     | The route for the `logout` page.                                                                                                                                                                                                                                            |
+| `inactivityRoute` | The route for the `logout` inactivity page.                                                                                                                                                                                                                                 |
 
 ### The Admin User Collection
 

docs/configuration/i18n.mdx

@@ -65,7 +65,7 @@ After a user logs in, they can change their language selection in the `/account`
   <strong>Note:</strong>
   <br />
   If there is a language that Payload does not yet support, we accept code
-  [contributions](https://github.com/payloadcms/payload/blob/main/contributing.md).
+  [contributions](https://github.com/payloadcms/payload/blob/main/CONTRIBUTING.md).
 </Banner>
 
 ### Node Express

docs/configuration/overview.mdx

@@ -19,48 +19,53 @@ Payload is a _config-based_, code-first CMS and application framework. The Paylo
 
 ## Options
 
-| Option                | Description                                                                                                                                                                   |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `serverURL`           | A string used to define the absolute URL of your app including the protocol, for example `https://example.com`. No paths allowed, only protocol, domain and (optionally) port |
-| `collections`         | An array of all Collections that Payload will manage. To read more about how to define your collection configs, [click here](/docs/configuration/collections).                |
-| `cors`                | Either a whitelist array of URLS to allow CORS requests from, or a wildcard string (`'*'`) to accept incoming requests from any domain.                                       |
-| `globals`             | An array of all Globals that Payload will manage. For more on Globals and their configs, [click here](/docs/configuration/globals).                                           |
-| `admin`               | Base Payload admin configuration. Specify custom components, control metadata, set the Admin user collection, and [more](/docs/admin/overview#admin-options).                 |
-| `editor`              | Default richText editor which will be used by richText fields.                                                                                                                |
-| `localization`        | Opt-in and control how Payload handles the translation of your content into multiple locales. [More](/docs/configuration/localization)                                        |
-| `graphQL`             | Manage GraphQL-specific functionality here. Define your own queries and mutations, manage query complexity limits, and [more](/docs/graphql/overview#graphql-options).        |
-| `cookiePrefix`        | A string that will be prefixed to all cookies that Payload sets.                                                                                                              |
-| `csrf`                | A whitelist array of URLs to allow Payload cookies to be accepted from as a form of CSRF protection. [More](/docs/authentication/overview#csrf-protection)                    |
-| `defaultDepth`        | If a user does not specify `depth` while requesting a resource, this depth will be used. [More](/docs/getting-started/concepts#depth)                                         |
-| `maxDepth`            | The maximum allowed depth to be permitted application-wide. This setting helps prevent against malicious queries. Defaults to `10`.                                           |
-| `indexSortableFields` | Automatically index all sortable top-level fields in the database to improve sort performance and add database compatibility for Azure Cosmos and similar.                    |
-| `upload`              | Base Payload upload configuration. [More](/docs/upload/overview#payload-wide-upload-options).                                                                                 |
-| `routes`              | Control the routing structure that Payload binds itself to. Specify `admin`, `api`, `graphQL`, and `graphQLPlayground`.                                                       |
-| `email`               | Base email settings to allow Payload to generate email such as Forgot Password requests and other requirements. [More](/docs/email/overview#configuration)                    |
-| `express`             | Express-specific middleware options such as compression and JSON parsing. [More](/docs/configuration/express)                                                                 |
-| `debug`               | Enable to expose more detailed error information.                                                                                                                             |
-| `telemetry`           | Disable Payload telemetry by passing `false`. [More](/docs/configuration/overview#telemetry)                                                                                  |
-| `rateLimit`           | Control IP-based rate limiting for all Payload resources. Used to prevent DDoS attacks and [more](/docs/production/preventing-abuse#rate-limiting-requests).                  |
-| `hooks`               | Tap into Payload-wide hooks. [More](/docs/hooks/overview)                                                                                                                     |
-| `plugins`             | An array of Payload plugins. [More](/docs/plugins/overview)                                                                                                                   |
-| `endpoints`           | An array of custom API endpoints added to the Payload router. [More](/docs/rest-api/overview#custom-endpoints)                                                                |
-| `custom`              | Extension point for adding custom data (e.g. for plugins)                                                                                                                     |
+| Option                | Description                                                                                                                                                                       |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `admin` \*            | Base Payload admin configuration. Specify bundler*, custom components, control metadata, set the Admin user collection, and [more](/docs/admin/overview#admin-options). Required. |
+| `editor` \*           | Rich Text Editor which will be used by richText fields. Required.                                                                                                                 |
+| `db` \*               | Database Adapter which will be used by Payload. Read more [here](/docs/database/overview). Required.                                                                              |
+| `serverURL`           | A string used to define the absolute URL of your app including the protocol, for example `https://example.com`. No paths allowed, only protocol, domain and (optionally) port     |
+| `collections`         | An array of all Collections that Payload will manage. To read more about how to define your collection configs, [click here](/docs/configuration/collections).                    |
+| `globals`             | An array of all Globals that Payload will manage. For more on Globals and their configs, [click here](/docs/configuration/globals).                                               |
+| `cors`                | Either a whitelist array of URLS to allow CORS requests from, or a wildcard string (`'*'`) to accept incoming requests from any domain.                                           |
+| `localization`        | Opt-in and control how Payload handles the translation of your content into multiple locales. [More](/docs/configuration/localization)                                            |
+| `graphQL`             | Manage GraphQL-specific functionality here. Define your own queries and mutations, manage query complexity limits, and [more](/docs/graphql/overview#graphql-options).            |
+| `cookiePrefix`        | A string that will be prefixed to all cookies that Payload sets.                                                                                                                  |
+| `csrf`                | A whitelist array of URLs to allow Payload cookies to be accepted from as a form of CSRF protection. [More](/docs/authentication/overview#csrf-protection)                        |
+| `defaultDepth`        | If a user does not specify `depth` while requesting a resource, this depth will be used. [More](/docs/getting-started/concepts#depth)                                             |
+| `maxDepth`            | The maximum allowed depth to be permitted application-wide. This setting helps prevent against malicious queries. Defaults to `10`.                                               |
+| `indexSortableFields` | Automatically index all sortable top-level fields in the database to improve sort performance and add database compatibility for Azure Cosmos and similar.                        |
+| `upload`              | Base Payload upload configuration. [More](/docs/upload/overview#payload-wide-upload-options).                                                                                     |
+| `routes`              | Control the routing structure that Payload binds itself to. Specify `admin`, `api`, `graphQL`, and `graphQLPlayground`.                                                           |
+| `email`               | Base email settings to allow Payload to generate email such as Forgot Password requests and other requirements. [More](/docs/email/overview#configuration)                        |
+| `express`             | Express-specific middleware options such as compression and JSON parsing. [More](/docs/configuration/express)                                                                     |
+| `debug`               | Enable to expose more detailed error information.                                                                                                                                 |
+| `telemetry`           | Disable Payload telemetry by passing `false`. [More](/docs/configuration/overview#telemetry)                                                                                      |
+| `rateLimit`           | Control IP-based rate limiting for all Payload resources. Used to prevent DDoS attacks and [more](/docs/production/preventing-abuse#rate-limiting-requests).                      |
+| `hooks`               | Tap into Payload-wide hooks. [More](/docs/hooks/overview)                                                                                                                         |
+| `plugins`             | An array of Payload plugins. [More](/docs/plugins/overview)                                                                                                                       |
+| `endpoints`           | An array of custom API endpoints added to the Payload router. [More](/docs/rest-api/overview#custom-endpoints)                                                                    |
+| `custom`              | Extension point for adding custom data (e.g. for plugins)                                                                                                                         |
+
+_\* An asterisk denotes that a property is required._
 
 #### Simple example
 
 ```ts
 import { buildConfig } from 'payload/config'
 import { mongooseAdapter } from '@payloadcms/db-mongodb'
-import { postgresAdapter } from '@payloadcms/db-postgres'
+import { postgresAdapter } from '@payloadcms/db-postgres' // beta
 
 import { viteBundler } from '@payloadcms/bundler-vite'
 import { webpackBundler } from '@payloadcms/bundler-webpack'
 
-import { lexicalEditor } from '@payloadcms/richtext-lexical'
+import { lexicalEditor } from '@payloadcms/richtext-lexical' // beta
 import { slateEditor } from '@payloadcms/richtext-slate'
 
 export default buildConfig({
-  bundler: webpackBundler() // or viteBundler(),
+  admin: {
+    bundler: webpackBundler(), // or viteBundler()
+  },
   db: mongooseAdapter({}) // or postgresAdapter({}),
   editor: lexicalEditor({}) // or slateEditor({})
   collections: [

docs/graphql/graphql-schema.mdx

@@ -8,7 +8,7 @@ keywords: headless cms, typescript, documentation, Content Management System, cm
 
 When working with GraphQL it is useful to have the schema for development of other projects that need to call on your GraphQL endpoint. In Payload the schema is controlled by your collections and globals and is made available to the developer or third parties, it is not necessary for developers using Payload to write schema types manually.
 
-### Schema generatation script
+### Schema generation script
 
 Run the following command in a Payload project to generate your project's GraphQL schema from Payload:
 

docs/live-preview/frontend.mdx

@@ -88,13 +88,14 @@ This package provides the following functions:
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **`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.                                                                          |
 
 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.                                                                                                                                                        git s     |
+| **`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`.                                                                                                                                   |
 
@@ -103,18 +104,23 @@ With these functions, you can build your own hook using your front-end framework
 ```tsx
 import { subscribe, unsubscribe } from '@payloadcms/live-preview';
 
-// Build your own hook to subscribe to the live preview events
-// This function will handle everything for you like
-// 1. subscribing to `window.postMessage` events
-// 2. merging initial page data with incoming form state
-// 3. populating relationships and uploads
+// To build your own hook, subscribe to Live Preview events using the`subscribe` function
+// It handles everything from:
+// 1. Listening to `window.postMessage` events
+// 2. Merging initial data with active form state
+// 3. Populating relationships and uploads
+// 4. Calling the `onChange` callback with the result
+// Your hook should also:
+// 1. Tell the Admin panel when it is ready to receive messages
+// 2. Handle the results of the `onChange` callback to update the UI
+// 3. Unsubscribe from the `window.postMessage` events when it unmounts
 ```
 
 Here is an example of what the same `useLivePreview` React hook from above looks like under the hood:
 
 ```tsx
-import { subscribe, unsubscribe } from '@payloadcms/live-preview'
-import { useCallback, useEffect, useState } from 'react'
+import { subscribe, unsubscribe, ready } from '@payloadcms/live-preview'
+import { useCallback, useEffect, useState, useRef } from 'react'
 
 export const useLivePreview = <T extends any>(props: {
   depth?: number
@@ -127,13 +133,18 @@ export const useLivePreview = <T extends any>(props: {
   const { depth = 0, initialData, serverURL } = props
   const [data, setData] = useState<T>(initialData)
   const [isLoading, setIsLoading] = useState<boolean>(true)
+  const hasSentReadyMessage = useRef<boolean>(false)
 
   const onChange = useCallback((mergedData) => {
+    // When a change is made, the `onChange` callback will be called with the merged data
+    // Set this merged data into state so that React will re-render the UI
     setData(mergedData)
     setIsLoading(false)
   }, [])
 
   useEffect(() => {
+    // Listen for `window.postMessage` events from the Admin panel
+    // When a change is made, the `onChange` callback will be called with the merged data
     const subscription = subscribe({
       callback: onChange,
       depth,
@@ -141,6 +152,17 @@ export const useLivePreview = <T extends any>(props: {
       serverURL,
     })
 
+    // Once subscribed, send a `ready` message back up to the Admin panel
+    // This will indicate that the front-end is ready to receive messages
+    if (!hasSentReadyMessage.current) {
+      hasSentReadyMessage.current = true
+
+      ready({
+        serverURL
+      })
+    }
+
+    // When the component unmounts, unsubscribe from the `window.postMessage` events
     return () => {
       unsubscribe(subscription)
     }

docs/live-preview/overview.mdx

@@ -8,7 +8,7 @@ keywords: live preview, preview, live, iframe, iframe preview, visual editing, d
 
 **With Live Preview you can render your front-end application directly within the Admin panel. As you type, your changes take effect in real-time. No need to save a draft or publish your changes.**
 
-Live Preview works by rendering an iframe on the page that loads your front-end application. The Admin panel communicates with your app through `window.postMessage` events. These events are emitted every time a change is made to the document. Your app then listens for these events and re-renders itself with the data it receives.
+Live Preview works by rendering an iframe on the page that loads your front-end application. The Admin panel communicates with your app through [`window.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) events. These events are emitted every time a change is made to the document. Your app then listens for these events and re-renders itself with the data it receives.
 
 {/* IMAGE OF LIVE PREVIEW HERE */}
 
@@ -84,8 +84,8 @@ Here is an example of using a function that returns a dynamic URL:
         documentInfo,
         locale
       }) => `${data.tenant.url}${ // Multi-tenant top-level domain
-        documentInfo.slug === 'posts' ? `/posts/${data.slug}` : `/${data.slug}
-      `}?locale=${locale}`, // Localization query param
+        documentInfo.slug === 'posts' ? `/posts/${data.slug}` : `${data.slug !== 'home' : `/${data.slug}` : ''}`
+      }${locale ? `?locale=${locale?.code}` : ''}`, // Localization query param
       collections: ['pages'],
     },
   }

examples/auth/payload/nodemon.json

@@ -1,4 +1,5 @@
 {
   "ext": "ts",
-  "exec": "ts-node src/server.ts"
+  "exec": "ts-node src/server.ts -- -I",
+  "stdin": false
 }

examples/custom-server/nodemon.json

@@ -1,5 +1,6 @@
 {
   "watch": ["server.ts"],
-  "exec": "ts-node --project tsconfig.server.json src/server.ts",
-  "ext": "js ts"
+  "exec": "ts-node --project tsconfig.server.json src/server.ts -- -I",
+  "ext": "js ts",
+  "stdin": false
 }

examples/draft-preview/payload/nodemon.json

@@ -1,4 +1,5 @@
 {
   "ext": "ts",
-  "exec": "ts-node src/server.ts"
+  "exec": "ts-node src/server.ts -- -I",
+  "stdin": false
 }

examples/email/nodemon.json

@@ -1,4 +1,5 @@
 {
   "ext": "ts",
-  "exec": "ts-node src/server.ts"
+  "exec": "ts-node src/server.ts -- -I",
+  "stdin": false
 }

examples/form-builder/payload/nodemon.json

@@ -1,4 +1,5 @@
 {
   "ext": "ts",
-  "exec": "ts-node src/server.ts"
+  "exec": "ts-node src/server.ts -- -I",
+  "stdin": false
 }

examples/live-preview/payload/src/collections/Pages/index.ts

@@ -10,7 +10,8 @@ export const Pages: CollectionConfig = {
     useAsTitle: 'title',
     defaultColumns: ['title', 'slug', 'updatedAt'],
     livePreview: {
-      url: ({ data }) => `${process.env.PAYLOAD_PUBLIC_SITE_URL}/${data.slug}`,
+      url: ({ data }) =>
+        `${process.env.PAYLOAD_PUBLIC_SITE_URL}${data.slug !== 'home' ? `/${data.slug}` : ''}`,
     },
   },
   access: {

examples/multi-tenant/nodemon.json

@@ -1,4 +1,5 @@
 {
   "ext": "ts",
-  "exec": "ts-node src/server.ts"
+  "exec": "ts-node src/server.ts -- -I",
+  "stdin": false
 }

examples/redirects/payload/nodemon.json

@@ -1,4 +1,5 @@
 {
   "ext": "ts",
-  "exec": "ts-node src/server.ts"
+  "exec": "ts-node src/server.ts -- -I",
+  "stdin": false
 }

examples/virtual-fields/nodemon.json

@@ -1,4 +1,5 @@
 {
   "ext": "ts",
-  "exec": "ts-node src/server.ts"
+  "exec": "ts-node src/server.ts -- -I",
+  "stdin": false
 }

examples/whitelabel/nodemon.json

@@ -1,4 +1,5 @@
 {
   "ext": "ts",
-  "exec": "ts-node src/server.ts"
+  "exec": "ts-node src/server.ts -- -I",
+  "stdin": false
 }

package.json

@@ -20,8 +20,8 @@
     "lint-staged": "lint-staged",
     "pretest": "pnpm build",
     "reinstall": "pnpm clean:unix && pnpm install",
-    "list:packages": "./scripts/list_published_packages.sh beta",
-    "script:release:beta": "./scripts/release_beta.sh",
+    "script:list-packages": "tsx ./scripts/list-packages.ts",
+    "script:release": "tsx ./scripts/release.ts",
     "test": "pnpm test:int && pnpm test:components && pnpm test:e2e",
     "test:components": "cross-env jest --config=jest.components.config.js",
     "test:e2e": "npx playwright install --with-deps && ts-node -T ./test/runE2E.ts",
@@ -50,6 +50,7 @@
     "@types/shelljs": "0.8.12",
     "@types/testing-library__jest-dom": "5.14.8",
     "chalk": "^5.3.0",
+    "chalk-template": "1.1.0",
     "copyfiles": "2.4.1",
     "cross-env": "7.0.3",
     "dotenv": "8.6.0",
@@ -58,7 +59,6 @@
     "fs-extra": "10.1.0",
     "get-port": "5.1.1",
     "glob": "8.1.0",
-    "graphql-request": "6.1.0",
     "husky": "^8.0.3",
     "isomorphic-fetch": "3.0.0",
     "jest": "29.6.4",
@@ -74,9 +74,11 @@
     "qs": "6.11.2",
     "rimraf": "3.0.2",
     "shelljs": "0.8.5",
+    "simple-git": "^3.20.0",
     "slash": "3.0.0",
     "slate": "0.91.4",
     "ts-node": "10.9.1",
+    "tsx": "^3.13.0",
     "turbo": "^1.10.15",
     "typescript": "5.2.2",
     "uuid": "^9.0.0"

packages/bundler-webpack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/bundler-webpack",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "The officially supported Webpack bundler adapter for Payload",
   "repository": "https://github.com/payloadcms/payload",
   "license": "MIT",
@@ -25,6 +25,7 @@
     "css-loader": "5.2.7",
     "css-minimizer-webpack-plugin": "^5.0.0",
     "file-loader": "6.2.0",
+    "find-node-modules": "^2.1.3",
     "html-webpack-plugin": "^5.5.0",
     "md5": "2.3.0",
     "mini-css-extract-plugin": "1.6.2",
@@ -48,6 +49,7 @@
   "devDependencies": {
     "@payloadcms/eslint-config": "workspace:*",
     "@types/extract-text-webpack-plugin": "^3.0.7",
+    "@types/find-node-modules": "^2.1.0",
     "@types/html-webpack-plugin": "^3.2.6",
     "@types/mini-css-extract-plugin": "^1.4.3",
     "@types/optimize-css-assets-webpack-plugin": "^5.0.5",

packages/bundler-webpack/src/configs/base.ts

@@ -1,6 +1,7 @@
 import type { SanitizedConfig } from 'payload/config'
 import type { Configuration } from 'webpack'
 
+import findNodeModules from 'find-node-modules'
 import HtmlWebpackPlugin from 'html-webpack-plugin'
 import path from 'path'
 import webpack from 'webpack'
@@ -8,7 +9,8 @@ import webpack from 'webpack'
 const mockModulePath = path.resolve(__dirname, '../mocks/emptyModule.js')
 const mockDotENVPath = path.resolve(__dirname, '../mocks/dotENV.js')
 
-const nodeModulesPath = path.resolve(__dirname, '../../../../')
+const nodeModulesPaths = findNodeModules({ cwd: process.cwd() })
+const nodeModulesPath = path.resolve(nodeModulesPaths[0])
 const adminFolderPath = path.resolve(nodeModulesPath, 'payload/dist/admin')
 
 export const getBaseConfig = (payloadConfig: SanitizedConfig): Configuration => ({

packages/bundler-webpack/src/configs/dev.ts

@@ -23,7 +23,9 @@ export const getDevConfig = (payloadConfig: SanitizedConfig): Configuration => {
     entry: {
       ...baseConfig.entry,
       main: [
-        `webpack-hot-middleware/client?path=${payloadConfig.routes.admin}/__webpack_hmr`,
+        `${require.resolve('webpack-hot-middleware/client')}?path=${
+          payloadConfig.routes.admin
+        }/__webpack_hmr`,
         ...(baseConfig.entry.main as string[]),
       ],
     },

packages/create-payload-app/.eslintrc.js

@@ -0,0 +1,44 @@
+/** @type {import('prettier').Config} */
+module.exports = {
+  extends: ['@payloadcms'],
+  ignorePatterns: ['README.md', '**/*.spec.ts'],
+  overrides: [
+    {
+      extends: ['plugin:@typescript-eslint/disable-type-checked'],
+      files: ['*.js', '*.cjs', '*.json', '*.md', '*.yml', '*.yaml'],
+    },
+    {
+      files: ['**/*.ts', '**/*.tsx'],
+      rules: {
+        'no-console': 'off',
+      },
+    },
+    {
+      files: ['package.json', 'tsconfig.json'],
+      rules: {
+        'perfectionist/sort-array-includes': 'off',
+        'perfectionist/sort-astro-attributes': 'off',
+        'perfectionist/sort-classes': 'off',
+        'perfectionist/sort-enums': 'off',
+        'perfectionist/sort-exports': 'off',
+        'perfectionist/sort-imports': 'off',
+        'perfectionist/sort-interfaces': 'off',
+        'perfectionist/sort-jsx-props': 'off',
+        'perfectionist/sort-keys': 'off',
+        'perfectionist/sort-maps': 'off',
+        'perfectionist/sort-named-exports': 'off',
+        'perfectionist/sort-named-imports': 'off',
+        'perfectionist/sort-object-types': 'off',
+        'perfectionist/sort-objects': 'off',
+        'perfectionist/sort-svelte-attributes': 'off',
+        'perfectionist/sort-union-types': 'off',
+        'perfectionist/sort-vue-attributes': 'off',
+      },
+    },
+  ],
+  parserOptions: {
+    project: ['./tsconfig.json'],
+    tsconfigRootDir: __dirname,
+  },
+  root: true,
+}

packages/create-payload-app/README.md

@@ -0,0 +1,34 @@
+# Create Payload App
+
+CLI for easily starting new Payload project
+
+## Usage
+
+```text
+
+  USAGE
+
+      $ npx create-payload-app
+      $ npx create-payload-app my-project
+      $ npx create-payload-app -n my-project -t blog
+
+  OPTIONS
+
+      -n     my-payload-app         Set project name
+      -t     template_name          Choose specific template
+
+        Available templates:
+
+        blank                       Blank Template
+        website                     Website Template
+        ecommerce                   E-commerce Template
+        plugin                      Template for creating a Payload plugin
+        payload-demo                Payload demo site at https://demo.payloadcms.com
+        payload-website             Payload website CMS at https://payloadcms.com
+
+      --use-npm                     Use npm to install dependencies
+      --use-yarn                    Use yarn to install dependencies
+      --use-pnpm                    Use pnpm to install dependencies
+      --no-deps                     Do not install any dependencies
+      -h                            Show help
+```

packages/create-payload-app/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/index.js')

packages/create-payload-app/jest.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/src/**/?(*.)+(spec|test|it-test).[tj]s?(x)'],
+  testTimeout: 10000,
+  transform: {
+    '^.+\\.(ts|tsx)?$': 'ts-jest',
+  },
+  verbose: true,
+}

packages/create-payload-app/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "create-payload-app",
+  "version": "0.5.2",
+  "license": "MIT",
+  "bin": {
+    "create-payload-app": "bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc && pnpm copyfiles",
+    "copyfiles": "copyfiles -u 1 \"src/templates/**\" \"src/lib/common-files/**\" dist",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "lint-staged": "lint-staged --quiet",
+    "test": "jest",
+    "prepublishOnly": "pnpm test && pnpm clean && pnpm build"
+  },
+  "files": [
+    "package.json",
+    "dist",
+    "bin"
+  ],
+  "dependencies": {
+    "@sindresorhus/slugify": "^1.1.0",
+    "arg": "^5.0.0",
+    "chalk": "^4.1.0",
+    "command-exists": "^1.2.9",
+    "degit": "^2.8.4",
+    "execa": "^5.0.0",
+    "figures": "^3.2.0",
+    "fs-extra": "^9.0.1",
+    "handlebars": "^4.7.7",
+    "ora": "^5.1.0",
+    "prompts": "^2.4.2",
+    "terminal-link": "^2.1.1"
+  },
+  "devDependencies": {
+    "@types/command-exists": "^1.2.0",
+    "@types/degit": "^2.8.3",
+    "@types/fs-extra": "^9.0.12",
+    "@types/jest": "^27.0.3",
+    "@types/node": "^16.6.2",
+    "@types/prompts": "^2.4.1",
+    "ts-jest": "^29.1.0"
+  }
+}

packages/create-payload-app/src/index.ts

@@ -0,0 +1,8 @@
+import { Main } from './main'
+import { error } from './utils/log'
+
+async function main(): Promise<void> {
+  await new Main().init()
+}
+
+main().catch((e) => error(`An error has occurred: ${e instanceof Error ? e.message : e}`))

packages/create-payload-app/src/lib/configure-payload-config.ts

@@ -0,0 +1,117 @@
+import fse from 'fs-extra'
+import path from 'path'
+
+import type { DbDetails } from '../types'
+
+import { warning } from '../utils/log'
+import { bundlerPackages, dbPackages, editorPackages } from './packages'
+
+/** Update payload config with necessary imports and adapters */
+export async function configurePayloadConfig(args: {
+  dbDetails: DbDetails | undefined
+  projectDir: string
+}): Promise<void> {
+  if (!args.dbDetails) {
+    return
+  }
+
+  // Update package.json
+  const packageJsonPath = path.resolve(args.projectDir, 'package.json')
+  try {
+    const packageObj = await fse.readJson(packageJsonPath)
+
+    packageObj.dependencies['payload'] = '^2.0.0'
+
+    const dbPackage = dbPackages[args.dbDetails.type]
+    const bundlerPackage = bundlerPackages['webpack']
+    const editorPackage = editorPackages['slate']
+
+    // Delete all other db adapters
+    Object.values(dbPackages).forEach((p) => {
+      if (p.packageName !== dbPackage.packageName) {
+        delete packageObj.dependencies[p.packageName]
+      }
+    })
+
+    packageObj.dependencies[dbPackage.packageName] = dbPackage.version
+    packageObj.dependencies[bundlerPackage.packageName] = bundlerPackage.version
+    packageObj.dependencies[editorPackage.packageName] = editorPackage.version
+
+    await fse.writeJson(packageJsonPath, packageObj, { spaces: 2 })
+  } catch (err: unknown) {
+    warning('Unable to update name in package.json')
+  }
+
+  try {
+    const possiblePaths = [
+      path.resolve(args.projectDir, 'src/payload.config.ts'),
+      path.resolve(args.projectDir, 'src/payload/payload.config.ts'),
+    ]
+
+    let payloadConfigPath: string | undefined
+
+    possiblePaths.forEach((p) => {
+      if (fse.pathExistsSync(p) && !payloadConfigPath) {
+        payloadConfigPath = p
+      }
+    })
+
+    if (!payloadConfigPath) {
+      warning('Unable to update payload.config.ts with plugins')
+      return
+    }
+
+    const configContent = fse.readFileSync(payloadConfigPath, 'utf-8')
+    const configLines = configContent.split('\n')
+
+    const dbReplacement = dbPackages[args.dbDetails.type]
+    const bundlerReplacement = bundlerPackages['webpack']
+    const editorReplacement = editorPackages['slate']
+
+    let dbConfigStartLineIndex: number | undefined
+    let dbConfigEndLineIndex: number | undefined
+
+    configLines.forEach((l, i) => {
+      if (l.includes('// database-adapter-import')) {
+        configLines[i] = dbReplacement.importReplacement
+      }
+      if (l.includes('// bundler-import')) {
+        configLines[i] = bundlerReplacement.importReplacement
+      }
+
+      if (l.includes('// bundler-config')) {
+        configLines[i] = bundlerReplacement.configReplacement
+      }
+
+      if (l.includes('// editor-import')) {
+        configLines[i] = editorReplacement.importReplacement
+      }
+
+      if (l.includes('// editor-config')) {
+        configLines[i] = editorReplacement.configReplacement
+      }
+
+      if (l.includes('// database-adapter-config-start')) {
+        dbConfigStartLineIndex = i
+      }
+      if (l.includes('// database-adapter-config-end')) {
+        dbConfigEndLineIndex = i
+      }
+    })
+
+    if (!dbConfigStartLineIndex || !dbConfigEndLineIndex) {
+      warning('Unable to update payload.config.ts with database adapter import')
+    } else {
+      // Replaces lines between `// database-adapter-config-start` and `// database-adapter-config-end`
+      configLines.splice(
+        dbConfigStartLineIndex,
+        dbConfigEndLineIndex - dbConfigStartLineIndex + 1,
+        ...dbReplacement.configReplacement,
+      )
+    }
+
+    fse.writeFileSync(payloadConfigPath, configLines.join('\n'))
+  } catch (err: unknown) {
+    warning('Unable to update payload.config.ts with plugins')
+  }
+}

packages/create-payload-app/src/lib/create-project.spec.ts

@@ -0,0 +1,151 @@
+import fse from 'fs-extra'
+import path from 'path'
+import type { BundlerType, CliArgs, DbType, ProjectTemplate } from '../types'
+import { createProject } from './create-project'
+import { bundlerPackages, dbPackages, editorPackages } from './packages'
+import exp from 'constants'
+
+const projectDir = path.resolve(__dirname, './tmp')
+describe('createProject', () => {
+  beforeAll(() => {
+    console.log = jest.fn()
+  })
+
+  beforeEach(() => {
+    if (fse.existsSync(projectDir)) {
+      fse.rmdirSync(projectDir, { recursive: true })
+    }
+  })
+  afterEach(() => {
+    if (fse.existsSync(projectDir)) {
+      fse.rmSync(projectDir, { recursive: true })
+    }
+  })
+
+  describe('#createProject', () => {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const args = {
+      _: ['project-name'],
+      '--db': 'mongodb',
+      '--no-deps': true,
+    } as CliArgs
+    const packageManager = 'yarn'
+
+    it('creates starter project', async () => {
+      const projectName = 'starter-project'
+      const template: ProjectTemplate = {
+        name: 'blank',
+        type: 'starter',
+        url: 'https://github.com/payloadcms/payload/templates/blank',
+        description: 'Blank Template',
+      }
+      await createProject({
+        cliArgs: args,
+        projectName,
+        projectDir,
+        template,
+        packageManager,
+      })
+
+      const packageJsonPath = path.resolve(projectDir, 'package.json')
+      const packageJson = fse.readJsonSync(packageJsonPath)
+
+      // Check package name and description
+      expect(packageJson.name).toEqual(projectName)
+    })
+
+    it('creates plugin template', async () => {
+      const projectName = 'plugin'
+      const template: ProjectTemplate = {
+        name: 'plugin',
+        type: 'plugin',
+        url: 'https://github.com/payloadcms/payload-plugin-template',
+        description: 'Template for creating a Payload plugin',
+      }
+      await createProject({
+        cliArgs: args,
+        projectName,
+        projectDir,
+        template,
+        packageManager,
+      })
+
+      const packageJsonPath = path.resolve(projectDir, 'package.json')
+      const packageJson = fse.readJsonSync(packageJsonPath)
+
+      // Check package name and description
+      expect(packageJson.name).toEqual(projectName)
+    })
+
+    describe('db adapters and bundlers', () => {
+      it.each([
+        ['mongodb', 'webpack'],
+        ['postgres', 'webpack'],
+      ])('update config and deps: %s, %s', async (db, bundler) => {
+        const projectName = 'starter-project'
+        const template: ProjectTemplate = {
+          name: 'blank',
+          type: 'starter',
+          url: 'https://github.com/payloadcms/payload/templates/blank',
+          description: 'Blank Template',
+        }
+        await createProject({
+          cliArgs: args,
+          projectName,
+          projectDir,
+          template,
+          packageManager,
+          dbDetails: {
+            dbUri: `${db}://localhost:27017/create-project-test`,
+            type: db as DbType,
+          },
+        })
+
+        const dbReplacement = dbPackages[db as DbType]
+        const bundlerReplacement = bundlerPackages[bundler as BundlerType]
+        const editorReplacement = editorPackages['slate']
+
+        const packageJsonPath = path.resolve(projectDir, 'package.json')
+        const packageJson = fse.readJsonSync(packageJsonPath)
+
+        // Check deps
+        expect(packageJson.dependencies['payload']).toEqual('^2.0.0')
+        expect(packageJson.dependencies[dbReplacement.packageName]).toEqual(dbReplacement.version)
+
+        // Should only have one db adapter
+        expect(
+          Object.keys(packageJson.dependencies).filter((n) => n.startsWith('@payloadcms/db-')),
+        ).toHaveLength(1)
+
+        expect(packageJson.dependencies[bundlerReplacement.packageName]).toEqual(
+          bundlerReplacement.version,
+        )
+        expect(packageJson.dependencies[editorReplacement.packageName]).toEqual(
+          editorReplacement.version,
+        )
+
+        const payloadConfigPath = path.resolve(projectDir, 'src/payload.config.ts')
+        const content = fse.readFileSync(payloadConfigPath, 'utf-8')
+
+        // Check payload.config.ts
+        expect(content).not.toContain('// database-adapter-import')
+        expect(content).toContain(dbReplacement.importReplacement)
+
+        expect(content).not.toContain('// database-adapter-config-start')
+        expect(content).not.toContain('// database-adapter-config-end')
+        expect(content).toContain(dbReplacement.configReplacement.join('\n'))
+
+        expect(content).not.toContain('// bundler-config-import')
+        expect(content).toContain(bundlerReplacement.importReplacement)
+
+        expect(content).not.toContain('// bundler-config')
+        expect(content).toContain(bundlerReplacement.configReplacement)
+      })
+    })
+  })
+
+  describe('Templates', () => {
+    it.todo('Verify that all templates are valid')
+    // Loop through all templates.ts that should have replacement comments, and verify that they are present
+  })
+})

packages/create-payload-app/src/lib/create-project.ts

@@ -0,0 +1,102 @@
+import chalk from 'chalk'
+import degit from 'degit'
+import execa from 'execa'
+import fse from 'fs-extra'
+import ora from 'ora'
+import path from 'path'
+
+import type { CliArgs, DbDetails, PackageManager, ProjectTemplate } from '../types'
+
+import { error, success, warning } from '../utils/log'
+import { configurePayloadConfig } from './configure-payload-config'
+
+async function createOrFindProjectDir(projectDir: string): Promise<void> {
+  const pathExists = await fse.pathExists(projectDir)
+  if (!pathExists) {
+    await fse.mkdir(projectDir)
+  }
+}
+
+async function installDeps(args: {
+  cliArgs: CliArgs
+  packageManager: PackageManager
+  projectDir: string
+}): Promise<boolean> {
+  const { cliArgs, packageManager, projectDir } = args
+  if (cliArgs['--no-deps']) {
+    return true
+  }
+  let installCmd = 'npm install --legacy-peer-deps'
+
+  if (packageManager === 'yarn') {
+    installCmd = 'yarn'
+  } else if (packageManager === 'pnpm') {
+    installCmd = 'pnpm install'
+  }
+
+  try {
+    await execa.command(installCmd, {
+      cwd: path.resolve(projectDir),
+    })
+    return true
+  } catch (err: unknown) {
+    console.log({ err })
+    return false
+  }
+}
+
+export async function createProject(args: {
+  cliArgs: CliArgs
+  dbDetails?: DbDetails
+  packageManager: PackageManager
+  projectDir: string
+  projectName: string
+  template: ProjectTemplate
+}): Promise<void> {
+  const { cliArgs, dbDetails, packageManager, projectDir, projectName, template } = args
+
+  await createOrFindProjectDir(projectDir)
+
+  console.log(`\n  Creating project in ${chalk.green(path.resolve(projectDir))}\n`)
+
+  if ('url' in template) {
+    const emitter = degit(template.url)
+    await emitter.clone(projectDir)
+  }
+
+  const spinner = ora('Checking latest Payload version...').start()
+
+  await updatePackageJSON({ projectDir, projectName })
+  await configurePayloadConfig({ dbDetails, projectDir })
+
+  // Remove yarn.lock file. This is only desired in Payload Cloud.
+  const lockPath = path.resolve(projectDir, 'yarn.lock')
+  if (fse.existsSync(lockPath)) {
+    await fse.remove(lockPath)
+  }
+
+  spinner.text = 'Installing dependencies...'
+  const result = await installDeps({ cliArgs, packageManager, projectDir })
+  spinner.stop()
+  spinner.clear()
+  if (result) {
+    success('Dependencies installed')
+  } else {
+    error('Error installing dependencies')
+  }
+}
+
+export async function updatePackageJSON(args: {
+  projectDir: string
+  projectName: string
+}): Promise<void> {
+  const { projectDir, projectName } = args
+  const packageJsonPath = path.resolve(projectDir, 'package.json')
+  try {
+    const packageObj = await fse.readJson(packageJsonPath)
+    packageObj.name = projectName
+    await fse.writeJson(packageJsonPath, packageObj, { spaces: 2 })
+  } catch (err: unknown) {
+    warning('Unable to update name in package.json')
+  }
+}

packages/create-payload-app/src/lib/generate-secret.ts

@@ -0,0 +1,5 @@
+import { randomBytes } from 'crypto'
+
+export function generateSecret(): string {
+  return randomBytes(32).toString('hex').slice(0, 24)
+}

packages/create-payload-app/src/lib/packages.ts

@@ -0,0 +1,83 @@
+import type { BundlerType, DbType, EditorType } from '../types'
+
+type DbAdapterReplacement = {
+  configReplacement: string[]
+  importReplacement: string
+  packageName: string
+  version: string
+}
+
+type BundlerReplacement = {
+  configReplacement: string
+  importReplacement: string
+  packageName: string
+  version: string
+}
+
+type EditorReplacement = {
+  configReplacement: string
+  importReplacement: string
+  packageName: string
+  version: string
+}
+
+const mongodbReplacement: DbAdapterReplacement = {
+  importReplacement: "import { mongooseAdapter } from '@payloadcms/db-mongodb'",
+  packageName: '@payloadcms/db-mongodb',
+  // Replacement between `// database-adapter-config-start` and `// database-adapter-config-end`
+  configReplacement: ['  db: mongooseAdapter({', '    url: process.env.DATABASE_URI,', '  }),'],
+  version: '^1.0.0',
+}
+
+const postgresReplacement: DbAdapterReplacement = {
+  configReplacement: [
+    '  db: postgresAdapter({',
+    '    pool: {',
+    '      connectionString: process.env.DATABASE_URI,',
+    '    },',
+    '  }),',
+  ],
+  importReplacement: "import { postgresAdapter } from '@payloadcms/db-postgres'",
+  packageName: '@payloadcms/db-postgres',
+  version: '^0.x', // up to, not including 1.0.0
+}
+
+export const dbPackages: Record<DbType, DbAdapterReplacement> = {
+  mongodb: mongodbReplacement,
+  postgres: postgresReplacement,
+}
+
+const webpackReplacement: BundlerReplacement = {
+  importReplacement: "import { webpackBundler } from '@payloadcms/bundler-webpack'",
+  packageName: '@payloadcms/bundler-webpack',
+  // Replacement of line containing `// bundler-config`
+  configReplacement: '    bundler: webpackBundler(),',
+  version: '^1.0.0',
+}
+
+const viteReplacement: BundlerReplacement = {
+  configReplacement: '  bundler: viteBundler(),',
+  importReplacement: "import { viteBundler } from '@payloadcms/bundler-vite'",
+  packageName: '@payloadcms/bundler-vite',
+  version: '^0.x', // up to, not including 1.0.0
+}
+
+export const bundlerPackages: Record<BundlerType, BundlerReplacement> = {
+  vite: viteReplacement,
+  webpack: webpackReplacement,
+}
+
+export const editorPackages: Record<EditorType, EditorReplacement> = {
+  lexical: {
+    configReplacement: '  editor: lexicalEditor({}),',
+    importReplacement: "import { lexicalEditor } from '@payloadcms/richtext-lexical'",
+    packageName: '@payloadcms/richtext-lexical',
+    version: '^0.x', // up to, not including 1.0.0
+  },
+  slate: {
+    configReplacement: '  editor: slateEditor({}),',
+    importReplacement: "import { slateEditor } from '@payloadcms/richtext-slate'",
+    packageName: '@payloadcms/richtext-slate',
+    version: '^1.0.0',
+  },
+}

packages/create-payload-app/src/lib/parse-project-name.ts

@@ -0,0 +1,24 @@
+import prompts from 'prompts'
+
+import type { CliArgs } from '../types'
+
+export async function parseProjectName(args: CliArgs): Promise<string> {
+  if (args['--name']) return args['--name']
+  if (args._[0]) return args._[0]
+
+  const response = await prompts(
+    {
+      name: 'value',
+      message: 'Project name?',
+      type: 'text',
+      validate: (value: string) => !!value.length,
+    },
+    {
+      onCancel: () => {
+        process.exit(0)
+      },
+    },
+  )
+
+  return response.value
+}

packages/create-payload-app/src/lib/parse-template.ts

@@ -0,0 +1,41 @@
+import prompts from 'prompts'
+
+import type { CliArgs, ProjectTemplate } from '../types'
+
+export async function parseTemplate(
+  args: CliArgs,
+  validTemplates: ProjectTemplate[],
+): Promise<ProjectTemplate> {
+  if (args['--template']) {
+    const templateName = args['--template']
+    const template = validTemplates.find((t) => t.name === templateName)
+    if (!template) throw new Error('Invalid template given')
+    return template
+  }
+
+  const response = await prompts(
+    {
+      name: 'value',
+      choices: validTemplates.map((p) => {
+        return {
+          description: p.description,
+          title: p.name,
+          value: p.name,
+        }
+      }),
+      message: 'Choose project template',
+      type: 'select',
+      validate: (value: string) => !!value.length,
+    },
+    {
+      onCancel: () => {
+        process.exit(0)
+      },
+    },
+  )
+
+  const template = validTemplates.find((t) => t.name === response.value)
+  if (!template) throw new Error('Template is undefined')
+
+  return template
+}

packages/create-payload-app/src/lib/select-db.ts

@@ -0,0 +1,86 @@
+import slugify from '@sindresorhus/slugify'
+import prompts from 'prompts'
+
+import type { CliArgs, DbDetails, DbType } from '../types'
+
+type DbChoice = {
+  dbConnectionPrefix: `${string}/`
+  title: string
+  value: DbType
+}
+
+const dbChoiceRecord: Record<DbType, DbChoice> = {
+  mongodb: {
+    dbConnectionPrefix: 'mongodb://127.0.0.1/',
+    title: 'MongoDB',
+    value: 'mongodb',
+  },
+  postgres: {
+    dbConnectionPrefix: 'postgres://127.0.0.1:5432/',
+    title: 'PostgreSQL (beta)',
+    value: 'postgres',
+  },
+}
+
+export async function selectDb(args: CliArgs, projectName: string): Promise<DbDetails> {
+  let dbType: DbType | undefined = undefined
+  if (args['--db']) {
+    if (!Object.values(dbChoiceRecord).some((dbChoice) => dbChoice.value === args['--db'])) {
+      throw new Error(
+        `Invalid database type given. Valid types are: ${Object.values(dbChoiceRecord)
+          .map((dbChoice) => dbChoice.value)
+          .join(', ')}`,
+      )
+    }
+    dbType = args['--db'] as DbType
+  } else {
+    const dbTypeRes = await prompts(
+      {
+        name: 'value',
+        choices: Object.values(dbChoiceRecord).map((dbChoice) => {
+          return {
+            title: dbChoice.title,
+            value: dbChoice.value,
+          }
+        }),
+        message: 'Select a database',
+        type: 'select',
+        validate: (value: string) => !!value.length,
+      },
+      {
+        onCancel: () => {
+          process.exit(0)
+        },
+      },
+    )
+    dbType = dbTypeRes.value
+  }
+
+  const dbChoice = dbChoiceRecord[dbType]
+
+  const dbUriRes = await prompts(
+    {
+      name: 'value',
+      initial: `${dbChoice.dbConnectionPrefix}${
+        projectName === '.' ? `payload-${getRandomDigitSuffix()}` : slugify(projectName)
+      }`,
+      message: `Enter ${dbChoice.title.split(' ')[0]} connection string`, // strip beta from title
+      type: 'text',
+      validate: (value: string) => !!value.length,
+    },
+    {
+      onCancel: () => {
+        process.exit(0)
+      },
+    },
+  )
+
+  return {
+    dbUri: dbUriRes.value,
+    type: dbChoice.value,
+  }
+}
+
+function getRandomDigitSuffix(): string {
+  return (Math.random() * Math.pow(10, 6)).toFixed(0)
+}

packages/create-payload-app/src/lib/templates.ts

@@ -0,0 +1,54 @@
+import type { ProjectTemplate } from '../types'
+
+import { error, info } from '../utils/log'
+
+export function validateTemplate(templateName: string): boolean {
+  const validTemplates = getValidTemplates()
+  if (!validTemplates.map((t) => t.name).includes(templateName)) {
+    error(`'${templateName}' is not a valid template.`)
+    info(`Valid templates: ${validTemplates.map((t) => t.name).join(', ')}`)
+    return false
+  }
+  return true
+}
+
+export function getValidTemplates(): ProjectTemplate[] {
+  return [
+    {
+      name: 'blank',
+      description: 'Blank Template',
+      type: 'starter',
+      url: 'https://github.com/payloadcms/payload/templates/blank',
+    },
+    {
+      name: 'website',
+      description: 'Website Template',
+      type: 'starter',
+      url: 'https://github.com/payloadcms/payload/templates/website',
+    },
+    {
+      name: 'ecommerce',
+      description: 'E-commerce Template',
+      type: 'starter',
+      url: 'https://github.com/payloadcms/payload/templates/ecommerce',
+    },
+    {
+      name: 'plugin',
+      description: 'Template for creating a Payload plugin',
+      type: 'plugin',
+      url: 'https://github.com/payloadcms/payload-plugin-template',
+    },
+    {
+      name: 'payload-demo',
+      description: 'Payload demo site at https://demo.payloadcms.com',
+      type: 'starter',
+      url: 'https://github.com/payloadcms/public-demo',
+    },
+    {
+      name: 'payload-website',
+      description: 'Payload website CMS at https://payloadcms.com',
+      type: 'starter',
+      url: 'https://github.com/payloadcms/website-cms',
+    },
+  ]
+}

packages/create-payload-app/src/lib/write-env-file.ts

@@ -0,0 +1,55 @@
+import fs from 'fs-extra'
+import path from 'path'
+
+import type { ProjectTemplate } from '../types'
+
+import { error, success } from '../utils/log'
+
+/** Parse and swap .env.example values and write .env */
+export async function writeEnvFile(args: {
+  databaseUri: string
+  payloadSecret: string
+  projectDir: string
+  template: ProjectTemplate
+}): Promise<void> {
+  const { databaseUri, payloadSecret, projectDir, template } = args
+  try {
+    if (template.type === 'starter' && fs.existsSync(path.join(projectDir, '.env.example'))) {
+      // Parse .env file into key/value pairs
+      const envFile = await fs.readFile(path.join(projectDir, '.env.example'), 'utf8')
+      const envWithValues: string[] = envFile
+        .split('\n')
+        .filter((e) => e)
+        .map((line) => {
+          if (line.startsWith('#') || !line.includes('=')) return line
+
+          const split = line.split('=')
+          const key = split[0]
+          let value = split[1]
+
+          if (key === 'MONGODB_URI' || key === 'MONGO_URL' || key === 'DATABASE_URI') {
+            value = databaseUri
+          }
+          if (key === 'PAYLOAD_SECRET' || key === 'PAYLOAD_SECRET_KEY') {
+            value = payloadSecret
+          }
+
+          return `${key}=${value}`
+        })
+
+      // Write new .env file
+      await fs.writeFile(path.join(projectDir, '.env'), envWithValues.join('\n'))
+    } else {
+      const content = `MONGODB_URI=${databaseUri}\nPAYLOAD_SECRET=${payloadSecret}`
+      await fs.outputFile(`${projectDir}/.env`, content)
+    }
+
+    success('.env file created')
+  } catch (err: unknown) {
+    error('Unable to write .env file')
+    if (err instanceof Error) {
+      error(err.message)
+    }
+    process.exit(1)
+  }
+}

packages/create-payload-app/src/main.ts

@@ -0,0 +1,133 @@
+import slugify from '@sindresorhus/slugify'
+import arg from 'arg'
+import commandExists from 'command-exists'
+
+import type { CliArgs, PackageManager } from './types'
+
+import { createProject } from './lib/create-project'
+import { generateSecret } from './lib/generate-secret'
+import { parseProjectName } from './lib/parse-project-name'
+import { parseTemplate } from './lib/parse-template'
+import { selectDb } from './lib/select-db'
+import { getValidTemplates, validateTemplate } from './lib/templates'
+import { writeEnvFile } from './lib/write-env-file'
+import { success } from './utils/log'
+import { helpMessage, successMessage, welcomeMessage } from './utils/messages'
+
+export class Main {
+  args: CliArgs
+
+  constructor() {
+    // @ts-expect-error bad typings
+    this.args = arg(
+      {
+        '--db': String,
+        '--help': Boolean,
+        '--name': String,
+        '--secret': String,
+        '--template': String,
+
+        // Package manager
+        '--no-deps': Boolean,
+        '--use-npm': Boolean,
+        '--use-pnpm': Boolean,
+        '--use-yarn': Boolean,
+
+        // Flags
+        '--beta': Boolean,
+        '--dry-run': Boolean,
+
+        // Aliases
+        '-d': '--db',
+        '-h': '--help',
+        '-n': '--name',
+        '-t': '--template',
+      },
+      { permissive: true },
+    )
+  }
+
+  async init(): Promise<void> {
+    try {
+      if (this.args['--help']) {
+        console.log(helpMessage())
+        process.exit(0)
+      }
+      const templateArg = this.args['--template']
+      if (templateArg) {
+        const valid = validateTemplate(templateArg)
+        if (!valid) {
+          console.log(helpMessage())
+          process.exit(1)
+        }
+      }
+
+      console.log(welcomeMessage)
+      const projectName = await parseProjectName(this.args)
+      const validTemplates = getValidTemplates()
+      const template = await parseTemplate(this.args, validTemplates)
+
+      const projectDir = projectName === '.' ? process.cwd() : `./${slugify(projectName)}`
+      const packageManager = await getPackageManager(this.args)
+
+      if (template.type !== 'plugin') {
+        const dbDetails = await selectDb(this.args, projectName)
+        const payloadSecret = generateSecret()
+        if (!this.args['--dry-run']) {
+          await createProject({
+            cliArgs: this.args,
+            dbDetails,
+            packageManager,
+            projectDir,
+            projectName,
+            template,
+          })
+          await writeEnvFile({
+            databaseUri: dbDetails.dbUri,
+            payloadSecret,
+            projectDir,
+            template,
+          })
+        }
+      } else {
+        if (!this.args['--dry-run']) {
+          await createProject({
+            cliArgs: this.args,
+            packageManager,
+            projectDir,
+            projectName,
+            template,
+          })
+        }
+      }
+
+      success('Payload project successfully created')
+      console.log(successMessage(projectDir, packageManager))
+    } catch (error: unknown) {
+      console.log(error)
+    }
+  }
+}
+
+async function getPackageManager(args: CliArgs): Promise<PackageManager> {
+  let packageManager: PackageManager = 'npm'
+
+  if (args['--use-npm']) {
+    packageManager = 'npm'
+  } else if (args['--use-yarn']) {
+    packageManager = 'yarn'
+  } else if (args['--use-pnpm']) {
+    packageManager = 'pnpm'
+  } else {
+    try {
+      if (await commandExists('yarn')) {
+        packageManager = 'yarn'
+      } else if (await commandExists('pnpm')) {
+        packageManager = 'pnpm'
+      }
+    } catch (error: unknown) {
+      packageManager = 'npm'
+    }
+  }
+  return packageManager
+}

packages/create-payload-app/src/types.ts

@@ -0,0 +1,58 @@
+import type arg from 'arg'
+
+export interface Args extends arg.Spec {
+  '--beta': BooleanConstructor
+  '--db': StringConstructor
+  '--dry-run': BooleanConstructor
+  '--help': BooleanConstructor
+  '--name': StringConstructor
+  '--no-deps': BooleanConstructor
+  '--secret': StringConstructor
+  '--template': StringConstructor
+  '--use-npm': BooleanConstructor
+  '--use-pnpm': BooleanConstructor
+  '--use-yarn': BooleanConstructor
+  '-h': string
+  '-n': string
+  '-t': string
+}
+
+export type CliArgs = arg.Result<Args>
+
+export type ProjectTemplate = GitTemplate | PluginTemplate
+
+/**
+ * Template that is cloned verbatim from a git repo
+ * Performs .env manipulation based upon input
+ */
+export interface GitTemplate extends Template {
+  type: 'starter'
+  url: string
+}
+
+/**
+ * Type specifically for the plugin template
+ * No .env manipulation is done
+ */
+export interface PluginTemplate extends Template {
+  type: 'plugin'
+  url: string
+}
+
+interface Template {
+  description?: string
+  name: string
+  type: ProjectTemplate['type']
+}
+
+export type PackageManager = 'npm' | 'pnpm' | 'yarn'
+
+export type DbType = 'mongodb' | 'postgres'
+
+export type DbDetails = {
+  dbUri: string
+  type: DbType
+}
+
+export type BundlerType = 'vite' | 'webpack'
+export type EditorType = 'lexical' | 'slate'

packages/create-payload-app/src/utils/log.ts

@@ -0,0 +1,18 @@
+import chalk from 'chalk'
+import figures from 'figures'
+
+export const success = (message: string): void => {
+  console.log(`${chalk.green(figures.tick)} ${chalk.bold(message)}`)
+}
+
+export const warning = (message: string): void => {
+  console.log(chalk.yellow('? ') + chalk.bold(message))
+}
+
+export const info = (message: string): void => {
+  console.log(`${chalk.yellow(figures.info)} ${chalk.bold(message)}`)
+}
+
+export const error = (message: string): void => {
+  console.log(`${chalk.red(figures.cross)} ${chalk.bold(message)}`)
+}

packages/create-payload-app/src/utils/messages.ts

@@ -0,0 +1,76 @@
+import chalk from 'chalk'
+import figures from 'figures'
+import path from 'path'
+import terminalLink from 'terminal-link'
+
+import type { ProjectTemplate } from '../types'
+
+import { getValidTemplates } from '../lib/templates'
+
+const header = (message: string): string => `${chalk.yellow(figures.star)} ${chalk.bold(message)}`
+
+export const welcomeMessage = chalk`
+  {green Welcome to Payload. Let's create a project! }
+`
+
+const spacer = ' '.repeat(8)
+
+export function helpMessage(): string {
+  const validTemplates = getValidTemplates()
+  return chalk`
+  {bold USAGE}
+
+      {dim $} {bold npx create-payload-app}
+      {dim $} {bold npx create-payload-app} my-project
+      {dim $} {bold npx create-payload-app} -n my-project -t blog
+
+  {bold OPTIONS}
+
+      -n     {underline my-payload-app}         Set project name
+      -t     {underline template_name}          Choose specific template
+
+        {dim Available templates: ${formatTemplates(validTemplates)}}
+
+      --use-npm                     Use npm to install dependencies
+      --use-yarn                    Use yarn to install dependencies
+      --use-pnpm                    Use pnpm to install dependencies
+      --no-deps                     Do not install any dependencies
+      -h                            Show help
+`
+}
+
+function formatTemplates(templates: ProjectTemplate[]) {
+  return `\n\n${spacer}${templates
+    .map((t) => `${t.name}${' '.repeat(28 - t.name.length)}${t.description}`)
+    .join(`\n${spacer}`)}`
+}
+
+export function successMessage(projectDir: string, packageManager: string): string {
+  return `
+  ${header('Launch Application:')}
+
+    - cd ${projectDir}
+    - ${
+      packageManager === 'yarn' ? 'yarn' : 'npm run'
+    } dev or follow directions in ${createTerminalLink(
+      'README.md',
+      `file://${path.resolve(projectDir, 'README.md')}`,
+    )}
+
+  ${header('Documentation:')}
+
+    - ${createTerminalLink(
+      'Getting Started',
+      'https://payloadcms.com/docs/getting-started/what-is-payload',
+    )}
+    - ${createTerminalLink('Configuration', 'https://payloadcms.com/docs/configuration/overview')}
+
+`
+}
+
+// Create terminalLink with fallback for unsupported terminals
+function createTerminalLink(text: string, url: string) {
+  return terminalLink(text, url, {
+    fallback: (text, url) => `${text}: ${url}`,
+  })
+}

packages/create-payload-app/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true, // Make sure typescript knows that this module depends on their references
+    "noEmit": false /* Do not emit outputs. */,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist" /* Specify an output folder for all emitted files. */,
+    "rootDir": "./src" /* Specify the root folder within your source files. */
+  },
+  "exclude": [
+    "dist",
+    "build",
+    "tests",
+    "test",
+    "node_modules",
+    ".eslintrc.js",
+    "src/**/*.spec.js",
+    "src/**/*.spec.jsx",
+    "src/**/*.spec.ts",
+    "src/**/*.spec.tsx"
+  ],
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.d.ts", "src/**/*.json"],
+  "references": [{ "path": "../payload" }]
+}

packages/db-mongodb/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/db-mongodb",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "The officially supported MongoDB database adapter for Payload",
   "repository": "https://github.com/payloadcms/payload",
   "license": "MIT",
@@ -23,7 +23,7 @@
     "bson-objectid": "2.0.4",
     "deepmerge": "4.3.1",
     "get-port": "5.1.1",
-    "mongoose": "6.11.4",
+    "mongoose": "6.12.0",
     "mongoose-aggregate-paginate-v2": "1.0.6",
     "mongoose-paginate-v2": "1.7.22",
     "prompts": "2.4.2",

packages/db-mongodb/src/index.ts

@@ -68,7 +68,9 @@ export type MongooseAdapter = BaseDatabaseAdapter &
 type MongooseAdapterResult = (args: { payload: Payload }) => MongooseAdapter
 
 declare module 'payload' {
-  export interface DatabaseAdapter extends Args {
+  export interface DatabaseAdapter
+    extends Omit<BaseDatabaseAdapter, 'sessions'>,
+      Omit<Args, 'migrationDir'> {
     collections: {
       [slug: string]: CollectionModel
     }

packages/db-postgres/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/db-postgres",
-  "version": "0.1.1",
+  "version": "0.1.5",
   "description": "The officially supported Postgres database adapter for Payload",
   "repository": "https://github.com/payloadcms/payload",
   "license": "MIT",

packages/db-postgres/src/connect.ts

@@ -1,6 +1,5 @@
 import type { Connect } from 'payload/database'
 
-import { pushSchema } from 'drizzle-kit/utils'
 import { eq, sql } from 'drizzle-orm'
 import { drizzle } from 'drizzle-orm/node-postgres'
 import { numeric, pgTable, timestamp, varchar } from 'drizzle-orm/pg-core'
@@ -40,6 +39,8 @@ export const connect: Connect = async function connect(this: PostgresAdapter, pa
   )
     return
 
+  const { pushSchema } = require('drizzle-kit/utils')
+
   // This will prompt if clarifications are needed for Drizzle to push new schema
   const { apply, hasDataLoss, statementsToExecute, warnings } = await pushSchema(
     this.schema,

packages/db-postgres/src/createMigration.ts

@@ -2,7 +2,6 @@
 import type { DrizzleSnapshotJSON } from 'drizzle-kit/utils'
 import type { CreateMigration } from 'payload/database'
 
-import { generateDrizzleJson, generateMigration } from 'drizzle-kit/utils'
 import fs from 'fs'
 import prompts from 'prompts'
 
@@ -61,6 +60,8 @@ export const createMigration: CreateMigration = async function createMigration(
     fs.mkdirSync(dir)
   }
 
+  const { generateDrizzleJson, generateMigration } = require('drizzle-kit/utils')
+
   const [yyymmdd, hhmmss] = new Date().toISOString().split('T')
   const formattedDate = yyymmdd.replace(/\D/g, '')
   const formattedTime = hhmmss.split('.')[0].replace(/\D/g, '')

packages/db-postgres/src/find/findMany.ts

@@ -150,7 +150,10 @@ export const findMany = async function find({
     const countResult = await chainMethods({
       methods: selectCountMethods,
       query: db
-        .select({ count: sql<number>`count(*)` })
+        .select({
+          count: sql<number>`count
+              (*)`,
+        })
         .from(table)
         .where(where),
     })

packages/db-postgres/src/init.ts

@@ -24,6 +24,7 @@ export const init: Init = async function init(this: PostgresAdapter) {
     buildTable({
       adapter: this,
       buildRelationships: true,
+      disableNotNull: !!collection?.versions?.drafts,
       disableUnique: false,
       fields: collection.fields,
       tableName,
@@ -37,6 +38,7 @@ export const init: Init = async function init(this: PostgresAdapter) {
       buildTable({
         adapter: this,
         buildRelationships: true,
+        disableNotNull: !!collection.versions?.drafts,
         disableUnique: true,
         fields: versionFields,
         tableName: versionsTableName,
@@ -51,6 +53,7 @@ export const init: Init = async function init(this: PostgresAdapter) {
     buildTable({
       adapter: this,
       buildRelationships: true,
+      disableNotNull: !!global?.versions?.drafts,
       disableUnique: false,
       fields: global.fields,
       tableName,
@@ -64,6 +67,7 @@ export const init: Init = async function init(this: PostgresAdapter) {
       buildTable({
         adapter: this,
         buildRelationships: true,
+        disableNotNull: !!global.versions?.drafts,
         disableUnique: true,
         fields: versionFields,
         tableName: versionsTableName,

packages/db-postgres/src/migrate.ts

@@ -2,9 +2,7 @@
 import type { Payload } from 'payload'
 import type { Migration } from 'payload/database'
 
-import { generateDrizzleJson } from 'drizzle-kit/utils'
 import { readMigrationFiles } from 'payload/database'
-import { DatabaseError } from 'pg'
 import prompts from 'prompts'
 
 import type { PostgresAdapter } from './types'
@@ -78,6 +76,8 @@ export async function migrate(this: PostgresAdapter): Promise<void> {
 }
 
 async function runMigrationFile(payload: Payload, migration: Migration, batch: number) {
+  const { generateDrizzleJson } = require('drizzle-kit/utils')
+
   const start = Date.now()
 
   payload.logger.info({ msg: `Migrating: ${migration.name}` })

packages/db-postgres/src/queries/parseParams.ts

@@ -2,7 +2,7 @@
 import type { SQL } from 'drizzle-orm'
 import type { Field, Operator, Where } from 'payload/types'
 
-import { and, ilike, isNotNull, isNull, ne, or, sql } from 'drizzle-orm'
+import { and, ilike, isNotNull, isNull, ne, notInArray, or, sql } from 'drizzle-orm'
 import { QueryError } from 'payload/errors'
 import { validOperators } from 'payload/types'
 
@@ -147,6 +147,7 @@ export async function parseParams({
                 const { operator: queryOperator, value: queryValue } = sanitizeQueryValue({
                   field,
                   operator,
+                  relationOrPath,
                   val,
                 })
 
@@ -158,6 +159,17 @@ export async function parseParams({
                       ne<any>(rawColumn || table[columnName], queryValue),
                     ),
                   )
+                } else if (
+                  (field.type === 'relationship' || field.type === 'upload') &&
+                  Array.isArray(queryValue) &&
+                  operator === 'not_in'
+                ) {
+                  constraints.push(
+                    sql`${notInArray(table[columnName], queryValue)} OR
+                    ${table[columnName]}
+                    IS
+                    NULL`,
+                  )
                 } else {
                   constraints.push(
                     operatorMap[queryOperator](rawColumn || table[columnName], queryValue),

packages/db-postgres/src/queries/sanitizeQueryValue.ts

@@ -5,12 +5,14 @@ import { createArrayFromCommaDelineated } from 'payload/utilities'
 type SanitizeQueryValueArgs = {
   field: Field | TabAsField
   operator: string
+  relationOrPath: string
   val: any
 }
 
 export const sanitizeQueryValue = ({
   field,
   operator: operatorArg,
+  relationOrPath,
   val,
 }: SanitizeQueryValueArgs): { operator: string; value: unknown } => {
   let operator = operatorArg
@@ -18,6 +20,22 @@ export const sanitizeQueryValue = ({
 
   if (!fieldAffectsData(field)) return { operator, value: formattedValue }
 
+  if (
+    (field.type === 'relationship' || field.type === 'upload') &&
+    !relationOrPath.endsWith('relationTo') &&
+    Array.isArray(formattedValue)
+  ) {
+    const allPossibleIDTypes: (number | string)[] = []
+    formattedValue.forEach((val) => {
+      if (typeof val === 'string') {
+        allPossibleIDTypes.push(val, parseInt(val))
+      } else {
+        allPossibleIDTypes.push(val, String(val))
+      }
+    })
+    formattedValue = allPossibleIDTypes
+  }
+
   // Cast incoming values as proper searchable types
   if (field.type === 'checkbox' && typeof val === 'string') {
     if (val.toLowerCase() === 'true') formattedValue = true

packages/db-postgres/src/reference.ts

@@ -6,11 +6,12 @@
 
 // drizzle-kit@utils
 
-import { generateDrizzleJson, generateMigration, pushSchema } from 'drizzle-kit/utils'
 import { drizzle } from 'drizzle-orm/node-postgres'
 import { Pool } from 'pg'
 
 async function generateUsage() {
+  const { generateDrizzleJson, generateMigration } = require('drizzle-kit/utils')
+
   // @ts-expect-error Just TypeScript being broken // TODO: Open TypeScript issue
   const schema = await import('./data/users')
   // @ts-expect-error Just TypeScript being broken // TODO: Open TypeScript issue
@@ -25,6 +26,8 @@ async function generateUsage() {
 }
 
 async function pushUsage() {
+  const { pushSchema } = require('drizzle-kit/utils')
+
   // @ts-expect-error Just TypeScript being broken // TODO: Open TypeScript issue
   const schemaAfter = await import('./data/users-after')
 

packages/db-postgres/src/schema/build.ts

@@ -27,6 +27,7 @@ type Args = {
   baseColumns?: Record<string, PgColumnBuilder>
   baseExtraConfig?: Record<string, (cols: GenericColumns) => IndexBuilder | UniqueConstraintBuilder>
   buildRelationships?: boolean
+  disableNotNull: boolean
   disableUnique: boolean
   fields: Field[]
   rootRelationsToBuild?: Map<string, string>
@@ -46,6 +47,7 @@ export const buildTable = ({
   baseColumns = {},
   baseExtraConfig = {},
   buildRelationships,
+  disableNotNull,
   disableUnique = false,
   fields,
   rootRelationsToBuild,
@@ -102,6 +104,7 @@ export const buildTable = ({
     adapter,
     buildRelationships,
     columns,
+    disableNotNull,
     disableUnique,
     fields,
     indexes,

packages/db-postgres/src/schema/traverseFields.ts

@@ -34,6 +34,7 @@ type Args = {
   buildRelationships: boolean
   columnPrefix?: string
   columns: Record<string, PgColumnBuilder>
+  disableNotNull: boolean
   disableUnique?: boolean
   fieldPrefix?: string
   fields: (Field | TabAsField)[]
@@ -62,6 +63,7 @@ export const traverseFields = ({
   buildRelationships,
   columnPrefix,
   columns,
+  disableNotNull,
   disableUnique = false,
   fieldPrefix,
   fields,
@@ -174,7 +176,7 @@ export const traverseFields = ({
 
       case 'radio':
       case 'select': {
-        const enumName = `enum_${newTableName}_${columnPrefix || ''}${toSnakeCase(field.name)}`
+        const enumName = `enum_${newTableName}_${toSnakeCase(field.name)}`
 
         adapter.enums[enumName] = pgEnum(
           enumName,
@@ -188,7 +190,7 @@ export const traverseFields = ({
         )
 
         if (field.type === 'select' && field.hasMany) {
-          const selectTableName = `${newTableName}_${toSnakeCase(fieldName)}`
+          const selectTableName = `${newTableName}_${toSnakeCase(field.name)}`
           const baseColumns: Record<string, PgColumnBuilder> = {
             order: integer('order').notNull(),
             parent: parentIDColumnMap[parentIDColType]('parent_id')
@@ -218,6 +220,7 @@ export const traverseFields = ({
             adapter,
             baseColumns,
             baseExtraConfig,
+            disableNotNull,
             disableUnique,
             fields: [],
             tableName: selectTableName,
@@ -274,6 +277,7 @@ export const traverseFields = ({
           adapter,
           baseColumns,
           baseExtraConfig,
+          disableNotNull,
           disableUnique,
           fields: field.fields,
           rootRelationsToBuild,
@@ -339,6 +343,7 @@ export const traverseFields = ({
               adapter,
               baseColumns,
               baseExtraConfig,
+              disableNotNull,
               disableUnique,
               fields: block.fields,
               rootRelationsToBuild,
@@ -399,6 +404,7 @@ export const traverseFields = ({
             buildRelationships,
             columnPrefix,
             columns,
+            disableNotNull,
             disableUnique,
             fieldPrefix,
             fields: field.fields,
@@ -432,6 +438,7 @@ export const traverseFields = ({
           buildRelationships,
           columnPrefix: `${columnName}_`,
           columns,
+          disableNotNull,
           disableUnique,
           fieldPrefix: `${fieldName}_`,
           fields: field.fields,
@@ -466,6 +473,7 @@ export const traverseFields = ({
           buildRelationships,
           columnPrefix,
           columns,
+          disableNotNull,
           disableUnique,
           fieldPrefix,
           fields: field.tabs.map((tab) => ({ ...tab, type: 'tab' })),
@@ -502,6 +510,7 @@ export const traverseFields = ({
           buildRelationships,
           columnPrefix,
           columns,
+          disableNotNull,
           disableUnique,
           fieldPrefix,
           fields: field.fields,
@@ -544,7 +553,13 @@ export const traverseFields = ({
 
     const condition = field.admin && field.admin.condition
 
-    if (targetTable[fieldName] && 'required' in field && field.required && !condition) {
+    if (
+      !disableNotNull &&
+      targetTable[fieldName] &&
+      'required' in field &&
+      field.required &&
+      !condition
+    ) {
       targetTable[fieldName].notNull()
     }
   })

packages/db-postgres/src/types.ts

@@ -69,7 +69,9 @@ export type MigrateUpArgs = { payload: Payload }
 export type MigrateDownArgs = { payload: Payload }
 
 declare module 'payload' {
-  export interface DatabaseAdapter extends Omit<Args, 'pool'> {
+  export interface DatabaseAdapter
+    extends Omit<Args, 'migrationDir' | 'pool'>,
+      BaseDatabaseAdapter {
     drizzle: DrizzleDB
     enums: Record<string, GenericEnum>
     pool: Pool

packages/live-preview-react/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/live-preview-react",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "The official live preview React SDK for Payload",
   "repository": "https://github.com/payloadcms/payload",
   "license": "MIT",

packages/live-preview-react/src/index.ts

@@ -1,5 +1,5 @@
-import { subscribe, unsubscribe } from '@payloadcms/live-preview'
-import { useCallback, useEffect, useState } from 'react'
+import { ready, subscribe, unsubscribe } from '@payloadcms/live-preview'
+import { useCallback, useEffect, useRef, useState } from 'react'
 
 // To prevent the flicker of missing data on initial load,
 // you can pass in the initial page data from the server
@@ -17,6 +17,7 @@ export const useLivePreview = <T extends any>(props: {
   const { depth = 0, initialData, serverURL } = props
   const [data, setData] = useState<T>(initialData)
   const [isLoading, setIsLoading] = useState<boolean>(true)
+  const hasSentReadyMessage = useRef<boolean>(false)
 
   const onChange = useCallback((mergedData) => {
     setData(mergedData)
@@ -31,6 +32,14 @@ export const useLivePreview = <T extends any>(props: {
       serverURL,
     })
 
+    if (!hasSentReadyMessage.current) {
+      hasSentReadyMessage.current = true
+
+      ready({
+        serverURL,
+      })
+    }
+
     return () => {
       unsubscribe(subscription)
     }

packages/live-preview/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/live-preview",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "The official live preview JavaScript SDK for Payload",
   "repository": "https://github.com/payloadcms/payload",
   "license": "MIT",

packages/live-preview/src/handleMessage.ts

@@ -7,11 +7,10 @@ export const handleMessage = async <T>(args: {
   serverURL: string
 }): Promise<T> => {
   const { depth, event, initialData, serverURL } = args
-
   if (event.origin === serverURL && event.data) {
     const eventData = JSON.parse(event?.data)
 
-    if (eventData.type === 'livePreview') {
+    if (eventData.type === 'payload-live-preview') {
       const mergedData = await mergeData<T>({
         depth,
         fieldSchema: eventData.fieldSchemaJSON,

packages/live-preview/src/index.ts

@@ -1,4 +1,5 @@
 export { handleMessage } from './handleMessage'
 export { mergeData } from './mergeData'
+export { ready } from './ready'
 export { subscribe } from './subscribe'
 export { unsubscribe } from './unsubscribe'

packages/live-preview/src/ready.ts

@@ -0,0 +1,15 @@
+export const ready = (args: { serverURL: string }): void => {
+  const { serverURL } = args
+
+  if (typeof window !== 'undefined') {
+    // This subscription may have been from either an iframe `src` or `window.open()`
+    // i.e. `window?.opener` || `window?.parent`
+    window?.opener?.postMessage(
+      JSON.stringify({
+        popupReady: true,
+        type: 'payload-live-preview',
+      }),
+      serverURL,
+    )
+  }
+}

packages/live-preview/src/subscribe.ts

@@ -8,15 +8,14 @@ export const subscribe = <T>(args: {
 }): ((event: MessageEvent) => void) => {
   const { callback, depth, initialData, serverURL } = args
 
-  if (typeof window !== 'undefined') {
-    const handleMessageCallback = async (event: MessageEvent) => {
-      const mergedData = await handleMessage({ depth, event, initialData, serverURL })
-      callback(mergedData)
-    }
-
-    window.addEventListener('message', handleMessageCallback)
-    window.parent.postMessage('ready', serverURL)
-
-    return handleMessageCallback
+  const onMessage = async (event: MessageEvent) => {
+    const mergedData = await handleMessage({ depth, event, initialData, serverURL })
+    callback(mergedData)
   }
+
+  if (typeof window !== 'undefined') {
+    window.addEventListener('message', onMessage)
+  }
+
+  return onMessage
 }

packages/payload/README.md

@@ -26,7 +26,9 @@
 </h4>
 <hr/>
 
-### 🎉 Payload 2.0 is now available! Read more in the [announcement post](https://payloadcms.com/blog/payload-2-0).
+<h3>
+  🎉 Payload 2.0 is now available! Read more in the <a target="_blank" href="https://payloadcms.com/blog/payload-2-0" rel="dofollow"><strong>announcement post</strong></a>
+</h3>
 
 <h3>Benefits over a regular CMS</h3>
 <ul>

packages/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payload",
-  "version": "2.0.3",
+  "version": "2.0.6",
   "description": "Node, React and MongoDB Headless CMS and Application Framework",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -77,7 +77,7 @@
     "flatley": "5.2.0",
     "fs-extra": "10.1.0",
     "get-tsconfig": "4.6.2",
-    "graphql": "16.7.1",
+    "graphql": "16.8.1",
     "graphql-http": "1.21.0",
     "graphql-playground-middleware-express": "1.7.23",
     "graphql-query-complexity": "0.12.0",
@@ -187,7 +187,7 @@
     "file-loader": "6.2.0",
     "form-data": "3.0.1",
     "get-port": "5.1.1",
-    "graphql-request": "3.7.0",
+    "graphql-request": "6.1.0",
     "mini-css-extract-plugin": "1.6.2",
     "node-fetch": "2.6.12",
     "nodemon": "3.0.1",
@@ -208,8 +208,7 @@
     "webpack": "^5.78.0"
   },
   "engines": {
-    "node": ">=14",
-    "pnpm": ">=8"
+    "node": ">=14"
   },
   "files": [
     "bin.js",

packages/payload/src/admin/components/elements/ArrayAction/index.tsx

@@ -66,7 +66,7 @@ export const ArrayAction: React.FC<Props> = ({
                 <PopupList.Button
                   className={`${baseClass}__action ${baseClass}__add`}
                   onClick={() => {
-                    addRow(index)
+                    addRow(index + 1)
                     close()
                   }}
                 >

packages/payload/src/admin/components/elements/DocumentControls/index.tsx

@@ -55,24 +55,6 @@ export const DocumentControls: React.FC<{
 
   const { i18n, t } = useTranslation('general')
 
-  let showPreviewButton = false
-
-  if (collection) {
-    showPreviewButton =
-      isEditing &&
-      collection?.admin?.preview &&
-      collection?.versions?.drafts &&
-      !collection?.versions?.drafts?.autosave
-  }
-
-  if (global) {
-    showPreviewButton =
-      isEditing &&
-      global?.admin?.preview &&
-      global?.versions?.drafts &&
-      !global?.versions?.drafts?.autosave
-  }
-
   const showDotMenu = Boolean(collection && id && !disableActions)
 
   return (
@@ -165,9 +147,12 @@ export const DocumentControls: React.FC<{
         </div>
         <div className={`${baseClass}__controls-wrapper`}>
           <div className={`${baseClass}__controls`}>
-            {showPreviewButton && (
+            {(collection?.admin?.preview || global?.admin?.preview) && (
               <PreviewButton
-                CustomComponent={collection?.admin?.components?.edit?.PreviewButton}
+                CustomComponent={
+                  collection?.admin?.components?.edit?.PreviewButton ||
+                  global?.admin?.components?.elements?.PreviewButton
+                }
                 generatePreviewURL={collection?.admin?.preview || global?.admin?.preview}
               />
             )}
@@ -178,13 +163,26 @@ export const DocumentControls: React.FC<{
                     {((collection?.versions?.drafts && !collection?.versions?.drafts?.autosave) ||
                       (global?.versions?.drafts && !global?.versions?.drafts?.autosave)) && (
                       <SaveDraft
-                        CustomComponent={collection?.admin?.components?.edit?.SaveDraftButton}
+                        CustomComponent={
+                          collection?.admin?.components?.edit?.SaveDraftButton ||
+                          global?.admin?.components?.elements?.SaveDraftButton
+                        }
                       />
                     )}
-                    <Publish CustomComponent={collection?.admin?.components?.edit?.PublishButton} />
+                    <Publish
+                      CustomComponent={
+                        collection?.admin?.components?.edit?.PublishButton ||
+                        global?.admin?.components?.elements?.PublishButton
+                      }
+                    />
                   </React.Fragment>
                 ) : (
-                  <Save CustomComponent={collection?.admin?.components?.edit?.SaveButton} />
+                  <Save
+                    CustomComponent={
+                      collection?.admin?.components?.edit?.SaveButton ||
+                      global?.admin?.components?.elements?.SaveButton
+                    }
+                  />
                 )}
               </React.Fragment>
             )}

packages/payload/src/admin/components/elements/DuplicateDocument/index.tsx

@@ -51,6 +51,7 @@ const Duplicate: React.FC<Props> = ({ id, collection, slug }) => {
           },
           params: {
             depth: 0,
+            draft: true,
             locale,
           },
         })

packages/payload/src/admin/components/elements/StepNav/index.tsx

@@ -54,13 +54,12 @@ const StepNav: React.FC<{
       )}
       {stepNav.map((item, i) => {
         const StepLabel = <span key={i}>{getTranslation(item.label, i18n)}</span>
-
         const Step =
           stepNav.length === i + 1 ? (
             StepLabel
           ) : (
             <Fragment key={i}>
-              <Link to={item.url}>{StepLabel}</Link>
+              {item.url ? <Link to={item.url}>{StepLabel}</Link> : StepLabel}
               <span>/</span>
             </Fragment>
           )

packages/payload/src/admin/components/forms/Form/buildStateFromSchema/addFieldStatePromise.ts

@@ -61,6 +61,7 @@ export const addFieldStatePromise = async ({
       user,
       value: data?.[field.name],
     })
+
     if (data?.[field.name]) {
       data[field.name] = valueWithDefault
     }
@@ -145,8 +146,8 @@ export const addFieldStatePromise = async ({
           fieldState.value = null
           fieldState.initialValue = null
         } else {
-          fieldState.value = arrayValue
-          fieldState.initialValue = arrayValue
+          fieldState.value = arrayValue.length
+          fieldState.initialValue = arrayValue.length
 
           if (arrayValue.length > 0) {
             fieldState.disableFormData = true
@@ -236,8 +237,8 @@ export const addFieldStatePromise = async ({
           fieldState.value = null
           fieldState.initialValue = null
         } else {
-          fieldState.value = blocksValue
-          fieldState.initialValue = blocksValue
+          fieldState.value = blocksValue.length
+          fieldState.initialValue = blocksValue.length
 
           if (blocksValue.length > 0) {
             fieldState.disableFormData = true

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

@@ -8,6 +8,9 @@ import getSiblingData from './getSiblingData'
 import reduceFieldsToValues from './reduceFieldsToValues'
 import { flattenRows, separateRows } from './rows'
 
+/**
+ * Reducer which modifies the form field state (all the current data of the fields in the form). When called using dispatch, it will return a new state object.
+ */
 export function fieldReducer(state: Fields, action: FieldAction): Fields {
   switch (action.type) {
     case 'REPLACE_STATE': {
@@ -123,7 +126,7 @@ export function fieldReducer(state: Fields, action: FieldAction): Fields {
           ...state[path],
           disableFormData: rows.length > 0,
           rows: rowsMetadata,
-          value: rows,
+          value: rows.length,
         },
         ...flattenRows(path, rows),
       }
@@ -132,7 +135,9 @@ export function fieldReducer(state: Fields, action: FieldAction): Fields {
     }
 
     case 'ADD_ROW': {
-      const { blockType, path, rowIndex, subFieldState } = action
+      const { blockType, path, rowIndex: rowIndexFromArgs, subFieldState } = action
+      const rowIndex =
+        typeof rowIndexFromArgs === 'number' ? rowIndexFromArgs : state[path]?.rows?.length || 0
 
       const rowsMetadata = [...(state[path]?.rows || [])]
       rowsMetadata.splice(
@@ -155,19 +160,18 @@ export function fieldReducer(state: Fields, action: FieldAction): Fields {
         }
       }
 
-      const { remainingFields, rows } = separateRows(path, state)
-
-      // actual form state (value saved in db)
-      rows.splice(rowIndex, 0, subFieldState)
+      // add new row to array _field state_
+      const { remainingFields, rows: siblingRows } = separateRows(path, state)
+      siblingRows.splice(rowIndex, 0, subFieldState)
 
       const newState: Fields = {
         ...remainingFields,
-        ...flattenRows(path, rows),
+        ...flattenRows(path, siblingRows),
         [path]: {
           ...state[path],
           disableFormData: true,
           rows: rowsMetadata,
-          value: rows,
+          value: siblingRows.length,
         },
       }
 
@@ -176,8 +180,8 @@ export function fieldReducer(state: Fields, action: FieldAction): Fields {
 
     case 'REPLACE_ROW': {
       const { blockType, path, rowIndex: rowIndexArg, subFieldState } = action
-      const { remainingFields, rows } = separateRows(path, state)
-      const rowIndex = Math.max(0, Math.min(rowIndexArg, rows?.length - 1 || 0))
+      const { remainingFields, rows: siblingRows } = separateRows(path, state)
+      const rowIndex = Math.max(0, Math.min(rowIndexArg, siblingRows?.length - 1 || 0))
 
       const rowsMetadata = [...(state[path]?.rows || [])]
       rowsMetadata[rowIndex] = {
@@ -195,17 +199,17 @@ export function fieldReducer(state: Fields, action: FieldAction): Fields {
         }
       }
 
-      // replace form field state
-      rows[rowIndex] = subFieldState
+      // replace form _field state_
+      siblingRows[rowIndex] = subFieldState
 
       const newState: Fields = {
         ...remainingFields,
-        ...flattenRows(path, rows),
+        ...flattenRows(path, siblingRows),
         [path]: {
           ...state[path],
           disableFormData: true,
           rows: rowsMetadata,
-          value: rows,
+          value: siblingRows.length,
         },
       }
 
@@ -236,7 +240,7 @@ export function fieldReducer(state: Fields, action: FieldAction): Fields {
           ...state[path],
           disableFormData: true,
           rows: rowsMetadata,
-          value: rows,
+          value: rows.length,
         },
         ...flattenRows(path, rows),
       }

packages/payload/src/admin/components/forms/Form/index.tsx

@@ -50,12 +50,15 @@ import reduceFieldsToValues from './reduceFieldsToValues'
 const baseClass = 'form'
 
 const Form: React.FC<Props> = (props) => {
+  const { id, collection, getDocPreferences, global } = useDocumentInfo()
+
   const {
     action,
     children,
     className,
     disableSuccessStatus,
     disabled,
+    fields: fieldsFromProps = collection?.fields || global?.fields,
     handleResponse,
     initialData, // values only, paths are required as key - form should build initial state as convenience
     initialState, // fully formed initial field state
@@ -71,7 +74,6 @@ const Form: React.FC<Props> = (props) => {
   const { code: locale } = useLocale()
   const { i18n, t } = useTranslation('general')
   const { refreshCookie, user } = useAuth()
-  const { id, collection, getDocPreferences, global } = useDocumentInfo()
   const operation = useOperation()
 
   const config = useConfig()
@@ -90,6 +92,10 @@ const Form: React.FC<Props> = (props) => {
   if (initialState) initialFieldState = initialState
 
   const fieldsReducer = useReducer(fieldReducer, {}, () => initialFieldState)
+  /**
+   * `fields` is the current, up-to-date state/data of all fields in the form. It can be modified by using dispatchFields,
+   * which calls the fieldReducer, which then updates the state.
+   */
   const [fields, dispatchFields] = fieldsReducer
 
   contextRef.current.fields = fields
@@ -167,7 +173,13 @@ const Form: React.FC<Props> = (props) => {
           let validationResult: boolean | string = true
 
           if (typeof field.validate === 'function') {
-            validationResult = await field.validate(field.value, {
+            let valueToValidate = field.value
+
+            if (field?.rows && Array.isArray(field.rows)) {
+              valueToValidate = contextRef.current.getDataByPath(path)
+            }
+
+            validationResult = await field.validate(valueToValidate, {
               id,
               config,
               data,
@@ -431,10 +443,10 @@ const Form: React.FC<Props> = (props) => {
     [],
   )
 
-  const getRowConfigByPath = React.useCallback(
+  const getRowSchemaByPath = React.useCallback(
     ({ blockType, path }: { blockType?: string; path: string }) => {
       const rowConfig = traverseRowConfigs({
-        fieldConfig: collection?.fields || global?.fields,
+        fieldConfig: fieldsFromProps,
         path,
       })
       const rowFieldConfigs = buildFieldSchemaMap(rowConfig)
@@ -442,30 +454,32 @@ const Form: React.FC<Props> = (props) => {
       const fieldKey = pathSegments.at(-1)
       return rowFieldConfigs.get(blockType ? `${fieldKey}.${blockType}` : fieldKey)
     },
-    [traverseRowConfigs, collection?.fields, global?.fields],
+    [traverseRowConfigs, fieldsFromProps],
   )
 
-  // Array/Block row manipulation
+  // Array/Block row manipulation. This is called when, for example, you add a new block to a blocks field.
+  // The block data is saved in the rows property of the state, which is modified updated here.
   const addFieldRow: Context['addFieldRow'] = useCallback(
     async ({ data, path, rowIndex }) => {
       const preferences = await getDocPreferences()
-      const fieldConfig = getRowConfigByPath({
+      const rowSchema = getRowSchemaByPath({
         blockType: data?.blockType,
         path,
       })
 
-      if (fieldConfig) {
+      if (rowSchema) {
         const subFieldState = await buildStateFromSchema({
           id,
           config,
           data,
-          fieldSchema: fieldConfig,
+          fieldSchema: rowSchema,
           locale,
           operation,
           preferences,
           t,
           user,
         })
+
         dispatchFields({
           blockType: data?.blockType,
           path,
@@ -475,11 +489,11 @@ const Form: React.FC<Props> = (props) => {
         })
       }
     },
-    [dispatchFields, getDocPreferences, id, user, operation, locale, t, getRowConfigByPath, config],
+    [dispatchFields, getDocPreferences, id, user, operation, locale, t, getRowSchemaByPath, config],
   )
 
   const removeFieldRow: Context['removeFieldRow'] = useCallback(
-    async ({ path, rowIndex }) => {
+    ({ path, rowIndex }) => {
       dispatchFields({ path, rowIndex, type: 'REMOVE_ROW' })
     },
     [dispatchFields],
@@ -488,17 +502,17 @@ const Form: React.FC<Props> = (props) => {
   const replaceFieldRow: Context['replaceFieldRow'] = useCallback(
     async ({ data, path, rowIndex }) => {
       const preferences = await getDocPreferences()
-      const fieldConfig = getRowConfigByPath({
+      const rowSchema = getRowSchemaByPath({
         blockType: data?.blockType,
         path,
       })
 
-      if (fieldConfig) {
+      if (rowSchema) {
         const subFieldState = await buildStateFromSchema({
           id,
           config,
           data,
-          fieldSchema: fieldConfig,
+          fieldSchema: rowSchema,
           locale,
           operation,
           preferences,
@@ -514,7 +528,7 @@ const Form: React.FC<Props> = (props) => {
         })
       }
     },
-    [dispatchFields, getDocPreferences, id, user, operation, locale, t, getRowConfigByPath, config],
+    [dispatchFields, getDocPreferences, id, user, operation, locale, t, getRowSchemaByPath, config],
   )
 
   const getFields = useCallback(() => contextRef.current.fields, [contextRef])

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

@@ -12,9 +12,9 @@ export const separateRows = (path: string, fields: Fields): Result => {
     const newRows = incomingRows
 
     if (fieldPath.indexOf(`${path}.`) === 0) {
-      const index = Number(fieldPath.replace(`${path}.`, '').split('.')[0])
-      if (!newRows[index]) newRows[index] = {}
-      newRows[index][fieldPath.replace(`${path}.${String(index)}.`, '')] = { ...field }
+      const [rowIndex] = fieldPath.replace(`${path}.`, '').split('.')
+      if (!newRows[rowIndex]) newRows[rowIndex] = {}
+      newRows[rowIndex][fieldPath.replace(`${path}.${String(rowIndex)}.`, '')] = { ...field }
     } else {
       remainingFields[fieldPath] = field
     }

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

@@ -2,7 +2,12 @@ import type React from 'react'
 import type { Dispatch } from 'react'
 
 import type { User } from '../../../../auth/types'
-import type { Condition, Field as FieldConfig, Validate } from '../../../../fields/config/types'
+import type {
+  Condition,
+  Field,
+  Field as FieldConfig,
+  Validate,
+} from '../../../../fields/config/types'
 
 export type Row = {
   blockType?: string
@@ -41,6 +46,12 @@ export type Props = {
   className?: string
   disableSuccessStatus?: boolean
   disabled?: boolean
+  /**
+   * By default, the form will get the field schema (not data) from the current document. If you pass this in, you can override that behavior.
+   * This is very useful for sub-forms, where the form's field schema is not necessarily the field schema of the current document (e.g. for the Blocks
+   * feature of the Lexical Rich Text field)
+   */
+  fields?: Field[]
   handleResponse?: (res: Response) => void
   initialData?: Data
   initialState?: Fields
@@ -174,7 +185,10 @@ export type Context = {
   }: {
     data?: Data
     path: string
-    rowIndex: number
+    /*
+     * by default the new row will be added to the end of the list
+     */
+    rowIndex?: number
   }) => Promise<void>
   buildRowErrors: () => void
   createFormData: CreateFormData
@@ -190,7 +204,7 @@ export type Context = {
   getField: GetField
   getFields: GetFields
   getSiblingData: GetSiblingData
-  removeFieldRow: ({ path, rowIndex }: { path: string; rowIndex: number }) => Promise<void>
+  removeFieldRow: ({ path, rowIndex }: { path: string; rowIndex: number }) => void
   replaceFieldRow: ({
     data,
     path,

packages/payload/src/admin/components/forms/RenderFields/index.tsx

@@ -17,10 +17,21 @@ const intersectionObserverOptions = {
   rootMargin: '1000px',
 }
 
-// If you send `fields` through, it will render those fields explicitly
-// Otherwise, it will reduce your fields using the other provided props
-// This is so that we can conditionally render fields before reducing them, if desired
-// See the sidebar in '../collections/Edit/Default/index.tsx' for an example
+/**
+ * If you send `fields` through, it will render those fields explicitly
+ * Otherwise, it will reduce your fields using the other provided props
+ * This is so that we can conditionally render fields before reducing them, if desired
+ * See the sidebar in '../collections/Edit/Default/index.tsx' for an example
+ *
+ * The state/data for the fields it renders is not managed by this component. Instead, every component it renders has
+ * their own handling of their own value, usually through the useField hook. This hook will get the field's value
+ * from the Form the field is in, using the field's path.
+ *
+ * Thus, if you would like to set the value of a field you render here, you must do so in the Form that contains the field, or in the
+ * Field component itself.
+ *
+ * All this component does is render the field's Field Components, and pass them the props they need to function.
+ **/
 const RenderFields: React.FC<Props> = (props) => {
   const { className, fieldTypes, forceRender, margins } = props
 

packages/payload/src/admin/components/forms/RenderFields/types.ts

@@ -6,21 +6,23 @@ import type { ReducedField } from './filterFields'
 export type Props = {
   className?: string
   fieldTypes: FieldTypes
-  margins?: 'small' | false
   forceRender?: boolean
+  margins?: 'small' | false
+  permissions?:
+    | {
+        [field: string]: FieldPermissions
+      }
+    | FieldPermissions
+  readOnly?: boolean
 } & (
   | {
+      // Fields to be filtered by the component
       fieldSchema: FieldWithPath[]
       filter?: (field: Field) => boolean
       indexPath?: string
-      permissions?:
-        | {
-            [field: string]: FieldPermissions
-          }
-        | FieldPermissions
-      readOnly?: boolean
     }
   | {
+      // Pre-filtered fields to be simply rendered
       fields: ReducedField[]
     }
 )

packages/payload/src/admin/components/forms/field-types/Array/index.tsx

@@ -91,7 +91,7 @@ const ArrayFieldType: React.FC<Props> = (props) => {
     showError,
     valid,
     value,
-  } = useField<[]>({
+  } = useField<number>({
     condition,
     hasRows: true,
     path,
@@ -123,8 +123,8 @@ const ArrayFieldType: React.FC<Props> = (props) => {
   )
 
   const removeRow = useCallback(
-    async (rowIndex: number) => {
-      await removeFieldRow({ path, rowIndex })
+    (rowIndex: number) => {
+      removeFieldRow({ path, rowIndex })
       setModified(true)
     },
     [removeFieldRow, path, setModified],
@@ -278,7 +278,7 @@ const ArrayFieldType: React.FC<Props> = (props) => {
           icon="plus"
           iconPosition="left"
           iconStyle="with-border"
-          onClick={() => addRow(value?.length || 0)}
+          onClick={() => addRow(value || 0)}
         >
           {t('addLabel', { label: getTranslation(labels.singular, i18n) })}
         </Button>

packages/payload/src/admin/components/forms/field-types/Blocks/index.tsx

@@ -90,7 +90,7 @@ const BlocksField: React.FC<Props> = (props) => {
     showError,
     valid,
     value,
-  } = useField<[]>({
+  } = useField<number>({
     condition,
     hasRows: true,
     path,
@@ -128,8 +128,8 @@ const BlocksField: React.FC<Props> = (props) => {
   )
 
   const removeRow = useCallback(
-    async (rowIndex: number) => {
-      await removeFieldRow({ path, rowIndex })
+    (rowIndex: number) => {
+      removeFieldRow({ path, rowIndex })
       setModified(true)
     },
     [path, removeFieldRow, setModified],
@@ -297,7 +297,7 @@ const BlocksField: React.FC<Props> = (props) => {
           </DrawerToggler>
           <BlocksDrawer
             addRow={addRow}
-            addRowIndex={value?.length || 0}
+            addRowIndex={value || 0}
             blocks={blocks}
             drawerSlug={drawerSlug}
             labels={labels}

packages/payload/src/admin/components/forms/field-types/RichText/types.ts

@@ -2,24 +2,24 @@ import type { PayloadRequest } from '../../../../../express/types'
 import type { RichTextField, Validate } from '../../../../../fields/config/types'
 import type { CellComponentProps } from '../../../views/collections/List/Cell/types'
 
-export type RichTextFieldProps<AdapterProps = object> = Omit<
-  RichTextField<AdapterProps>,
+export type RichTextFieldProps<Value extends object, AdapterProps> = Omit<
+  RichTextField<Value, AdapterProps>,
   'type'
 > & {
   path?: string
 }
 
-export type RichTextAdapter<AdapterProps = object> = {
-  CellComponent: React.FC<CellComponentProps<RichTextField<AdapterProps>>>
-  FieldComponent: React.FC<RichTextFieldProps<AdapterProps>>
+export type RichTextAdapter<Value extends object = object, AdapterProps = any> = {
+  CellComponent: React.FC<CellComponentProps<RichTextField<Value, AdapterProps>>>
+  FieldComponent: React.FC<RichTextFieldProps<Value, AdapterProps>>
   afterReadPromise?: (data: {
     currentDepth?: number
     depth: number
-    field: RichTextField<AdapterProps>
+    field: RichTextField<Value, AdapterProps>
     overrideAccess?: boolean
     req: PayloadRequest
     showHiddenFields: boolean
     siblingDoc: Record<string, unknown>
   }) => Promise<void> | null
-  validate: Validate<unknown, unknown, RichTextField<AdapterProps>>
+  validate: Validate<Value, Value, unknown, RichTextField<Value, AdapterProps>>
 }

packages/payload/src/admin/components/forms/field-types/Row/index.tsx

@@ -5,9 +5,9 @@ import type { Props } from './types'
 import { createNestedFieldPath } from '../../Form/createNestedFieldPath'
 import RenderFields from '../../RenderFields'
 import withCondition from '../../withCondition'
+import { fieldBaseClass } from '../shared'
 import './index.scss'
 import { RowProvider } from './provider'
-import { fieldBaseClass } from '../shared'
 
 const Row: React.FC<Props> = (props) => {
   const {
@@ -29,7 +29,6 @@ const Row: React.FC<Props> = (props) => {
         }))}
         fieldTypes={fieldTypes}
         indexPath={indexPath}
-        margins={false}
         permissions={permissions}
         readOnly={readOnly}
       />

packages/payload/src/admin/components/forms/useField/index.tsx

@@ -29,7 +29,7 @@ const useField = <T,>(options: Options): FieldType<T> => {
   const dispatchField = useFormFields(([_, dispatch]) => dispatch)
   const config = useConfig()
 
-  const { getData, getSiblingData, setModified } = useForm()
+  const { getData, getDataByPath, getSiblingData, setModified } = useForm()
 
   const value = field?.value as T
   const initialValue = field?.initialValue as T
@@ -116,8 +116,14 @@ const useField = <T,>(options: Options): FieldType<T> => {
           user,
         }
 
+        let valueToValidate = value
+
+        if (field?.rows && Array.isArray(field.rows)) {
+          valueToValidate = getDataByPath(path)
+        }
+
         const validationResult =
-          typeof validate === 'function' ? await validate(value, validateOptions) : true
+          typeof validate === 'function' ? await validate(valueToValidate, validateOptions) : true
 
         if (typeof validationResult === 'string') {
           action.errorMessage = validationResult
@@ -132,7 +138,7 @@ const useField = <T,>(options: Options): FieldType<T> => {
         }
       }
 
-      validateField()
+      void validateField()
     },
     150,
     [
@@ -142,6 +148,7 @@ const useField = <T,>(options: Options): FieldType<T> => {
       dispatchField,
       getData,
       getSiblingData,
+      getDataByPath,
       id,
       operation,
       path,

packages/payload/src/admin/components/views/API/index.scss

@@ -7,6 +7,10 @@
   gap: calc(var(--base) * 2);
   align-items: flex-start;
 
+  ul {
+    padding-left: calc(var(--base) * 1);
+  }
+
   &--fullscreen {
     padding-left: 0;
     .query-inspector__configuration {
@@ -173,6 +177,10 @@
     }
   }
 
+  &__row-line--nested {
+    margin-left: 25px;
+  }
+
   &__bracket {
     position: relative;
 

packages/payload/src/admin/components/views/API/index.tsx

@@ -1,6 +1,8 @@
 import * as React from 'react'
 import { useTranslation } from 'react-i18next'
 
+import type { EditViewProps } from '../types'
+
 import { Chevron } from '../..'
 import { requests } from '../../../api'
 import CopyToClipboard from '../../elements/CopyToClipboard'
@@ -11,6 +13,7 @@ import { MinimizeMaximize } from '../../icons/MinimizeMaximize'
 import { useConfig } from '../../utilities/Config'
 import { useDocumentInfo } from '../../utilities/DocumentInfo'
 import { useLocale } from '../../utilities/Locale'
+import { SetStepNav } from '../collections/Edit/SetStepNav'
 import './index.scss'
 
 const chars = {
@@ -119,12 +122,19 @@ const RecursivelyRenderObjectData = ({
             }
 
             if (type === 'date' || type === 'string' || type === 'null' || type === 'number') {
+              const parentHasKey = Boolean(parentType === 'object' && key)
+
+              const rowClasses = [
+                `${baseClass}__row-line`,
+                `${baseClass}__value-type--${type}`,
+                `${baseClass}__row-line--${objectKey ? 'nested' : 'top'}`,
+              ]
+                .filter(Boolean)
+                .join(' ')
+
               return (
-                <li
-                  className={`${baseClass}__row-line ${baseClass}__value-type--${type}`}
-                  key={`${key}-${keyIndex}`}
-                >
-                  {parentType === 'object' ? <span>{`"${key}": `}</span> : null}
+                <li className={rowClasses} key={`${key}-${keyIndex}`}>
+                  {parentHasKey ? <span>{`"${key}": `}</span> : null}
 
                   {type === 'string' ? (
                     <span className={`${baseClass}__value`}>{`"${value}"`}</span>
@@ -156,7 +166,8 @@ function createURL(url: string) {
   }
 }
 
-export const API = ({ apiURL }) => {
+export const API: React.FC<EditViewProps> = (props) => {
+  const { apiURL } = props
   const { i18n } = useTranslation()
   const {
     localization,
@@ -201,8 +212,21 @@ export const API = ({ apiURL }) => {
 
   const classes = [baseClass, fullscreen && `${baseClass}--fullscreen`].filter(Boolean).join(' ')
 
+  let isEditing: boolean
+
+  if ('collection' in props) {
+    isEditing = props?.isEditing
+  }
+
   return (
     <Gutter className={classes} right={false}>
+      <SetStepNav
+        collection={collection}
+        global={global}
+        id={id}
+        isEditing={isEditing}
+        view="API"
+      />
       <div className={`${baseClass}__configuration`}>
         <div className={`${baseClass}__api-url`}>
           <span className={`${baseClass}__label`}>

packages/payload/src/admin/components/views/Global/Default.tsx

@@ -8,6 +8,7 @@ import { DocumentHeader } from '../../elements/DocumentHeader'
 import { FormLoadingOverlayToggle } from '../../elements/Loading'
 import Form from '../../forms/Form'
 import { OperationContext } from '../../utilities/OperationProvider'
+import { SetStepNav } from '../collections/Edit/SetStepNav'
 import { GlobalRoutes } from './Routes'
 import { CustomGlobalComponent } from './Routes/CustomComponent'
 import './index.scss'
@@ -40,6 +41,7 @@ const DefaultGlobalView: React.FC<
   return (
     <main className={baseClass}>
       <OperationContext.Provider value="update">
+        <SetStepNav global={global} />
         <Form
           action={action}
           className={`${baseClass}__form`}

packages/payload/src/admin/components/views/Global/Default/index.scss

@@ -27,7 +27,8 @@
       }
 
       &__fields {
-        & > .tabs-field {
+        & > .tabs-field,
+        & > .group-field {
           margin-right: calc(var(--base) * -2);
         }
       }
@@ -49,8 +50,9 @@
 
   &__sidebar-wrap {
     position: sticky;
-    top: 0;
-    flex-grow: 1;
+    top: var(--doc-controls-height);
+    width: 33.33%;
+    height: calc(100vh - var(--doc-controls-height));
   }
 
   &__sidebar {
@@ -109,7 +111,8 @@
         }
 
         &__fields {
-          & > .tabs-field {
+          & > .tabs-field,
+          & > .group-field {
             margin-right: calc(var(--gutter-h) * -1);
           }
         }

packages/payload/src/admin/components/views/Global/Default/index.tsx

@@ -90,9 +90,8 @@ export const DefaultGlobalEdit: React.FC<GlobalEditViewProps> = (props) => {
               <div className={`${baseClass}__sidebar-sticky-wrap`}>
                 <div className={`${baseClass}__sidebar-fields`}>
                   <RenderFields
-                    fieldSchema={fields}
                     fieldTypes={fieldTypes}
-                    filter={(field) => field.admin.position === 'sidebar'}
+                    fields={sidebarFields}
                     permissions={permissions.fields}
                     readOnly={!hasSavePermission}
                   />

packages/payload/src/admin/components/views/LivePreview/Context/context.ts

@@ -8,7 +8,6 @@ import type { SizeReducerAction } from './sizeReducer'
 export interface LivePreviewContextType {
   breakpoint: LivePreviewConfig['breakpoints'][number]['name']
   breakpoints: LivePreviewConfig['breakpoints']
-  deviceFrameRef: React.RefObject<HTMLDivElement>
   iframeHasLoaded: boolean
   iframeRef: React.RefObject<HTMLIFrameElement>
   measuredDeviceSize: {
@@ -18,6 +17,7 @@ export interface LivePreviewContextType {
   setBreakpoint: (breakpoint: LivePreviewConfig['breakpoints'][number]['name']) => void
   setHeight: (height: number) => void
   setIframeHasLoaded: (loaded: boolean) => void
+  setMeasuredDeviceSize: (size: { height: number; width: number }) => void
   setSize: Dispatch<SizeReducerAction>
   setToolbarPosition: (position: { x: number; y: number }) => void
   setWidth: (width: number) => void
@@ -36,7 +36,6 @@ export interface LivePreviewContextType {
 export const LivePreviewContext = createContext<LivePreviewContextType>({
   breakpoint: undefined,
   breakpoints: undefined,
-  deviceFrameRef: undefined,
   iframeHasLoaded: false,
   iframeRef: undefined,
   measuredDeviceSize: {
@@ -46,6 +45,7 @@ export const LivePreviewContext = createContext<LivePreviewContextType>({
   setBreakpoint: () => {},
   setHeight: () => {},
   setIframeHasLoaded: () => {},
+  setMeasuredDeviceSize: () => {},
   setSize: () => {},
   setToolbarPosition: () => {},
   setWidth: () => {},

packages/payload/src/admin/components/views/LivePreview/Context/index.tsx

@@ -5,7 +5,6 @@ import type { LivePreviewConfig } from '../../../../../exports/config'
 import type { EditViewProps } from '../../types'
 import type { usePopupWindow } from '../usePopupWindow'
 
-import { useResize } from '../../../../utilities/useResize'
 import { customCollisionDetection } from './collisionDetection'
 import { LivePreviewContext } from './context'
 import { sizeReducer } from './sizeReducer'
@@ -26,8 +25,6 @@ export const LivePreviewProvider: React.FC<ToolbarProviderProps> = (props) => {
 
   const iframeRef = React.useRef<HTMLIFrameElement>(null)
 
-  const deviceFrameRef = React.useRef<HTMLDivElement>(null)
-
   const [iframeHasLoaded, setIframeHasLoaded] = React.useState(false)
 
   const [zoom, setZoom] = React.useState(1)
@@ -36,6 +33,11 @@ export const LivePreviewProvider: React.FC<ToolbarProviderProps> = (props) => {
 
   const [size, setSize] = React.useReducer(sizeReducer, { height: 0, width: 0 })
 
+  const [measuredDeviceSize, setMeasuredDeviceSize] = React.useState({
+    height: 0,
+    width: 0,
+  })
+
   const [breakpoint, setBreakpoint] =
     React.useState<LivePreviewConfig['breakpoints'][0]['name']>('responsive')
 
@@ -92,22 +94,18 @@ export const LivePreviewProvider: React.FC<ToolbarProviderProps> = (props) => {
     }
   }, [breakpoint, breakpoints])
 
-  // keep an accurate measurement of the actual device size as it is truly rendered
-  // this is helpful when `sizes` are non-number units like percentages, etc.
-  const { size: measuredDeviceSize } = useResize(deviceFrameRef)
-
   return (
     <LivePreviewContext.Provider
       value={{
         breakpoint,
         breakpoints,
-        deviceFrameRef,
         iframeHasLoaded,
         iframeRef,
         measuredDeviceSize,
         setBreakpoint,
         setHeight,
         setIframeHasLoaded,
+        setMeasuredDeviceSize,
         setSize,
         setToolbarPosition: setPosition,
         setWidth,

packages/payload/src/admin/components/views/LivePreview/Device/index.tsx

@@ -1,5 +1,6 @@
-import React from 'react'
+import React, { useEffect } from 'react'
 
+import { useResize } from '../../../../utilities/useResize'
 import { useLivePreviewContext } from '../Context/context'
 
 export const DeviceContainer: React.FC<{
@@ -7,7 +8,22 @@ export const DeviceContainer: React.FC<{
 }> = (props) => {
   const { children } = props
 
-  const { breakpoint, deviceFrameRef, size, zoom } = useLivePreviewContext()
+  const deviceFrameRef = React.useRef<HTMLDivElement>(null)
+
+  const { breakpoint, setMeasuredDeviceSize, size, zoom } = useLivePreviewContext()
+
+  // Keep an accurate measurement of the actual device size as it is truly rendered
+  // This is helpful when `sizes` are non-number units like percentages, etc.
+  const { size: measuredDeviceSize } = useResize(deviceFrameRef)
+
+  // Sync the measured device size with the context so that other components can use it
+  // This happens from the bottom up so that as this component mounts and unmounts,
+  // Its size is freshly populated again upon re-mounting, i.e. going from iframe->popup->iframe
+  useEffect(() => {
+    if (measuredDeviceSize) {
+      setMeasuredDeviceSize(measuredDeviceSize)
+    }
+  }, [measuredDeviceSize, setMeasuredDeviceSize])
 
   let x = '0'
   let margin = '0'

packages/payload/src/admin/components/views/LivePreview/DeviceContainer/index.tsx

@@ -7,7 +7,7 @@ export const DeviceContainer: React.FC<{
 }> = (props) => {
   const { children } = props
 
-  const { breakpoint, breakpoints, deviceFrameRef, size, zoom } = useLivePreviewContext()
+  const { breakpoint, breakpoints, size, zoom } = useLivePreviewContext()
 
   const foundBreakpoint = breakpoint && breakpoints?.find((bp) => bp.name === breakpoint)
 
@@ -31,7 +31,6 @@ export const DeviceContainer: React.FC<{
 
   return (
     <div
-      ref={deviceFrameRef}
       style={{
         height:
           foundBreakpoint && foundBreakpoint?.name !== 'responsive'

packages/payload/src/admin/components/views/LivePreview/Preview/index.tsx

@@ -58,13 +58,16 @@ const Preview: React.FC<
       const values = reduceFieldsToValues(fields, true)
 
       // TODO: only send `fieldSchemaToJSON` one time
-      const message = JSON.stringify({ data: values, fieldSchemaJSON, type: 'livePreview' })
+      const message = JSON.stringify({
+        data: values,
+        fieldSchemaJSON,
+        type: 'payload-live-preview',
+      })
 
       // external window
       if (isPopupOpen) {
         setIframeHasLoaded(false)
-
-        if (popupHasLoaded && popupRef.current) {
+        if (popupRef.current) {
           popupRef.current.postMessage(message, url)
         }
       }

packages/payload/src/admin/components/views/LivePreview/index.tsx

@@ -55,8 +55,8 @@ export const LivePreviewView: React.FC<EditViewProps> = (props) => {
       : livePreviewConfig?.url
 
   const popupState = usePopupWindow({
-    eventType: 'livePreview',
-    href: url,
+    eventType: 'payload-live-preview',
+    url,
   })
 
   const { apiURL, data, permissions } = props
@@ -94,7 +94,13 @@ export const LivePreviewView: React.FC<EditViewProps> = (props) => {
 
   return (
     <Fragment>
-      <SetStepNav collection={collection} global={global} id={id} isEditing={isEditing} />
+      <SetStepNav
+        collection={collection}
+        global={global}
+        id={id}
+        isEditing={isEditing}
+        view={t('livePreview')}
+      />
       <DocumentControls
         apiURL={apiURL}
         collection={collection}

packages/payload/src/admin/components/views/LivePreview/usePopupWindow.ts

@@ -14,28 +14,29 @@ export interface PopupMessage {
 
 export const usePopupWindow = (props: {
   eventType?: string
-  href: string
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   onMessage?: (searchParams: PopupMessage['searchParams']) => Promise<void>
+  url: string
 }): {
   isPopupOpen: boolean
   openPopupWindow: (e: React.MouseEvent<HTMLAnchorElement>) => void
   popupHasLoaded: boolean
   popupRef?: React.MutableRefObject<Window | null>
 } => {
-  const { eventType, href, onMessage } = props
+  const { eventType, onMessage, url } = props
   const isReceivingMessage = useRef(false)
   const [isOpen, setIsOpen] = useState(false)
   const [popupHasLoaded, setPopupHasLoaded] = useState(false)
   const { serverURL } = useConfig()
   const popupRef = useRef<Window | null>(null)
+  const hasAttachedMessageListener = useRef(false)
 
   // Optionally broadcast messages back out to the parent component
   useEffect(() => {
     const receiveMessage = async (event: MessageEvent): Promise<void> => {
       if (
         event.origin !== window.location.origin ||
-        event.origin !== href ||
+        event.origin !== url ||
         event.origin !== serverURL
       ) {
         // console.warn(`Message received by ${event.origin}; IGNORED.`) // eslint-disable-line no-console
@@ -53,12 +54,14 @@ export const usePopupWindow = (props: {
       }
     }
 
-    window.addEventListener('message', receiveMessage, false)
+    if (isOpen && popupRef.current) {
+      window.addEventListener('message', receiveMessage, false)
+    }
 
     return () => {
       window.removeEventListener('message', receiveMessage)
     }
-  }, [onMessage, eventType, href, serverURL])
+  }, [onMessage, eventType, url, serverURL, isOpen])
 
   // Customize the size, position, and style of the popup window
   const openPopupWindow = useCallback(
@@ -93,23 +96,36 @@ export const usePopupWindow = (props: {
           return strCopy
         }, '')
         .slice(0, -1) // remove last ',' (comma)
-      const newWindow = window.open(href, '_blank', popupOptions)
+
+      const newWindow = window.open(url, '_blank', popupOptions)
+
       popupRef.current = newWindow
+
       setIsOpen(true)
     },
-    [href],
+    [url],
   )
 
   // the only cross-origin way of detecting when a popup window has loaded
   // we catch a message event that the site rendered within the popup window fires
   // there is no way in js to add an event listener to a popup window across domains
   useEffect(() => {
+    if (hasAttachedMessageListener.current) return
+    hasAttachedMessageListener.current = true
+
     window.addEventListener('message', (event) => {
-      if (event.origin === href && event.data === 'ready') {
+      const data = JSON.parse(event.data)
+
+      if (
+        url.startsWith(event.origin) &&
+        data.type === eventType &&
+        data.popupReady &&
+        !popupHasLoaded
+      ) {
         setPopupHasLoaded(true)
       }
     })
-  }, [href])
+  }, [url, eventType, popupHasLoaded])
 
   // this is the most stable and widely supported way to check if a popup window is no longer open
   // we poll its ref every x ms and use the popup window's `closed` property

packages/payload/src/admin/components/views/Login/index.scss

@@ -21,4 +21,11 @@
       margin: 0;
     }
   }
+
+  &__inputWrap {
+    display: flex;
+    flex-direction: column;
+    gap: base(1);
+    margin-bottom: base(0.25);
+  }
 }