feat!: component paths (#7246)

This PR ensures that the payload config is 100% server-only. 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 3.0 release does not rely on
vercel/next.js#65415 which will likely will not
get merged. Now, the Payload config will be significantly more
lightweight.

Related discussion:
#6938

## The issue

This PR fixes a few issues:

#4085
#6598
#6441
#7261 #7339

### 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.

### Custom Client Components are not server-rendered anymore

Previously, custom components would be server-rendered in
`buildComponentMap`, no matter if they are server or client components.
Now, only server components are rendered in `buildComponentMap`. Client
components simply get passed through, using `MappedComponent` as a
container. It is then the client's responsibility to render those.

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.

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,

### 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)


## Custom Components

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.

E.g.

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

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

Now becomes:

```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
  },
},
```

## Concepts: MappedComponent and PayloadComponent

Instead of `React.FC` / `React.ComponentType`, props within the payload
config that accept components now accept `PayloadComponent`. These are
basically the paths to the component. They can be a string, or an object
containing other properties like serverProps and clientProps - giving
you full control over the props this component will eventually receive.

`MappedComponent` is the result of buildComponentMap processing all
those `PayloadComponent`s. It contains the server-rendered component, or
unrendered/rendered client component. Any `MappedComponent` can be
rendered on both either the client and the server using the
`RenderMappedComponent` helper component.

## Try it out
This can be tested out here:
https://github.com/payloadcms/payload-3.0-demo/tree/feat/path-test

## Todo
- Migrate all payload plugins to new import pattern & get it to build
- Migrate test suites to new import pattern
- Clean-up, simplify component handling within core, add JSDocs
- Add Docs
- Collect all breaking changes

---------

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

.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

app/(app)/layout.tsx

@@ -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>
+  )
+}

app/(app)/test/page.tsx

@@ -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

app/(payload)/admin/[[...segments]]/not-found.tsx

@@ -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

app/(payload)/admin/[[...segments]]/page.tsx

@@ -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

app/(payload)/layout.tsx

@@ -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

eslint.config.js

