feat(ui): implement narrow renderFields server function

packages/payload/src/admin/forms/renderFieldsTypes.ts

@@ -18,8 +18,11 @@ export type RenderFieldsRequest = {
 
 export type RenderedFieldEntry = {
   path: string
-  /** RSC payload string (text/x-component) for the rendered component. */
-  payload: string
+  /**
+   * Rendered React element for the component. Serialized to RSC at the
+   * server-action boundary by Next.js — not by `renderFields` itself.
+   */
+  payload: unknown
   slot: RenderFieldsSlot
 }
 

packages/payload/src/exports/internal.ts

@@ -2,6 +2,14 @@
  * Modules exported here are not part of the public API and are subject to change without notice and without a major version bump.
  */
 
+export type {
+  RenderedFieldEntry,
+  RenderFieldsError,
+  RenderFieldsRequest,
+  RenderFieldsResponse,
+  RenderFieldsSlot,
+  RenderFieldsTarget,
+} from '../admin/forms/renderFieldsTypes.js'
 export { getExternalFile } from '../uploads/getExternalFile.js'
 export { getRangeRequestInfo } from '../uploads/getRangeRequestInfo.js'
 export { getSafeFileName } from '../uploads/getSafeFilename.js'

packages/ui/package.json

@@ -96,6 +96,11 @@
       "types": "./src/utilities/buildFieldSchemaMap/traverseFields.ts",
       "default": "./src/utilities/buildFieldSchemaMap/traverseFields.ts"
     },
