feat!: beta-next (#7620)

This PR makes three major changes to the codebase:

1. [Component Paths](#component-paths)
Instead of importing custom components into your config directly, they
are now defined as file paths and rendered only when needed. That way
the Payload config will be significantly more lightweight, and ensures
that the Payload config is 100% server-only and Node-safe. Related
discussion: #6938

2. [Client Config](#client-config)
Deprecates the component map by merging its logic into the client
config. The main goal of this change is for performance and
simplification. There was no need to deeply iterate over the Payload
config twice, once for the component map, and another for the client
config. Instead, we can do everything in the client config one time.
This has also dramatically simplified the client side prop drilling
through the UI library. Now, all components can share the same client
config which matches the exact shape of their Payload config (with the
exception of non-serializable props and mapped custom components).

3. [Custom client component are no longer
server-rendered](#custom-client-components-are-no-longer-server-rendered)
Previously, custom components would be server-rendered, no matter if
they are server or client components. Now, only server components are
rendered on the server. Client components are automatically detected,
and simply get passed through as `MappedComponent` to be rendered fully
client-side.

## Component Paths

Instead of importing custom components into your config directly, they
are now defined as file paths and rendered only when needed. That way
the Payload config will be significantly more lightweight, and ensures
that the Payload config is 100% server-only and Node-safe. Related
discussion: #6938

In order to reference any custom components in the Payload config, you
now have to specify a string path to the component instead of importing
it.

Old:

```ts
import { MyComponent2} from './MyComponent2.js'

admin: {
  components: {
    Label: MyComponent2
  },
},
```

New:

```ts
admin: {
  components: {
    Label: '/collections/Posts/MyComponent2.js#MyComponent2', // <= has to be a relative path based on a baseDir configured in the Payload config - NOT relative based on the importing file
  },
},
```

### Local API within Next.js routes

Previously, if you used the Payload Local API within Next.js pages, all
the client-side modules are being added to the bundle for that specific
page, even if you only need server-side functionality.

This `/test` route, which uses the Payload local API, was previously 460
kb. It is now down to 91 kb and does not bundle the Payload client-side
admin panel anymore.

All tests done
[here](https://github.com/payloadcms/payload-3.0-demo/tree/feat/path-test)
with beta.67/PR, db-mongodb and default richtext-lexical:

**dev /admin before:**
![CleanShot 2024-07-29 at 22 49
12@2x](https://github.com/user-attachments/assets/4428e766-b368-4bcf-8c18-d0187ab64f3e)

**dev /admin after:**
![CleanShot 2024-07-29 at 22 50
49@2x](https://github.com/user-attachments/assets/f494c848-7247-4b02-a650-a3fab4000de6)

---

**dev /test before:**
![CleanShot 2024-07-29 at 22 56
18@2x](https://github.com/user-attachments/assets/1a7e9500-b859-4761-bf63-abbcdac6f8d6)

**dev /test after:**
![CleanShot 2024-07-29 at 22 47
45@2x](https://github.com/user-attachments/assets/f89aa76d-f2d5-4572-9753-2267f034a45a)

---

**build before:**
![CleanShot 2024-07-29 at 22 57
14@2x](https://github.com/user-attachments/assets/5f8f7281-2a4a-40a5-a788-c30ddcdd51b5)

**build after::**
![CleanShot 2024-07-29 at 22 56
39@2x](https://github.com/user-attachments/assets/ea8772fd-512f-4db0-9a81-4b014715a1b7)

### Usage of the Payload Local API / config outside of Next.js

This will make it a lot easier to use the Payload config / local API in
other, server-side contexts. Previously, you might encounter errors due
to client files (like .scss files) not being allowed to be imported.

## Client Config

Deprecates the component map by merging its logic into the client
config. The main goal of this change is for performance and
simplification. There was no need to deeply iterate over the Payload
config twice, once for the component map, and another for the client
config. Instead, we can do everything in the client config one time.
This has also dramatically simplified the client side prop drilling
through the UI library. Now, all components can share the same client
config which matches the exact shape of their Payload config (with the
exception of non-serializable props and mapped custom components).

This is breaking change. The `useComponentMap` hook no longer exists,
and most component props have changed (for the better):

```ts
const { componentMap } = useComponentMap() // old
const { config } = useConfig() // new
```

The `useConfig` hook has also changed in shape, `config` is now a
property _within_ the context obj:

```ts
const config = useConfig() // old
const { config } = useConfig() // new
```

## Custom Client Components are no longer server rendered

Previously, custom components would be server-rendered, no matter if
they are server or client components. Now, only server components are
rendered on the server. Client components are automatically detected,
and simply get passed through as `MappedComponent` to be rendered fully
client-side.

The benefit of this change:

Custom client components can now receive props. Previously, the only way
for them to receive dynamic props from a parent client component was to
use hooks, e.g. `useFieldProps()`. Now, we do have the option of passing
in props to the custom components directly, if they are client
components. This will be simpler than having to look for the correct
hook.

This makes rendering them on the client a little bit more complex, as
you now have to check if that component is a server component (=>
already has been rendered) or a client component (=> not rendered yet,
has to be rendered here). However, this added complexity has been
alleviated through the easy-to-use `<RenderMappedComponent />` helper.

This helper now also handles rendering arrays of custom components (e.g.
beforeList, beforeLogin ...), which actually makes rendering custom
components easier in some cases.

## Misc improvements

This PR includes misc, breaking changes. For example, we previously
allowed unions between components and config object for the same
property. E.g. for the custom view property, you were allowed to pass in
a custom component or an object with other properties, alongside a
custom component.

Those union types are now gone. You can now either pass an object, or a
component. The previous `{ View: MyViewComponent}` is now `{ View: {
Component: MyViewComponent} }` or `{ View: { Default: { Component:
MyViewComponent} } }`.

This dramatically simplifies the way we read & process those properties,
especially in buildComponentMap. We can now simply check for the
existence of one specific property, which always has to be a component,
instead of running cursed runtime checks on a shared union property
which could contain a component, but could also contain functions or
objects.

![CleanShot 2024-07-29 at 23 07
07@2x](https://github.com/user-attachments/assets/1e75aa4c-7a4c-419f-9070-216bb7b9a5e5)

![CleanShot 2024-07-29 at 23 09
40@2x](https://github.com/user-attachments/assets/b4c96450-6b7e-496c-a4f7-59126bfd0991)

- [x] I have read and understand the
[CONTRIBUTING.md](https://github.com/payloadcms/payload/blob/main/CONTRIBUTING.md)
document in this repository.

---------

Co-authored-by: PatrikKozak <[email protected]>
Co-authored-by: Paul <[email protected]>
Co-authored-by: Paul Popus <[email protected]>
Co-authored-by: Jacob Fletcher <[email protected]>
Co-authored-by: James <[email protected]>

Author: 5 people

.gitignore

@@ -5,6 +5,7 @@ dist
 !/.idea/runConfigurations
 !/.idea/payload.iml
 
+
 test-results
 .devcontainer
 .localstack
@@ -300,3 +301,8 @@ $RECYCLE.BIN/
 
 /build
 .swc
+app/(payload)/admin/importMap.js
+test/live-preview/app/(payload)/admin/importMap.js
+/test/live-preview/app/(payload)/admin/importMap.js
+test/admin-root/app/(payload)/admin/importMap.js
+/test/admin-root/app/(payload)/admin/importMap.js

.husky/pre-commit

@@ -1 +0,0 @@
-pnpm run lint-staged --quiet

.idea/payload.iml

@@ -42,8 +42,8 @@
     }
   },
   "files.insertFinalNewline": true,
-  "jestrunner.jestCommand": "pnpm exec cross-env NODE_OPTIONS=\"--experimental-vm-modules --no-deprecation\" node 'node_modules/jest/bin/jest.js'",
+  "jestrunner.jestCommand": "pnpm exec cross-env NODE_OPTIONS=\"--no-deprecation\" node 'node_modules/jest/bin/jest.js'",
   "jestrunner.debugOptions": {
-    "runtimeArgs": ["--experimental-vm-modules", "--no-deprecation"]
+    "runtimeArgs": ["--no-deprecation"]
   }
 }

.idea/runConfigurations/Run_Dev_Fields.xml

@@ -0,0 +1,14 @@
+import React from 'react'
+
+export const metadata = {
+  description: 'Generated by Next.js',
+  title: 'Next.js',
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}

.idea/runConfigurations/Run_Dev__community.xml

@@ -0,0 +1,11 @@
+import configPromise from '@payload-config'
+import { getPayloadHMR } from '@payloadcms/next/utilities'
+
+export const Page = async ({ params, searchParams }) => {
+  const payload = await getPayloadHMR({
+    config: configPromise,
+  })
+  return <div>test ${payload?.config?.collections?.length}</div>
+}
+
+export default Page

.idea/runConfigurations/Run_Dev_admin.xml

@@ -5,6 +5,8 @@ import config from '@payload-config'
 /* DO NOT MODIFY IT BECAUSE IT COULD BE REWRITTEN AT ANY TIME. */
 import { NotFoundPage, generatePageMetadata } from '@payloadcms/next/views'
 
+import { importMap } from '../importMap.js'
+
 type Args = {
   params: {
     segments: string[]
@@ -17,6 +19,7 @@ type Args = {
 export const generateMetadata = ({ params, searchParams }: Args): Promise<Metadata> =>
   generatePageMetadata({ config, params, searchParams })
 
-const NotFound = ({ params, searchParams }: Args) => NotFoundPage({ config, params, searchParams })
+const NotFound = ({ params, searchParams }: Args) =>
+  NotFoundPage({ config, importMap, params, searchParams })
 
 export default NotFound

.idea/runConfigurations/_template__of_JavaScriptTestRunnerJest.xml

@@ -5,6 +5,8 @@ import config from '@payload-config'
 /* DO NOT MODIFY IT BECAUSE IT COULD BE REWRITTEN AT ANY TIME. */
 import { RootPage, generatePageMetadata } from '@payloadcms/next/views'
 
+import { importMap } from '../importMap.js'
+
 type Args = {
   params: {
     segments: string[]
@@ -17,6 +19,7 @@ type Args = {
 export const generateMetadata = ({ params, searchParams }: Args): Promise<Metadata> =>
   generatePageMetadata({ config, params, searchParams })
 
-const Page = ({ params, searchParams }: Args) => RootPage({ config, params, searchParams })
+const Page = ({ params, searchParams }: Args) =>
+  RootPage({ config, importMap, params, searchParams })
 
 export default Page

.vscode/settings.json

@@ -1,6 +1,9 @@
 /* THIS FILE WAS GENERATED AUTOMATICALLY BY PAYLOAD. */
 import configPromise from '@payload-config'
 import { RootLayout } from '@payloadcms/next/layouts'
+
+import { importMap } from './admin/importMap.js'
+
 // import '@payloadcms/ui/styles.css' // Uncomment this line if `@payloadcms/ui` in `tsconfig.json` points to `/ui/dist` instead of `/ui/src`
 /* DO NOT MODIFY IT BECAUSE IT COULD BE REWRITTEN AT ANY TIME. */
 import React from 'react'
@@ -11,6 +14,10 @@ type Args = {
   children: React.ReactNode
 }
 
-const Layout = ({ children }: Args) => <RootLayout config={configPromise}>{children}</RootLayout>
+const Layout = ({ children }: Args) => (
+  <RootLayout config={configPromise} importMap={importMap}>
+    {children}
+  </RootLayout>
+)
 
 export default Layout

app/(app)/layout.tsx

@@ -51,7 +51,6 @@ To override Collection Components, use the `admin.components` property in your [
 
 ```ts
 import type { SanitizedCollectionConfig } from 'payload'
-import { CustomSaveButton } from './CustomSaveButton'
 
 export const MyCollection: SanitizedCollectionConfig = {
   // ...

app/(app)/test/page.tsx

@@ -33,8 +33,6 @@ To override Root Components, use the `admin.components` property in your [Payloa
 ```ts
 import { buildConfig } from 'payload'
 
-import { MyCustomLogo } from './MyCustomLogo'
-
 export default buildConfig({
   // ...
   admin: {
@@ -81,13 +79,11 @@ To add a Custom Provider, use the `admin.components.providers` property in your
 ```ts
 import { buildConfig } from 'payload'
 
-import { MyProvider } from './MyProvider'
-
 export default buildConfig({
   // ...
   admin: {
     components: {
-      providers: [MyProvider], // highlight-line
+      providers: ['/path/to/MyProvider'], // highlight-line
     },
   },
 })
@@ -207,7 +203,7 @@ import React from 'react'
 import { useConfig } from '@payloadcms/ui'
 
 export const MyClientComponent: React.FC = () => {
-  const { serverURL } = useConfig() // highlight-line
+  const { config: { serverURL } } = useConfig() // highlight-line
 
   return (
     <Link href={serverURL}>
@@ -221,6 +217,22 @@ export const MyClientComponent: React.FC = () => {
   See [Using Hooks](#using-hooks) for more details.
 </Banner>
 
+All [Field Components](./fields) automatically receive their respective Client Field Config through a common [`field`](./fields#the-field-prop) prop:
+
+```tsx
+'use client'
+import React from 'react'
+import type { TextFieldProps } from 'payload'
+
+export const MyClientFieldComponent: TextFieldProps = ({ field: { name } }) => {
+  return (
+    <p>
+      {`This field's name is ${name}`}
+    </p>
+  )
+}
+```
+
 ### Using Hooks
 
 To make it easier to [build your Custom Components](#building-custom-components), you can use [Payload's built-in React Hooks](./hooks) in any Client Component. For example, you might want to interact with one of Payload's many React Contexts: