refactor(next)!: move templates and elements to @payloadcms/ui (#16765)

Requires #16763 and #16753.

Moves all elements and templates defined in the `@payloadcms/next`
package to `@payloadcms/ui`. This is in effort to convert the
`@payloadcms/next` package into a framework adapter.

**Relocated exports** — code physically moved from `@payloadcms/next` to
`@payloadcms/ui`:

| Component | Old source | New source |
| -------------------------- | ----------------------------- |
---------------------- |
| `DefaultTemplate` | `@payloadcms/next/templates` |
`@payloadcms/ui/rsc` |
| `DefaultTemplateProps` | `@payloadcms/next/templates` |
`@payloadcms/ui/rsc` |
| `MinimalTemplate` | `@payloadcms/next/templates` |
`@payloadcms/ui/rsc` |
| `MinimalTemplateProps` | `@payloadcms/next/templates` |
`@payloadcms/ui/rsc` |
| `DocumentHeader` | `@payloadcms/next/rsc` | `@payloadcms/ui/rsc` |
| `DefaultNav` | `@payloadcms/next/rsc` | `@payloadcms/ui/rsc` |
| `Logo` | `@payloadcms/next/rsc` | `@payloadcms/ui/rsc` |
| `HierarchyTypeFieldServer` | `@payloadcms/next/rsc` |
`@payloadcms/ui/rsc` |
| `DefaultNavClient` | `@payloadcms/next/client` | `@payloadcms/ui` |
| `HierarchyTypeField` | `@payloadcms/next/client` | `@payloadcms/ui` |
| `NavSidebarToggle` | `@payloadcms/next/client` | `@payloadcms/ui` |
| `NavWrapper` | `@payloadcms/next/client` | `@payloadcms/ui` |

This PR also removes the now unneeded export aliases. These were in
place for backwards compatibility during v3. Now, we enforce that all
imports point to its canonical source, not the aliased export.

| Component | Old source | New source |
| -------------------------- | ------------------------- |
--------------------- |
| `CollectionCards` | `@payloadcms/next/rsc` | `@payloadcms/ui/rsc` |
| `SlugField` | `@payloadcms/next/client` | `@payloadcms/ui` |
| `QueryPresetsAccessCell` | `@payloadcms/next/client` |
`@payloadcms/ui` |
| `QueryPresetsColumnField` | `@payloadcms/next/client` |
`@payloadcms/ui` |
| `QueryPresetsColumnsCell` | `@payloadcms/next/client` |
`@payloadcms/ui` |
| `QueryPresetsGroupByCell` | `@payloadcms/next/client` |
`@payloadcms/ui` |
| `QueryPresetsGroupByField` | `@payloadcms/next/client` |
`@payloadcms/ui` |
| `QueryPresetsWhereCell` | `@payloadcms/next/client` | `@payloadcms/ui`
|
| `QueryPresetsWhereField` | `@payloadcms/next/client` |
`@payloadcms/ui` |

The `./client`, `./rsc`, and `./templates` subpath exports on
`@payloadcms/next` are removed entirely.

#### Codemod

To migrate automatically, there's a codemod for this change available by
running:

```bash
npx @payloadcms/codemod --transform migrate-next-subpath-exports
```

Author: jacobsfletch

docs/custom-components/custom-views.mdx

@@ -177,8 +177,8 @@ Here is an example of how to use the Default Template in your Custom View:
 ```tsx
 import type { AdminViewServerProps } from 'payload'
 
-import { DefaultTemplate } from '@payloadcms/next/templates'
 import { Gutter } from '@payloadcms/ui'
+import { DefaultTemplate } from '@payloadcms/ui/rsc'
 import React from 'react'
 
 export function MyCustomView({

docs/migration-guide/v4.mdx

@@ -205,6 +205,44 @@ If you were relying on Next-specific extras like `prefetch()` on the router inst
   />
 ```
 
+### `@payloadcms/next/client`, `@payloadcms/next/rsc`, and `@payloadcms/next/templates` removed
+
+The `./client`, `./rsc`, and `./templates` subpath exports on `@payloadcms/next` were thin re-exports of components that now live in `@payloadcms/ui`. All admin elements (DocumentHeader, FormHeader, HierarchyTypeField, Logo, Nav) and templates (DefaultTemplate, MinimalTemplate) have been relocated to `@payloadcms/ui` and no longer depend on `next/*` modules. Import them directly from the canonical source.
+
+| Symbol                     | Old source                   | New source           |
+| -------------------------- | ---------------------------- | -------------------- |
+| `DefaultTemplate`          | `@payloadcms/next/templates` | `@payloadcms/ui/rsc` |
+| `MinimalTemplate`          | `@payloadcms/next/templates` | `@payloadcms/ui/rsc` |
+| `CollectionCards`          | `@payloadcms/next/rsc`       | `@payloadcms/ui/rsc` |
+| `DefaultNav`               | `@payloadcms/next/rsc`       | `@payloadcms/ui/rsc` |
+| `DocumentHeader`           | `@payloadcms/next/rsc`       | `@payloadcms/ui/rsc` |
+| `HierarchyTypeFieldServer` | `@payloadcms/next/rsc`       | `@payloadcms/ui/rsc` |
+| `Logo`                     | `@payloadcms/next/rsc`       | `@payloadcms/ui/rsc` |
+| `DefaultNavClient`         | `@payloadcms/next/client`    | `@payloadcms/ui`     |
+| `HierarchyTypeField`       | `@payloadcms/next/client`    | `@payloadcms/ui`     |
+| `NavSidebarToggle`         | `@payloadcms/next/client`    | `@payloadcms/ui`     |
+| `NavWrapper`               | `@payloadcms/next/client`    | `@payloadcms/ui`     |
+| `QueryPresetsAccessCell`   | `@payloadcms/next/client`    | `@payloadcms/ui`     |
+| `QueryPresetsColumnField`  | `@payloadcms/next/client`    | `@payloadcms/ui`     |
+| `QueryPresetsColumnsCell`  | `@payloadcms/next/client`    | `@payloadcms/ui`     |
+| `QueryPresetsGroupByCell`  | `@payloadcms/next/client`    | `@payloadcms/ui`     |
+| `QueryPresetsGroupByField` | `@payloadcms/next/client`    | `@payloadcms/ui`     |
+| `QueryPresetsWhereCell`    | `@payloadcms/next/client`    | `@payloadcms/ui`     |
+| `QueryPresetsWhereField`   | `@payloadcms/next/client`    | `@payloadcms/ui`     |
+| `SlugField`                | `@payloadcms/next/client`    | `@payloadcms/ui`     |
+
+```diff
+- import { DefaultTemplate, MinimalTemplate } from '@payloadcms/next/templates'
+- import { DocumentHeader, Logo } from '@payloadcms/next/rsc'
+- import { HierarchyTypeField, SlugField } from '@payloadcms/next/client'
++ import { DefaultTemplate, DocumentHeader, Logo, MinimalTemplate } from '@payloadcms/ui/rsc'
++ import { HierarchyTypeField, SlugField } from '@payloadcms/ui'
+```
+
+If you reference any of these components by string path in your Payload config (e.g. `Component: '@payloadcms/next/rsc#CollectionCards'`), update the path string too — then regenerate the import map with `payload generate:importmap`.
+
+Run `npx @payloadcms/codemod --transform migrate-next-subpath-exports` to migrate automatically. It rewrites both `import` declarations and string component paths.
+
 ### `title` and `setDocumentTitle` removed from `useDocumentInfo`
 
 For performance reasons, the document title state has been split out of `DocumentInfoContext` into its own `DocumentTitleContext`. Access it through the `useDocumentTitle` hook, which exposes the same `title` and `setDocumentTitle` API. Components that subscribed to `useDocumentInfo` solely for the title will no longer re-render when unrelated document state changes.

examples/custom-components/src/components/views/CustomDefaultRootView.tsx

@@ -1,7 +1,7 @@
 import type { AdminViewProps } from 'payload'
 
-import { DefaultTemplate } from '@payloadcms/next/templates'
 import { Gutter } from '@payloadcms/ui'
+import { DefaultTemplate } from '@payloadcms/ui/rsc'
 import React from 'react'
 
 export const CustomDefaultRootView: React.FC<AdminViewProps> = ({

examples/custom-components/src/components/views/CustomMinimalRootView.tsx

@@ -1,7 +1,7 @@
 import type { AdminViewProps } from 'payload'
 
-import { MinimalTemplate } from '@payloadcms/next/templates'
 import { Gutter } from '@payloadcms/ui'
+import { MinimalTemplate } from '@payloadcms/ui/rsc'
 import React from 'react'
 
 export const CustomMinimalRootView: React.FC<AdminViewProps> = () => {

packages/codemod/README.md

@@ -36,6 +36,7 @@ The tool loads your project via [ts-morph](https://ts-morph.com/), using your `t
 - `rename-storage-adapters-to-storage` — renames the top-level `storageAdapters` config property to `storage`. Skips any object that already has a `storage` property. Run this if you previously ran `migrate-storage-adapters-to-config` and need to update the property name.
 - `migrate-import-export-hooks` — migrates the deprecated `toCSV` and `fromCSV` field options in `custom['plugin-import-export']` to `hooks.beforeExport` and `hooks.beforeImport`. If a `hooks` object already exists it is merged into; if `hooks.beforeExport`/`hooks.beforeImport` already exist the deprecated sibling is dropped without overwriting. Review argument shapes after migration: `beforeExport` uses `siblingData` (not `row`) and `data` is the top-level document (previously `doc`).
 - `migrate-db-types-subpath` — rewrites imports from the removed `/types` subpath exports of `@payloadcms/drizzle`, `@payloadcms/db-postgres`, `@payloadcms/db-sqlite`, `@payloadcms/db-vercel-postgres`, and `@payloadcms/db-d1-sqlite` to their main entry points. Also handles re-export declarations and `declare module` augmentations.
+- `migrate-next-subpath-exports` — rewrites imports, re-exports, and string-literal component paths from the removed `@payloadcms/next/client`, `@payloadcms/next/rsc`, and `@payloadcms/next/templates` subpaths to their canonical `@payloadcms/ui` or `@payloadcms/ui/rsc` sources. After running, regenerate the import map with `payload generate:importmap`.
 - `rename-typescript-schema-to-json-schema` — renames the `typescriptSchema` field-config property to `jsonSchema` (it always accepted JSON Schema, not TypeScript). Skips any object that already defines a `jsonSchema` sibling and surfaces it as a note for manual review.
 
 ## Contributing

packages/codemod/src/registry.ts

@@ -10,6 +10,7 @@ import { migrateForceSelect } from './transforms/migrate-force-select/index.js'
 import { migrateHideAPIURL } from './transforms/migrate-hide-api-url/index.js'
 import { migrateImportExportHooks } from './transforms/migrate-import-export-hooks/index.js'
 import { migrateListViewSelectAPI } from './transforms/migrate-list-view-select-api/index.js'
+import { migrateNextSubpathExports } from './transforms/migrate-next-subpath-exports/index.js'
 import { migrateStorageAdaptersToConfig } from './transforms/migrate-storage-adapters-to-config/index.js'
 import { renameStorageAdaptersToStorage } from './transforms/rename-storage-adapters-to-storage/index.js'
 import { renameTypescriptSchemaToJsonSchema } from './transforms/rename-typescript-schema-to-json-schema/index.js'
@@ -27,5 +28,6 @@ export const transforms: Transform[] = [
   renameStorageAdaptersToStorage,
   migrateImportExportHooks,
   migrateDbTypesSubpath,
+  migrateNextSubpathExports,
   renameTypescriptSchemaToJsonSchema,
 ]

packages/codemod/src/transforms/migrate-next-subpath-exports/basic.input.ts

@@ -0,0 +1,28 @@
+import { DefaultTemplate, MinimalTemplate } from '@payloadcms/next/templates'
+import { CollectionCards, DefaultNav, DocumentHeader, Logo } from '@payloadcms/next/rsc'
+import { HierarchyTypeField, SlugField } from '@payloadcms/next/client'
+import type { CollectionConfig } from 'payload'
+
+export const widget = { Component: '@payloadcms/next/rsc#CollectionCards' }
+export const slug: CollectionConfig['fields'][number] = {
+  name: 'slug',
+  type: 'text',
+  admin: {
+    components: {
+      Field: {
+        path: '@payloadcms/next/client#SlugField',
+      },
+    },
+  },
+}
+
+export {
+  DefaultTemplate,
+  MinimalTemplate,
+  CollectionCards,
+  DefaultNav,
+  DocumentHeader,
+  Logo,
+  HierarchyTypeField,
+  SlugField,
+}

packages/codemod/src/transforms/migrate-next-subpath-exports/basic.output.ts

@@ -0,0 +1,28 @@
+import { DefaultTemplate, MinimalTemplate } from '@payloadcms/ui/rsc'
+import { CollectionCards, DefaultNav, DocumentHeader, Logo } from '@payloadcms/ui/rsc'
+import { HierarchyTypeField, SlugField } from '@payloadcms/ui'
+import type { CollectionConfig } from 'payload'
+
+export const widget = { Component: '@payloadcms/ui/rsc#CollectionCards' }
+export const slug: CollectionConfig['fields'][number] = {
+  name: 'slug',
+  type: 'text',
+  admin: {
+    components: {
+      Field: {
+        path: '@payloadcms/ui#SlugField',
+      },
+    },
+  },
+}
+
+export {
+  DefaultTemplate,
+  MinimalTemplate,
+  CollectionCards,
+  DefaultNav,
+  DocumentHeader,
+  Logo,
+  HierarchyTypeField,
+  SlugField,
+}

packages/codemod/src/transforms/migrate-next-subpath-exports/index.test.ts

@@ -0,0 +1,46 @@
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+import { runTransform } from '../../utils/test-helpers.js'
+import { migrateNextSubpathExports } from './index.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const fixture = (name: string) => readFile(join(here, name), 'utf8')
+
+describe('migrate-next-subpath-exports', () => {
+  it('rewrites import declarations and string component paths', async () => {
+    const input = await fixture('basic.input.ts')
+    const output = await fixture('basic.output.ts')
+
+    const result = await runTransform({ source: input, transform: migrateNextSubpathExports })
+
+    expect(result).toBe(output)
+  })
+
+  it('rewrites re-export declarations from the removed subpaths', async () => {
+    const input = await fixture('re-export.input.ts')
+    const output = await fixture('re-export.output.ts')
+
+    const result = await runTransform({ source: input, transform: migrateNextSubpathExports })
+
+    expect(result).toBe(output)
+  })
+
+  it('is idempotent on already-migrated source', async () => {
+    const output = await fixture('basic.output.ts')
+
+    const result = await runTransform({ source: output, transform: migrateNextSubpathExports })
+
+    expect(result).toBe(output)
+  })
+
+  it('leaves unrelated imports and plain prose strings untouched', async () => {
+    const input = await fixture('non-matching.input.ts')
+
+    const result = await runTransform({ source: input, transform: migrateNextSubpathExports })
+
+    expect(result).toBe(input)
+  })
+})

packages/codemod/src/transforms/migrate-next-subpath-exports/index.ts

@@ -0,0 +1,102 @@
+import { Node, SyntaxKind } from 'ts-morph'
+
+import type { Transform } from '../../types.js'
+
+/**
+ * Maps the removed `@payloadcms/next` subpaths to their new `@payloadcms/ui`
+ * targets. All admin elements and templates were relocated to `@payloadcms/ui`
+ * in v4; the `./client`, `./rsc`, and `./templates` subpaths on
+ * `@payloadcms/next` have been removed.
+ */
+const SUBPATH_TO_TARGET: Record<string, string> = {
+  '@payloadcms/next/client': '@payloadcms/ui',
+  '@payloadcms/next/rsc': '@payloadcms/ui/rsc',
+  '@payloadcms/next/templates': '@payloadcms/ui/rsc',
+}
+
+// `<package>` or `<package>#<exportName>` — the export identifier follows
+// JavaScript identifier rules so we reject anything with whitespace or
+// punctuation that would indicate it's actually prose containing the path.
+const COMPONENT_PATH_PATTERN = /^@payloadcms\/next\/(client|rsc|templates)(#[A-Za-z_$][\w$]*)?$/
+
+function mapComponentPath(value: string): string | undefined {
+  const match = COMPONENT_PATH_PATTERN.exec(value)
+  if (!match) {
+    return undefined
+  }
+  const subpath = `@payloadcms/next/${match[1]}`
+  const target = SUBPATH_TO_TARGET[subpath]
+  if (!target) {
+    return undefined
+  }
+  return match[2] ? `${target}${match[2]}` : target
+}
+
+export const migrateNextSubpathExports: Transform = {
+  name: 'migrate-next-subpath-exports',
+  apply: ({ project }) => {
+    const filesChanged = new Set<string>()
+
+    for (const file of project.getSourceFiles()) {
+      let mutated = false
+
+      for (const importDecl of file.getImportDeclarations()) {
+        const target = SUBPATH_TO_TARGET[importDecl.getModuleSpecifierValue()]
+        if (target) {
+          importDecl.setModuleSpecifier(target)
+          mutated = true
+        }
+      }
+
+      for (const exportDecl of file.getExportDeclarations()) {
+        const specifier = exportDecl.getModuleSpecifierValue()
+        if (specifier) {
+          const target = SUBPATH_TO_TARGET[specifier]
+          if (target) {
+            exportDecl.setModuleSpecifier(target)
+            mutated = true
+          }
+        }
+      }
+
+      // Rewrite string-literal component paths used in Payload config
+      // (e.g. `Component: '@payloadcms/next/rsc#CollectionCards'`) and
+      // import-map keys.
+      for (const stringLit of file.getDescendantsOfKind(SyntaxKind.StringLiteral)) {
+        if (isImportOrExportSpecifier(stringLit)) {
+          continue
+        }
+        const value = stringLit.getLiteralValue()
+        const replacement = mapComponentPath(value)
+        if (replacement && replacement !== value) {
+          stringLit.setLiteralValue(replacement)
+          mutated = true
+        }
+      }
+
+      if (mutated) {
+        filesChanged.add(file.getFilePath())
+      }
+    }
+
+    return { filesChanged: [...filesChanged] }
+  },
+  description:
+    'Rewrites imports, re-exports, and string-literal component paths from the removed `@payloadcms/next/client`, `@payloadcms/next/rsc`, and `@payloadcms/next/templates` subpaths to their canonical `@payloadcms/ui` or `@payloadcms/ui/rsc` sources. After running, regenerate the import map with `payload generate:importmap`.',
+}
+
+/**
+ * Skip string literals that form the module specifier of an import/export
+ * declaration — those are already handled by the dedicated traversals above
+ * and rewriting them through `setLiteralValue` would double-process.
+ */
+function isImportOrExportSpecifier(node: Node): boolean {
+  const parent = node.getParent()
+  if (!parent) {
+    return false
+  }
+  if (Node.isImportDeclaration(parent) || Node.isExportDeclaration(parent)) {
+    return parent.getModuleSpecifier() === node
+  }
+  return false
+}