+    "./utilities/renderFields": {
+      "import": "./src/utilities/renderFields.ts",
+      "types": "./src/utilities/renderFields.ts",
+      "default": "./src/utilities/renderFields.ts"
+    },
     "./forms/fieldSchemasToFormState": {
       "import": "./src/forms/fieldSchemasToFormState/index.tsx",
       "types": "./src/forms/fieldSchemasToFormState/index.tsx",

packages/ui/src/forms/fieldSchemasToFormState/renderSingleField.tsx

@@ -0,0 +1,53 @@
+import type { ImportMap, PayloadRequest, SanitizedConfig } from 'payload'
+import type React from 'react'
+
+import { RenderServerComponent } from '../../elements/RenderServerComponent/index.js'
+
+type ComponentSlot =
+  | 'afterInput'
+  | 'beforeInput'
+  | 'Description'
+  | 'Error'
+  | 'Field'
+  | 'Label'
+  | 'RowLabel'
+
+type RenderSingleFieldArgs = {
+  /** Module path/specifier of the component as recorded in the component index. */
+  componentPath: string
+  config: SanitizedConfig
+  /** Field path, e.g. `posts.renderTracker`. Forwarded to the component as `path`/`schemaPath`. */
+  fieldPath: string
+  importMap: ImportMap
+  req: PayloadRequest
+  slot: ComponentSlot
+}
+
+/**
+ * Renders a single component referenced by the component index, returning a
+ * React element. Intentionally narrow: it does not walk the schema, build a
+ * client field, load document data, or compute defaults. Callers that need
+ * those concerns should layer them on top.
+ */
+export async function renderSingleField(args: RenderSingleFieldArgs): Promise<React.ReactNode> {
+  const { componentPath, fieldPath, importMap, req } = args
+
+  const clientProps = {
+    path: fieldPath,
+    schemaPath: fieldPath,
+  }
+
+  const serverProps = {
+    i18n: req.i18n,
+    payload: req.payload,
+    req,
+    user: req.user,
+  }
+
+  return RenderServerComponent({
+    clientProps,
+    Component: { path: componentPath },
+    importMap,
+    serverProps,
+  })
+}

packages/ui/src/utilities/renderFields.ts

@@ -0,0 +1,73 @@
+import type { Payload, PayloadRequest } from 'payload'
+import type { RenderFieldsRequest, RenderFieldsResponse } from 'payload/internal'
+
+import { renderSingleField } from '../forms/fieldSchemasToFormState/renderSingleField.js'
+
+type RenderFieldsArgs = {
+  payload: Payload
+  req: PayloadRequest
+  request: RenderFieldsRequest
+}
+
+/**
+ * Renders the components requested by `request.render` and returns their
+ * React elements. Resolution is driven by `payload.config.componentIndex` —
+ * this function does NOT walk the schema, load document data, or compute
+ * defaults. Errors are isolated per target so a single failure does not
+ * abort the batch.
+ */
+export async function renderFields(args: RenderFieldsArgs): Promise<RenderFieldsResponse> {
+  const { payload, req, request } = args
+  const index = payload.config.componentIndex
+  const importMap = payload.importMap
+
+  const rendered: RenderFieldsResponse['rendered'] = []
+  const errors: NonNullable<RenderFieldsResponse['errors']> = []
+
+  if (!index) {
+    for (const target of request.render) {
+      errors.push({
+        message: 'componentIndex not configured on payload.config',
+        path: target.path,
+        slot: target.slot,
+      })
+    }
+    return errors.length > 0 ? { errors, rendered } : { rendered }
+  }
+
+  for (const target of request.render) {
+    try {
+      const matched = index
+        .componentsAt(target.path)
+        .find((c) => c.slot === target.slot && c.path === target.path)
+
+      if (!matched) {
+        errors.push({
+          message: 'No registered component at path/slot',
+          path: target.path,
+          slot: target.slot,
+        })
+        continue
+      }
+
+      const element = await renderSingleField({
+        componentPath: matched.componentPath,
+        config: payload.config,
+        fieldPath: matched.path,
+        importMap,
+        req,
+        slot: matched.slot,
+      })
+
+      rendered.push({ path: target.path, payload: element, slot: target.slot })
+    } catch (err) {
+      errors.push({
+        message: err instanceof Error ? err.message : String(err),
+        path: target.path,
+        slot: target.slot,
+      })
+    }
+  }
+
+  return errors.length > 0 ? { errors, rendered } : { rendered }
+}

test/form-state/renderFields.int.spec.ts

@@ -0,0 +1,102 @@
+import type { Payload } from 'payload'
+
+import { renderFields } from '@payloadcms/ui/utilities/renderFields'
+import path from 'path'
+import { createLocalReq } from 'payload'
+import { fileURLToPath } from 'url'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+
+import { initPayloadInt } from '../__helpers/shared/initPayloadInt.js'
+import { ArrayRowLabel } from './collections/Posts/ArrayRowLabel.js'
+import { RenderTracker } from './collections/Posts/RenderTracker.js'
+import { CustomTextField } from './collections/Posts/TextField.js'
+
+const filename = fileURLToPath(import.meta.url)
+const dirname = path.dirname(filename)
+
+let payload: Payload
+
+describe('renderFields server function', () => {
+  beforeAll(async () => {
+    ;({ payload } = await initPayloadInt(dirname, undefined, true))
+
+    // Integration tests run outside Next.js, so the admin layout never loads
+    // the generated `app/(payload)/admin/importMap.js` into `payload.importMap`.
+    // Build the map directly from the components referenced by the form-state
+    // config — the auto-injected `@payloadcms/next/rsc` entries aren't
+    // resolvable in the int runtime, but they are not exercised by these tests.
+    payload.importMap = {
+      './collections/Posts/RenderTracker.js#RenderTracker': RenderTracker,
+      './collections/Posts/TextField.js#CustomTextField': CustomTextField,
+      './collections/Posts/ArrayRowLabel.js#ArrayRowLabel': ArrayRowLabel,
+    }
+  })
+
+  afterAll(async () => {
+    await payload.destroy()
+  })
+
+  it('renders a single component and returns its element', async () => {
+    const req = await createLocalReq({ user: null }, payload)
+    const result = await renderFields({
+      payload,
+      req,
+      request: {
+        collectionSlug: 'posts',
+        render: [{ path: 'posts.renderTracker', slot: 'Field' }],
+      },
+    })
+
+    expect(result.rendered).toHaveLength(1)
+    expect(result.rendered[0]).toMatchObject({
+      path: 'posts.renderTracker',
+      slot: 'Field',
+    })
+    expect(result.rendered[0]!.payload).toBeDefined()
+    expect(result.errors).toBeUndefined()
+  })
+
+  it('isolates per-component errors', async () => {
+    const req = await createLocalReq({ user: null }, payload)
+    const result = await renderFields({
+      payload,
+      req,
+      request: {
+        collectionSlug: 'posts',
+        render: [
+          { path: 'posts.renderTracker', slot: 'Field' },
+          { path: 'posts.does-not-exist', slot: 'Field' },
+        ],
+      },
+    })
+
+    expect(result.rendered).toHaveLength(1)
+    expect(result.errors).toHaveLength(1)
+    expect(result.errors![0]!.path).toBe('posts.does-not-exist')
+  })
+
+  it('does not walk the config or compute defaults', async () => {
+    const req = await createLocalReq({ user: null }, payload)
+    // Warm up to avoid first-call import/cache penalties.
+    await renderFields({
+      payload,
+      req,
+      request: {
+        collectionSlug: 'posts',
+        render: [{ path: 'posts.renderTracker', slot: 'Field' }],
+      },
+    })
+
+    const t0 = performance.now()
+    await renderFields({
+      payload,
+      req,
+      request: {
+        collectionSlug: 'posts',
+        render: [{ path: 'posts.renderTracker', slot: 'Field' }],
+      },
+    })
+    const elapsed = performance.now() - t0
+    expect(elapsed).toBeLessThan(200)
+  })
+})