refactor: add relative flag to formatAdminURL util (#14925)

Adds a `relative` flag to the `formatAdminURL` util.

There are cases where this function can produce a fully qualified URL,
like for client-side routing, and other times when it must remain
relative, like when matching routes.

This flag differentiates these two behaviors declaratively so we don't
have to rely on the omission of `serverURL`.

```ts
const result = formatAdminURL({
  adminRoute: '/admin',
  basePath: '/v1',
  path: '/collections/posts',
  serverURL: 'http://payloadcms.com',
  relative: true,
})

// returns '/v1/admin/collections/posts'
```

Related: #14919 and
#14907

Author: jacobsfletch

packages/next/src/views/Root/getRouteData.ts

@@ -160,7 +160,12 @@ export const getRouteData = ({
           return isPathMatchingRoute({
             currentRoute,
             exact: true,
-            path: formatAdminURL({ adminRoute, path: route }),
+            path: formatAdminURL({
+              adminRoute,
+              path: route,
+              relative: true,
+              serverURL: config.serverURL,
+            }),
           })
         })
 

packages/next/src/views/Root/index.tsx

@@ -67,6 +67,8 @@ export const RootPage = async ({
   const currentRoute = formatAdminURL({
     adminRoute,
     path: Array.isArray(params.segments) ? `/${params.segments.join('/')}` : null,
+    relative: true,
+    serverURL: config.serverURL,
   })
 
   const segments = Array.isArray(params.segments) ? params.segments : []
@@ -224,7 +226,12 @@ export const RootPage = async ({
   const usersCollection = config.collections.find(({ slug }) => slug === userSlug)
   const disableLocalStrategy = usersCollection?.auth?.disableLocalStrategy
 
-  const createFirstUserRoute = formatAdminURL({ adminRoute, path: _createFirstUserRoute })
+  const createFirstUserRoute = formatAdminURL({
+    adminRoute,
+    path: _createFirstUserRoute,
+    relative: true,
+    serverURL: config.serverURL,
+  })
 
   if (disableLocalStrategy && currentRoute === createFirstUserRoute) {
     redirect(adminRoute)

packages/payload/src/utilities/formatAdminURL.spec.ts

@@ -0,0 +1,206 @@
+import { formatAdminURL } from './formatAdminURL.js'
+
+describe('formatAdminURL', () => {
+  const serverURL = 'https://example.com'
+
+  const defaultAdminRoute = '/admin'
+  const rootAdminRoute = '/'
+
+  const dummyPath = '/collections/posts'
+
+  describe('relative URLs', () => {
+    it('should ignore `serverURL` when relative=true', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: dummyPath,
+        serverURL,
+        relative: true,
+      })
+
+      expect(result).toBe(`${defaultAdminRoute}${dummyPath}`)
+    })
+
+    it('should force relative URL when `serverURL` is omitted', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: dummyPath,
+        relative: false,
+      })
+
+      expect(result).toBe(`${defaultAdminRoute}${dummyPath}`)
+    })
+  })
+
+  describe('absolute URLs', () => {
+    it('should return absolute URL with serverURL', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: dummyPath,
+        serverURL,
+      })
+
+      expect(result).toBe(`${serverURL}${defaultAdminRoute}${dummyPath}`)
+    })
+
+    it('should handle serverURL with trailing slash', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: '/collections/posts',
+        serverURL: 'https://example.com/',
+      })
+
+      expect(result).toBe('https://example.com/admin/collections/posts')
+    })
+
+    it('should handle serverURL with subdirectory', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: '/collections/posts',
+        serverURL: 'https://example.com/api/v1',
+      })
+
+      expect(result).toBe('https://example.com/admin/collections/posts')
+    })
+  })
+
+  describe('admin route handling', () => {
+    it('should return relative URL for adminRoute="/", no path, no `serverURL`', () => {
+      const result = formatAdminURL({
+        adminRoute: rootAdminRoute,
+        relative: true,
+      })
+
+      expect(result).toBe('/')
+    })
+
+    it('should handle relative URL for adminRoute="/", with path, no `serverURL`', () => {
+      const result = formatAdminURL({
+        adminRoute: rootAdminRoute,
+        path: dummyPath,
+        relative: true,
+      })
+
+      expect(result).toBe(dummyPath)
+    })
+
+    it('should return absolute URL for adminRoute="/", no path, with `serverURL`', () => {
+      const result = formatAdminURL({
+        adminRoute: rootAdminRoute,
+        serverURL,
+      })
+
+      expect(result).toBe('https://example.com/')
+    })
+
+    it('should handle absolute URL for adminRoute="/", with path and `serverURL`', () => {
+      const result = formatAdminURL({
+        adminRoute: rootAdminRoute,
+        serverURL,
+        path: dummyPath,
+      })
+
+      expect(result).toBe(`${serverURL}${dummyPath}`)
+    })
+  })
+
+  describe('base path handling', () => {
+    it('should include basePath in URL', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        basePath: '/v1',
+        path: dummyPath,
+        serverURL,
+      })
+
+      expect(result).toBe(`${serverURL}/v1${defaultAdminRoute}${dummyPath}`)
+    })
+
+    it('should handle basePath with adminRoute="/"', () => {
+      const result = formatAdminURL({
+        adminRoute: rootAdminRoute,
+        basePath: '/v1',
+        serverURL,
+      })
+
+      expect(result).toBe(`${serverURL}/v1`)
+    })
+
+    it('should handle basePath with no adminRoute', () => {
+      const result = formatAdminURL({
+        adminRoute: undefined,
+        basePath: '/v1',
+        path: dummyPath,
+        serverURL,
+      })
+
+      expect(result).toBe(`${serverURL}/v1${dummyPath}`)
+    })
+
+    it('should handle empty basePath', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        basePath: '',
+        path: dummyPath,
+        serverURL,
+      })
+
+      expect(result).toBe(`${serverURL}${defaultAdminRoute}${dummyPath}`)
+    })
+  })
+
+  describe('path handling', () => {
+    it('should handle empty string path', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: '',
+        serverURL,
+      })
+
+      expect(result).toBe(`${serverURL}${defaultAdminRoute}`)
+    })
+
+    it('should handle null path', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: null,
+        serverURL,
+      })
+      expect(result).toBe(`${serverURL}${defaultAdminRoute}`)
+    })
+
+    it('should handle undefined path', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: undefined,
+        serverURL,
+      })
+
+      expect(result).toBe(`${serverURL}${defaultAdminRoute}`)
+    })
+
+    it('should handle path with query parameters', () => {
+      const path = `${dummyPath}?page=2`
+
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path,
+        serverURL,
+      })
+
+      expect(result).toBe(`${serverURL}${defaultAdminRoute}${path}`)
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should return "/" when given minimal args', () => {
+      const result = formatAdminURL({
+        adminRoute: undefined,
+        basePath: '',
+        path: '',
+        relative: true,
+      })
+
+      expect(result).toBe('/')
+    })
+  })
+})

