fix: basePath not working properly with admin routes (#14967)

This PR adds a base-path test suite, updates the formatAdminURL helper
function.

The helper function allows you to create routes inside the admin panel
that take `basePath` into account when set.

There are a lot of touched files here, most have the same treatment.

## API URL construction changes
Previously we were appending the basePath in the default api
configuration. That is no longer the case and is more predictable to use
the helper function that will generate a correct path/url.

## Admin URL construction changes
The default admin route differed from the default api route, the default
admin route did not prepend the basePath. The reason it did not/should
not, is because `usePathname` from NextJS excludes basePath.

So if we were to prepend it to `routes.admin` and then for example use
`pathname.startsWith(config.routes.admin)` it would always return false
when using a basePath, since `/route` will never start with
`/basePath/route`.

Also, when you do something like `router.push(/adminRoute)` NextJS will
prepend the basePath and push you to `/basePath/adminRoute`. If we
prepended it in the config it would push you to
`/basePath/basePath/adminRoute`.


## Helper function usage

The helper is especially useful for plugin work, this way your plugin
will generate correct urls for users using basePath.

Before we were doing:
```ts
// worked because we prepended basePath to apiRoute
const apiURL = `${serverURL}${apiRoute}/collections/${slug}/${id}`

// never worked since basePath was never prepended to adminRoute
const adminURL = `${serverURL}${adminRoute}/collections/${slug}/${id}`
```

Now we can do:
```ts
import { formatAdminURL } from 'payload/shared'

// Admin url example
const adminURL = formatAdminURL({
  adminRoute: config.routes.admin,
  path: `/collections/${slug}/${id}`,
})

// API url example
const apiURL = formatAdminURL({
  apiRoute: config.routes.api,
  path: `/collections/${slug}/${id}`,
  // serverURL, when supplied returns a full url
})
```

If you pass `serverURL` the result will be a full URL. If excluded the
result will be a relative path.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: JarrodMFlesch

.github/workflows/post-release-templates.yml

@@ -62,7 +62,7 @@ jobs:
       - name: Start PostgreSQL
         uses: CasperWA/postgresql-action@v1.2
         with:
-          postgresql version: "14" # See https://hub.docker.com/_/postgres for available versions
+          postgresql version: '14' # See https://hub.docker.com/_/postgres for available versions
           postgresql db: ${{ env.POSTGRES_DB }}
           postgresql user: ${{ env.POSTGRES_USER }}
           postgresql password: ${{ env.POSTGRES_PASSWORD }}
@@ -108,13 +108,13 @@ jobs:
         uses: peter-evans/create-pull-request@v7
         with:
           token: ${{ secrets.GH_TOKEN_POST_RELEASE_TEMPLATES }}
-          labels: "area: templates"
+          labels: 'area: templates'
           author: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
-          commit-message: "templates: bump templates for ${{ needs.wait_for_release.outputs.release_tag }}"
+          commit-message: 'templates: bump templates for ${{ needs.wait_for_release.outputs.release_tag }}'
           branch: ${{ steps.commit.outputs.branch }}
           base: main
           assignees: ${{ github.actor }}
-          title: "templates: bump for ${{ needs.wait_for_release.outputs.release_tag }}"
+          title: 'templates: bump for ${{ needs.wait_for_release.outputs.release_tag }}'
           body: |
             🤖 Automated bump of templates for ${{ needs.wait_for_release.outputs.release_tag }}
 

docs/fields/rich-text.mdx

@@ -17,7 +17,6 @@ Instead, you can invest your time and effort into learning the underlying open-s
   caption="Admin Panel screenshot of a Rich Text field"
 />
 
-
 ## Config Options
 
 | Option                 | Description                                                                                                                                                                                                                                                                                             |

examples/astro/payload/docker-compose.yml

@@ -1,10 +1,10 @@
-version: "3"
+version: '3'
 
 services:
   payload:
     image: node:18-alpine
     ports:
-      - "3000:3000"
+      - '3000:3000'
     volumes:
       - .:/home/node/app
       - node_modules:/home/node/app/node_modules
@@ -20,7 +20,7 @@ services:
   mongo:
     image: mongo:latest
     ports:
-      - "27017:27017"
+      - '27017:27017'
     command:
       - --storageEngine=wiredTiger
     volumes:

examples/remix/payload/docker-compose.yml

@@ -1,10 +1,10 @@
-version: "3"
+version: '3'
 
 services:
   payload:
     image: node:18-alpine
     ports:
-      - "3000:3000"
+      - '3000:3000'
     volumes:
       - .:/home/node/app
       - node_modules:/home/node/app/node_modules
@@ -20,7 +20,7 @@ services:
   mongo:
     image: mongo:latest
     ports:
-      - "27017:27017"
+      - '27017:27017'
     command:
       - --storageEngine=wiredTiger
     volumes:

next.config.mjs

@@ -14,6 +14,7 @@ const withBundleAnalyzer = bundleAnalyzer({
 const config = withBundleAnalyzer(
   withPayload(
     {
+      basePath: process.env?.NEXT_BASE_PATH || undefined,
       eslint: {
         ignoreDuringBuilds: true,
       },

package.json

@@ -106,7 +106,7 @@
     "obliterate-playwright-cache-macos": "rm -rf ~/Library/Caches/ms-playwright && find /System/Volumes/Data/private/var/folders -type d -name 'playwright*' -exec rm -rf {} +",
     "prepare": "husky",
     "prepare-run-test-against-prod": "pnpm bf && rm -rf test/packed && rm -rf test/node_modules && rm -rf app && rm -f test/pnpm-lock.yaml && pnpm run script:pack --all --no-build --dest test/packed && pnpm runts test/setupProd.ts && cd test && pnpm i --ignore-workspace && cd ..",
-    "prepare-run-test-against-prod:ci": "rm -rf test/node_modules && rm -rf app && rm -f test/pnpm-lock.yaml && pnpm run script:pack --all --no-build --dest test/packed && pnpm runts test/setupProd.ts && cd test && pnpm i --ignore-workspace && cd ..",
+    "prepare-run-test-against-prod:ci": "rm -rf test/packed && rm -rf test/node_modules && rm -rf app && rm -f test/pnpm-lock.yaml && pnpm run script:pack --all --no-build --dest test/packed && pnpm runts test/setupProd.ts && cd test && pnpm i --ignore-workspace && cd ..",
     "publish-prerelease": "pnpm --filter releaser publish-prerelease",
     "reinstall": "pnpm clean:all && pnpm install",
     "release": "pnpm --filter releaser release --tag latest",

packages/live-preview/src/mergeData.ts

@@ -1,12 +1,12 @@
+import { formatAdminURL } from 'payload/shared'
+
 import type { CollectionPopulationRequestHandler } from './types.js'
 
-const defaultRequestHandler: CollectionPopulationRequestHandler = ({
-  apiPath,
-  data,
-  endpoint,
-  serverURL,
-}) => {
-  const url = `${serverURL}${apiPath}/${endpoint}`
+const defaultRequestHandler: CollectionPopulationRequestHandler = ({ apiPath, data, endpoint }) => {
+  const url = formatAdminURL({
+    apiRoute: apiPath,
+    path: `/${endpoint}`,
+  })
 
   return fetch(url, {
     body: JSON.stringify(data),

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

@@ -1,7 +1,7 @@
 'use client'
 import type { SanitizedConfig } from 'payload'
 
-import { Button, useConfig } from '@payloadcms/ui'
+import { Button } from '@payloadcms/ui'
 import { useParams, usePathname, useSearchParams } from 'next/navigation.js'
 import { formatAdminURL } from 'payload/shared'
 import React from 'react'
@@ -25,7 +25,6 @@ export const DocumentTabLink: React.FC<{
 }) => {
   const pathname = usePathname()
   const params = useParams()
-  const { config } = useConfig()
 
   const searchParams = useSearchParams()
 
@@ -37,7 +36,6 @@ export const DocumentTabLink: React.FC<{
   let docPath = formatAdminURL({
     adminRoute,
     path: `/${isCollection ? 'collections' : 'globals'}/${entitySlug}`,
-    serverURL: config.serverURL,
   })
 
   if (isCollection) {

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

@@ -28,7 +28,6 @@ export const DefaultNavClient: React.FC<{
       },
       folders,
       routes: { admin: adminRoute },
-      serverURL,
     },
   } = useConfig()
 
@@ -37,7 +36,6 @@ export const DefaultNavClient: React.FC<{
   const folderURL = formatAdminURL({
     adminRoute,
     path: foldersRoute,
-    serverURL,
   })
 
   const viewingRootFolderView = pathname.startsWith(folderURL)
@@ -53,12 +51,12 @@ export const DefaultNavClient: React.FC<{
               let id: string
 
               if (type === EntityType.collection) {
-                href = formatAdminURL({ adminRoute, path: `/collections/${slug}`, serverURL })
+                href = formatAdminURL({ adminRoute, path: `/collections/${slug}` })
                 id = `nav-${slug}`
               }
 
               if (type === EntityType.global) {
-                href = formatAdminURL({ adminRoute, path: `/globals/${slug}`, serverURL })
+                href = formatAdminURL({ adminRoute, path: `/globals/${slug}` })
                 id = `nav-global-${slug}`
               }
 

packages/next/src/routes/graphql/playground.ts

@@ -1,5 +1,6 @@
 import { renderPlaygroundPage } from 'graphql-playground-html'
 import { createPayloadRequest, type SanitizedConfig } from 'payload'
+import { formatAdminURL } from 'payload/shared'
 
 export const GET = (config: Promise<SanitizedConfig>) => async (request: Request) => {
   const req = await createPayloadRequest({
@@ -13,9 +14,13 @@ export const GET = (config: Promise<SanitizedConfig>) => async (request: Request
       process.env.NODE_ENV === 'production') ||
     process.env.NODE_ENV !== 'production'
   ) {
+    const endpoint = formatAdminURL({
+      apiRoute: req.payload.config.routes.api,
+      path: req.payload.config.routes.graphQL as `/${string}`,
+    })
     return new Response(
       renderPlaygroundPage({
-        endpoint: `${req.payload.config.routes.api}${req.payload.config.routes.graphQL}`,
+        endpoint,
         settings: {
           'request.credentials': 'include',
         },