@@ -28,6 +28,7 @@ export const rootParserOptions = {
   EXPERIMENTAL_useSourceOfProjectReferenceRedirect: true,
   EXPERIMENTAL_useProjectService: {
     allowDefaultProjectForFiles: ['./src/*.ts', './src/*.tsx'],
+    maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 100,
   },
   sourceType: 'module',
   ecmaVersion: 'latest',

next.config.mjs

@@ -1,6 +1,11 @@
 import bundleAnalyzer from '@next/bundle-analyzer'
 
 import withPayload from './packages/next/src/withPayload.js'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const dirname = path.dirname(__filename)
 
 const withBundleAnalyzer = bundleAnalyzer({
   enabled: process.env.ANALYZE === 'true',
@@ -15,6 +20,10 @@ export default withBundleAnalyzer(
     typescript: {
       ignoreBuildErrors: true,
     },
+    env: {
+      PAYLOAD_CORE_DEV: 'true',
+      ROOT_DIR: path.resolve(dirname),
+    },
     async redirects() {
       return [
         {

package.json

@@ -20,6 +20,7 @@
     "build:email-nodemailer": "turbo build --filter email-nodemailer",
     "build:email-resend": "turbo build --filter email-resend",
     "build:eslint-config": "turbo build --filter eslint-config",
+    "build:essentials:force": "pnpm clean:build && turbo build --filter=\"payload...\" --filter=\"@payloadcms/ui\" --filter=\"@payloadcms/next\" --filter=\"@payloadcms/db-mongodb\" --filter=\"@payloadcms/db-postgres\" --filter=\"@payloadcms/richtext-lexical\" --filter=\"@payloadcms/translations\" --filter=\"@payloadcms/plugin-cloud\" --filter=\"@payloadcms/graphql\" --no-cache --force",
     "build:force": "pnpm run build:core:force",
     "build:graphql": "turbo build --filter graphql",
     "build:live-preview": "turbo build --filter live-preview",
@@ -52,10 +53,11 @@
     "clean:all": "node ./scripts/delete-recursively.js '@node_modules' 'media/*' '**/dist/' '**/.cache/*' '**/.next/*' '**/.turbo/*' '**/tsconfig.tsbuildinfo' '**/payload*.tgz' '**/meta_*.json'",
     "clean:build": "node ./scripts/delete-recursively.js 'media/' '**/dist/' '**/.cache/' '**/.next/' '**/.turbo/' '**/tsconfig.tsbuildinfo' '**/payload*.tgz' '**/meta_*.json'",
     "clean:cache": "node ./scripts/delete-recursively.js node_modules/.cache! packages/payload/node_modules/.cache! .next/*",
-    "dev": "cross-env NODE_OPTIONS=--no-deprecation node ./test/dev.js",
+    "dev": "cross-env NODE_OPTIONS=--no-deprecation tsx ./test/dev.ts",
     "dev:generate-graphql-schema": "cross-env NODE_OPTIONS=--no-deprecation tsx ./test/generateGraphQLSchema.ts",
+    "dev:generate-importMap": "cross-env NODE_OPTIONS=--no-deprecation tsx ./test/generateImportMap.ts",
     "dev:generate-types": "cross-env NODE_OPTIONS=--no-deprecation tsx ./test/generateTypes.ts",
-    "dev:postgres": "cross-env NODE_OPTIONS=--no-deprecation PAYLOAD_DATABASE=postgres node ./test/dev.js",
+    "dev:postgres": "cross-env NODE_OPTIONS=--no-deprecation PAYLOAD_DATABASE=postgres tsx ./test/dev.ts",
     "devsafe": "node ./scripts/delete-recursively.js '**/.next' && pnpm dev",
     "docker:restart": "pnpm docker:stop --remove-orphans && pnpm docker:start",
     "docker:start": "docker compose -f packages/plugin-cloud-storage/docker-compose.yml up -d",

packages/db-mongodb/src/types.ts

@@ -67,31 +67,6 @@ export type FieldGenerator<TSchema, TField> = {
   schema: TSchema
 }
 
-/**
- * Field config types that need representation in the database
- */
-type FieldType =
-  | 'array'
-  | 'blocks'
-  | 'checkbox'
-  | 'code'
-  | 'collapsible'
-  | 'date'
-  | 'email'
-  | 'group'
-  | 'json'
-  | 'number'
-  | 'point'
-  | 'radio'
-  | 'relationship'
-  | 'richText'
-  | 'row'
-  | 'select'
-  | 'tabs'
-  | 'text'
-  | 'textarea'
-  | 'upload'
-
 export type FieldGeneratorFunction<TSchema, TField extends Field> = (
   args: FieldGenerator<TSchema, TField>,
 ) => void

packages/next/src/elements/DocumentHeader/Tabs/Tab/index.tsx

@@ -1,28 +1,32 @@
 import type { DocumentTabConfig, DocumentTabProps } from 'payload'
 
+import { RenderComponent, getCreateMappedComponent } from '@payloadcms/ui/shared'
 import React, { Fragment } from 'react'
 
 import { DocumentTabLink } from './TabLink.js'
 import './index.scss'
 
 export const baseClass = 'doc-tab'
 
-export const DocumentTab: React.FC<DocumentTabConfig & DocumentTabProps> = (props) => {
+export const DocumentTab: React.FC<
+  { Pill_Component?: React.FC } & DocumentTabConfig & DocumentTabProps
+> = (props) => {
   const {
     Pill,
+    Pill_Component,
     apiURL,
     collectionConfig,
     condition,
-    config,
     globalConfig,
     href: tabHref,
     i18n,
     isActive: tabIsActive,
     label,
     newTab,
+    payload,
     permissions,
   } = props
-
+  const { config } = payload
   const { routes } = config
 
   let href = typeof tabHref === 'string' ? tabHref : ''
@@ -55,6 +59,17 @@ export const DocumentTab: React.FC<DocumentTabConfig & DocumentTabProps> = (prop
           })
         : label
 
+    const createMappedComponent = getCreateMappedComponent({
+      importMap: payload.importMap,
+      serverProps: {
+        i18n,
+        payload,
+        permissions,
+      },
+    })
+
+    const mappedPin = createMappedComponent(Pill, undefined, Pill_Component)
+
     return (
       <DocumentTabLink
         adminRoute={routes.admin}
@@ -67,10 +82,10 @@ export const DocumentTab: React.FC<DocumentTabConfig & DocumentTabProps> = (prop
       >
         <span className={`${baseClass}__label`}>
           {labelToRender}
-          {Pill && (
+          {mappedPin && (
             <Fragment>
               &nbsp;
-              <Pill />
+              <RenderComponent mappedComponent={mappedPin} />
             </Fragment>
           )}
         </span>

packages/next/src/elements/DocumentHeader/Tabs/index.tsx

@@ -1,11 +1,12 @@
 import type { I18n } from '@payloadcms/translations'
 import type {
+  Payload,
   Permissions,
   SanitizedCollectionConfig,
-  SanitizedConfig,
   SanitizedGlobalConfig,
 } from 'payload'
 
+import { RenderComponent, getCreateMappedComponent } from '@payloadcms/ui/shared'
 import { isPlainObject } from 'payload'
 import React from 'react'
 
@@ -20,12 +21,13 @@ const baseClass = 'doc-tabs'
 
 export const DocumentTabs: React.FC<{
   collectionConfig: SanitizedCollectionConfig
-  config: SanitizedConfig
   globalConfig: SanitizedGlobalConfig
   i18n: I18n
+  payload: Payload
   permissions: Permissions
 }> = (props) => {
-  const { collectionConfig, config, globalConfig, permissions } = props
+  const { collectionConfig, globalConfig, i18n, payload, permissions } = props
+  const { config } = payload
 
   const customViews = getCustomViews({ collectionConfig, globalConfig })
 
@@ -82,7 +84,29 @@ export const DocumentTabs: React.FC<{
                 }
 
                 if (typeof Tab === 'function') {
-                  return <Tab path={path} {...props} key={`tab-custom-${index}`} />
+                  const createMappedComponent = getCreateMappedComponent({
+                    importMap: payload.importMap,
+                    serverProps: {
+                      i18n,
+                      payload,
+                      permissions,
+                      ...props,
+                      key: `tab-custom-${index}`,
+                      path,
+                    },
+                  })
+
+                  const mappedTab = createMappedComponent(Tab)
+                  return (
+                    <RenderComponent
+                      clientProps={{
+                        key: `tab-custom-${index}`,
+                        path,
+                      }}
+                      key={`tab-custom-${index}`}
+                      mappedComponent={mappedTab}
+                    />
+                  )
                 }
 
                 return (

packages/next/src/elements/DocumentHeader/Tabs/tabs/index.tsx

@@ -1,4 +1,5 @@
 import type { DocumentTabConfig } from 'payload'
+import type React from 'react'
 
 import { VersionsPill } from './VersionsPill/index.js'
 
@@ -17,6 +18,7 @@ export type DocumentViewKey = (typeof documentViewKeys)[number]
 export const tabs: Record<
   DocumentViewKey,
   {
+    Pill_Component?: React.FC
     order?: number // TODO: expose this to the globalConfig config
   } & DocumentTabConfig
 > = {
@@ -67,7 +69,7 @@ export const tabs: Record<
     condition: () => false,
   },
   Versions: {
-    Pill: VersionsPill,
+    Pill_Component: VersionsPill,
     condition: ({ collectionConfig, globalConfig, permissions }) =>
       Boolean(
         (collectionConfig?.versions &&