packages/payload/src/utilities/formatAdminURL.ts

@@ -1,24 +1,46 @@
 import type { Config } from '../config/types.js'
 
-/** Will read the `routes.admin` config and appropriately handle `"/"` admin paths */
-export const formatAdminURL = (args: {
-  adminRoute: NonNullable<Config['routes']>['admin']
-  basePath?: string
-  path: '' | `/${string}` | null | undefined
-  serverURL?: Config['serverURL']
-}): string => {
-  const { adminRoute, basePath = '', path: pathFromArgs, serverURL } = args
-  const path = pathFromArgs || ''
+/**
+ * This function builds correct URLs for admin panel routing.
+ * Its primary responsibilities are:
+ * 1. Read from your `routes.admin` config and appropriately handle `"/"` admin paths
+ * 2. Prepend the `basePath` from your Next.js config, if specified
+ * 3. Return relative or absolute URLs, as needed
+ */
+export const formatAdminURL = (
+  args: {
+    adminRoute: NonNullable<Config['routes']>['admin']
+    /**
+     * The subpath of your application, if specified.
+     * @see https://nextjs.org/docs/app/api-reference/config/next-config-js/basePath
+     * @example '/docs'
+     */
+    basePath?: string
+    path?: '' | `/${string}` | null
+    /**
+     * Return a relative URL, e.g. ignore `serverURL`.
+     * Useful for route-matching, etc.
+     */
+    relative?: boolean
+  } & Pick<Config, 'serverURL'>,
+): string => {
+  const { adminRoute, basePath = '', path = '', relative = false, serverURL } = args
 
-  if (adminRoute) {
-    if (adminRoute === '/') {
-      if (!path) {
-        return `${serverURL || ''}${basePath}${adminRoute}`
-      }
-    } else {
-      return `${serverURL || ''}${basePath}${adminRoute}${path}`
-    }
+  const pathSegments = [basePath]
+
+  if (adminRoute && adminRoute !== '/') {
+    pathSegments.push(adminRoute)
+  }
+
+  if (path && !(adminRoute === '/' && !path)) {
+    pathSegments.push(path)
+  }
+
+  const pathname = pathSegments.join('') || '/'
+
+  if (relative || !serverURL) {
+    return pathname
   }
 
-  return `${serverURL || ''}${basePath}${path}`
+  return new URL(pathname, serverURL).toString()
 }