feat(next): root admin (#7276)

Author: jacobsfletch

.github/workflows/main.yml

@@ -292,6 +292,7 @@ jobs:
           - access-control
           - admin__e2e__1
           - admin__e2e__2
+          - admin-root
           - auth
           - field-error-states
           - fields-relationship

docs/admin/overview.mdx

@@ -169,19 +169,32 @@ The following options are available:
 
 | Option             | Default route           | Description                           |
 | ------------------ | ----------------------- | ------------------------------------- |
-| `admin`            | `/admin`                | The Admin Panel itself.               |
+| `admin`            | `/admin`                | The Admin Panel itself. |
 | `api`              | `/api`                  | The [REST API](../rest-api/overview) base path.               |
 | `graphQL`          | `/graphql`              | The [GraphQL API](../graphql/overview) base path.            |
 | `graphQLPlayground`| `/graphql-playground`   | The GraphQL Playground.               |
 
-<Banner type="warning">
-  <strong>Warning:</strong>
-  Changing Root-level Routes _after_ your project was generated will also require you to manually update the corresponding directories in your project. For example, changing `routes.admin` will require you to rename the `(payload)/admin` directory in your project to match the new route. [More details](#project-structure).
-</Banner>
-
 <Banner type="success">
   <strong>Tip:</strong>
-   You can easily add _new_ routes to the Admin Panel through the `endpoints` property of the Payload Config. See [Custom Endpoints](../rest-api/overview#custom-endpoints) for more information.
+   You can easily add _new_ routes to the Admin Panel through [Custom Endpoints](../rest-api/overview#custom-endpoints) and [Custom Views](./views).
+</Banner>
+
+#### Customizing Root-level Routes
+
+You can change the Root-level Routes as needed, such as to mount the Admin Panel at the root of your application.
+
+Changing Root-level Routes also requires a change to [Project Structure](#project-structure) to match the new route. For example, if you set `routes.admin` to `/`, you would need to completely remove the `admin` directory from the project structure:
+
+```plaintext
+app/
+├─ (payload)/
+├── [[...segments]]/
+├──── ...
+```
+
+<Banner type="warning">
+  <strong>Note:</strong>
+  If you set Root-level Routes _before_ auto-generating the Admin Panel, your [Project Structure](#project-structure) will already be set up correctly.
 </Banner>
 
 ### Admin-level Routes

docs/fields/checkbox.mdx

@@ -6,7 +6,7 @@ desc: Checkbox field types allow the developer to save a boolean value in the da
 keywords: checkbox, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
 ---
 
-The Checkbox Field type saves a boolean in the database.
+The Checkbox Field saves a boolean in the database.
 
 <LightDarkImage
   srcLight="https://payloadcms.com/images/docs/fields/checkbox.png"

docs/fields/collapsible.mdx

@@ -6,7 +6,7 @@ desc: With the Collapsible field, you can place fields within a collapsible layo
 keywords: row, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
 ---
 
-The Collapsible field is presentational-only and only affects the Admin Panel. By using it, you can place fields within a nice layout component that can be collapsed / expanded.
+The Collapsible Field is presentational-only and only affects the Admin Panel. By using it, you can place fields within a nice layout component that can be collapsed / expanded.
 
 <LightDarkImage
   srcLight="https://payloadcms.com/images/docs/fields/collapsible.png"

docs/fields/relationship.mdx

@@ -6,7 +6,7 @@ desc: The Relationship field provides the ability to relate documents together.
 keywords: relationship, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
 ---
 
-The Relationship field is one of the most powerful fields Payload features. It provides for the ability to easily relate documents together.
+The Relationship Field is one of the most powerful fields Payload features. It provides for the ability to easily relate documents together.
 
 <LightDarkImage
   srcLight="https://payloadcms.com/images/docs/fields/relationship.png"

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

@@ -2,6 +2,7 @@
 import type { SanitizedConfig } from 'payload'
 
 import { useSearchParams } from '@payloadcms/ui'
+import { formatAdminURL } from '@payloadcms/ui/shared'
 import LinkImport from 'next/link.js'
 import { useParams, usePathname } from 'next/navigation.js'
 import React from 'react'
@@ -38,7 +39,12 @@ export const DocumentTabLink: React.FC<{
 
   const [entityType, entitySlug, segmentThree, segmentFour, ...rest] = params.segments || []
   const isCollection = entityType === 'collections'
-  let docPath = `${adminRoute}/${isCollection ? 'collections' : 'globals'}/${entitySlug}`
+
+  let docPath = formatAdminURL({
+    adminRoute,
+    path: `/${isCollection ? 'collections' : 'globals'}/${entitySlug}`,
+  })
+
   if (isCollection && segmentThree) {
     // doc ID
     docPath += `/${segmentThree}`

packages/next/src/elements/Nav/index.client.tsx

@@ -12,7 +12,7 @@ import {
   useNav,
   useTranslation,
 } from '@payloadcms/ui'
-import { EntityType, groupNavItems } from '@payloadcms/ui/shared'
+import { EntityType, formatAdminURL, groupNavItems } from '@payloadcms/ui/shared'
 import LinkWithDefault from 'next/link.js'
 import React, { Fragment } from 'react'
 
@@ -25,7 +25,7 @@ export const DefaultNavClient: React.FC = () => {
   const {
     collections,
     globals,
-    routes: { admin },
+    routes: { admin: adminRoute },
   } = useConfig()
 
   const { i18n } = useTranslation()
@@ -69,13 +69,13 @@ export const DefaultNavClient: React.FC = () => {
               let id: string
 
               if (type === EntityType.collection) {
-                href = `${admin}/collections/${entity.slug}`
+                href = formatAdminURL({ adminRoute, path: `/collections/${entity.slug}` })
                 entityLabel = getTranslation(entity.labels.plural, i18n)
                 id = `nav-${entity.slug}`
               }
 
               if (type === EntityType.global) {
-                href = `${admin}/globals/${entity.slug}`
+                href = formatAdminURL({ adminRoute, path: `/globals/${entity.slug}` })
                 entityLabel = getTranslation(entity.label, i18n)
                 id = `nav-global-${entity.slug}`
               }

packages/next/src/utilities/initPage/handleAdminPage.ts

@@ -21,7 +21,8 @@ export const handleAdminPage = ({
   route: string
 }) => {
   if (isAdminRoute(route, adminRoute)) {
-    const routeSegments = route.replace(adminRoute, '').split('/').filter(Boolean)
+    const baseAdminRoute = adminRoute && adminRoute !== '/' ? route.replace(adminRoute, '') : route
+    const routeSegments = baseAdminRoute.split('/').filter(Boolean)
     const [entityType, entitySlug, createOrID] = routeSegments
     const collectionSlug = entityType === 'collections' ? entitySlug : undefined
     const globalSlug = entityType === 'globals' ? entitySlug : undefined
@@ -56,4 +57,6 @@ export const handleAdminPage = ({
       globalConfig,
     }
   }
+
+  return {}
 }

packages/next/src/utilities/initPage/handleAuthRedirect.ts

@@ -1,3 +1,4 @@
+import { formatAdminURL } from '@payloadcms/ui/shared'
 import { redirect } from 'next/navigation.js'
 import * as qs from 'qs-esm'
 
@@ -30,7 +31,7 @@ export const handleAuthRedirect = ({
         : undefined,
     )
 
-    const adminLoginRoute = `${adminRoute}${loginRouteFromConfig}`
+    const adminLoginRoute = formatAdminURL({ adminRoute, path: loginRouteFromConfig })
 
     const customLoginRoute =
       typeof redirectUnauthenticatedUser === 'string' ? redirectUnauthenticatedUser : undefined

packages/next/src/views/Dashboard/Default/index.tsx

@@ -3,7 +3,7 @@ import type { Permissions, ServerProps, VisibleEntities } from 'payload'
 
 import { getTranslation } from '@payloadcms/translations'
 import { Button, Card, Gutter, SetStepNav, SetViewActions } from '@payloadcms/ui'
-import { EntityType, WithServerSideProps } from '@payloadcms/ui/shared'
+import { EntityType, WithServerSideProps, formatAdminURL } from '@payloadcms/ui/shared'
 import React, { Fragment } from 'react'
 
 import './index.scss'
@@ -100,19 +100,31 @@ export const DefaultDashboard: React.FC<DashboardProps> = (props) => {
 
                       if (type === EntityType.collection) {
                         title = getTranslation(entity.labels.plural, i18n)
+
                         buttonAriaLabel = t('general:showAllLabel', { label: title })
-                        href = `${adminRoute}/collections/${entity.slug}`
-                        createHREF = `${adminRoute}/collections/${entity.slug}/create`
+
+                        href = formatAdminURL({ adminRoute, path: `/collections/${entity.slug}` })
+
+                        createHREF = formatAdminURL({
+                          adminRoute,
+                          path: `/collections/${entity.slug}/create`,
+                        })
+
                         hasCreatePermission =
                           permissions?.collections?.[entity.slug]?.create?.permission
                       }
 
                       if (type === EntityType.global) {
                         title = getTranslation(entity.label, i18n)
+
                         buttonAriaLabel = t('general:editLabel', {
                           label: getTranslation(entity.label, i18n),
                         })
-                        href = `${adminRoute}/globals/${entity.slug}`
+
+                        href = formatAdminURL({
+                          adminRoute,
+                          path: `/globals/${entity.slug}`,
+                        })
                       }
 
                       return (