fix(next): support next.config trailingSlash without /api redirect loop

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

@@ -63,10 +63,14 @@ export const RootPage = async ({
 
   const params = await paramsPromise
 
-  const currentRoute = formatAdminURL({
+  const rawCurrentRoute = formatAdminURL({
     adminRoute,
     path: Array.isArray(params.segments) ? `/${params.segments.join('/')}` : null,
   })
+  const currentRoute =
+    rawCurrentRoute.length > 1 && rawCurrentRoute.endsWith('/')
+      ? rawCurrentRoute.slice(0, -1)
+      : rawCurrentRoute
 
   const segments = Array.isArray(params.segments) ? params.segments : []
   const isCollectionRoute = segments[0] === 'collections'
@@ -223,10 +227,14 @@ export const RootPage = async ({
   const usersCollection = config.collections.find(({ slug }) => slug === userSlug)
   const disableLocalStrategy = usersCollection?.auth?.disableLocalStrategy
 
-  const createFirstUserRoute = formatAdminURL({
+  const rawCreateFirstUserRoute = formatAdminURL({
     adminRoute,
     path: _createFirstUserRoute,
   })
+  const createFirstUserRoute =
+    rawCreateFirstUserRoute.length > 1 && rawCreateFirstUserRoute.endsWith('/')
+      ? rawCreateFirstUserRoute.slice(0, -1)
+      : rawCreateFirstUserRoute
 
   if (disableLocalStrategy && currentRoute === createFirstUserRoute) {
     redirect(adminRoute)

packages/next/src/withPayload/withPayload.js

@@ -270,6 +270,11 @@ export const withPayload = (nextConfig = {}, options = {}) => {
     baseConfig.env.NEXT_BASE_PATH = nextConfig.basePath
   }
 
+  if (nextConfig.trailingSlash === true) {
+    process.env.NEXT_TRAILING_SLASH = 'true'
+    baseConfig.env.NEXT_TRAILING_SLASH = 'true'
+  }
+
   if (!supportsTurbopackBuild) {
     return withPayloadLegacy(baseConfig)
   } else {

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

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest'
+import { afterEach, beforeEach, describe, it, expect } from 'vitest'
 import { formatAdminURL } from './formatAdminURL.js'
 
 describe('formatAdminURL', () => {
@@ -214,4 +214,119 @@ describe('formatAdminURL', () => {
       expect(result).toBe('/')
     })
   })
+
+  describe('trailing slash handling', () => {
+    const originalTrailingSlash = process.env.NEXT_TRAILING_SLASH
+
+    beforeEach(() => {
+      process.env.NEXT_TRAILING_SLASH = 'true'
+    })
+
+    afterEach(() => {
+      if (originalTrailingSlash === undefined) {
+        delete process.env.NEXT_TRAILING_SLASH
+      } else {
+        process.env.NEXT_TRAILING_SLASH = originalTrailingSlash
+      }
+    })
+
+    it('should append trailing slash to relative admin URL', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: dummyPath,
+        relative: true,
+      })
+
+      expect(result).toBe(`${defaultAdminRoute}${dummyPath}/`)
+    })
+
+    it('should append trailing slash to relative api URL', () => {
+      const result = formatAdminURL({
+        apiRoute: '/api',
+        path: '/users',
+        relative: true,
+      })
+
+      expect(result).toBe(`${process.env.NEXT_BASE_PATH || ''}/api/users/`)
+    })
+
+    it('should append trailing slash to absolute URL', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: dummyPath,
+        serverURL,
+      })
+
+      expect(result).toBe(
+        `${serverURL}${process.env.NEXT_BASE_PATH || ''}${defaultAdminRoute}${dummyPath}/`,
+      )
+    })
+
+    it('should append trailing slash when basePath is set', () => {
+      const result = formatAdminURL({
+        apiRoute: '/api',
+        basePath: '/v1',
+        path: '/users',
+        serverURL,
+      })
+
+      expect(result).toBe(`${serverURL}${process.env.NEXT_BASE_PATH || ''}/v1/api/users/`)
+    })
+
+    it('should not append trailing slash to root "/"', () => {
+      const result = formatAdminURL({
+        adminRoute: rootAdminRoute,
+        relative: true,
+      })
+
+      expect(result).toBe('/')
+    })
+
+    it('should not double-slash when path already ends with /', () => {
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: '/collections/posts',
+        relative: true,
+      })
+
+      expect(result.endsWith('//')).toBe(false)
+      expect(result).toBe(`${defaultAdminRoute}/collections/posts/`)
+    })
+
+    it('should place trailing slash before query string', () => {
+      const path = `${dummyPath}?page=2`
+
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path,
+        relative: true,
+      })
+
+      expect(result).toBe(`${defaultAdminRoute}${dummyPath}/?page=2`)
+    })
+
+    it('should leave URLs unchanged when env var is not set', () => {
+      delete process.env.NEXT_TRAILING_SLASH
+
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: dummyPath,
+        relative: true,
+      })
+
+      expect(result).toBe(`${defaultAdminRoute}${dummyPath}`)
+    })
+
+    it('should leave URLs unchanged when env var is "false"', () => {
+      process.env.NEXT_TRAILING_SLASH = 'false'
+
+      const result = formatAdminURL({
+        adminRoute: defaultAdminRoute,
+        path: dummyPath,
+        relative: true,
+      })
+
+      expect(result).toBe(`${defaultAdminRoute}${dummyPath}`)
+    })
+  })
 })

packages/payload/src/utilities/formatAdminURL.ts

@@ -51,11 +51,24 @@ export const formatAdminURL = (args: FormatURLArgs): string => {
 
   if (relative || !serverURL) {
     if (includeBasePath && basePath) {
-      return pathnameWithBase
+      return applyTrailingSlash(pathnameWithBase)
     }
-    return pathname
+    return applyTrailingSlash(pathname)
   }
 
   const serverURLObj = new URL(serverURL)
-  return new URL(pathnameWithBase, serverURLObj.origin).toString()
+  return applyTrailingSlash(new URL(pathnameWithBase, serverURLObj.origin).toString())
+}
+
+const applyTrailingSlash = (url: string): string => {
+  if (process.env.NEXT_TRAILING_SLASH !== 'true') {
+    return url
+  }
+  const queryIndex = url.search(/[?#]/)
+  const pathPart = queryIndex === -1 ? url : url.slice(0, queryIndex)
+  const queryPart = queryIndex === -1 ? '' : url.slice(queryIndex)
+  if (pathPart.endsWith('/')) {
+    return url
+  }
+  return `${pathPart}/${queryPart}`
 }

packages/payload/src/utilities/handleEndpoints.ts

@@ -143,11 +143,14 @@ export const handleEndpoints = async ({
     const { payload } = req
     const { config } = payload
 
-    const pathname = path ?? new URL(req.url!).pathname
-    const baseAPIPath = formatAdminURL({
+    const rawPathname = path ?? new URL(req.url!).pathname
+    const pathname = rawPathname.length > 1 ? rawPathname.replace(/\/$/, '') : rawPathname
+    const rawBaseAPIPath = formatAdminURL({
       apiRoute: config.routes.api,
       path: '',
     })
+    const baseAPIPath =
+      rawBaseAPIPath.length > 1 ? rawBaseAPIPath.replace(/\/$/, '') : rawBaseAPIPath
 
     if (!pathname.startsWith(baseAPIPath)) {
       return notFoundResponse(req, pathname)

test/trailing-slash/.gitignore

@@ -0,0 +1,2 @@
+/media
+/media-gif

test/trailing-slash/app/(payload)/admin/[[...segments]]/not-found.tsx

@@ -0,0 +1,25 @@
+/* THIS FILE WAS GENERATED AUTOMATICALLY BY PAYLOAD. */
+/* DO NOT MODIFY IT BECAUSE IT COULD BE REWRITTEN AT ANY TIME. */
+import type { Metadata } from 'next'
+
+import config from '@payload-config'
+import { generatePageMetadata, NotFoundPage } from '@payloadcms/next/views'
+
+import { importMap } from '../importMap.js'
+
+type Args = {
+  params: Promise<{
+    segments: string[]
+  }>
+  searchParams: Promise<{
+    [key: string]: string | string[]
+  }>
+}
+
+export const generateMetadata = ({ params, searchParams }: Args): Promise<Metadata> =>
+  generatePageMetadata({ config, params, searchParams })
+
+const NotFound = ({ params, searchParams }: Args) =>
+  NotFoundPage({ config, importMap, params, searchParams })
+
+export default NotFound

test/trailing-slash/app/(payload)/admin/[[...segments]]/page.tsx

@@ -0,0 +1,25 @@
+/* THIS FILE WAS GENERATED AUTOMATICALLY BY PAYLOAD. */
+/* DO NOT MODIFY IT BECAUSE IT COULD BE REWRITTEN AT ANY TIME. */
+import type { Metadata } from 'next'
+
+import config from '@payload-config'
+import { generatePageMetadata, RootPage } from '@payloadcms/next/views'
+
+import { importMap } from '../importMap.js'
+
+type Args = {
+  params: Promise<{
+    segments: string[]
+  }>
+  searchParams: Promise<{
+    [key: string]: string | string[]
+  }>
+}
+
+export const generateMetadata = ({ params, searchParams }: Args): Promise<Metadata> =>
+  generatePageMetadata({ config, params, searchParams })
+
+const Page = ({ params, searchParams }: Args) =>
+  RootPage({ config, importMap, params, searchParams })
+
+export default Page

test/trailing-slash/app/(payload)/admin/importMap.js

@@ -0,0 +1,6 @@
+import { CollectionCards as CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1 } from '@payloadcms/next/rsc'
+
+/** @type import('payload').ImportMap */
+export const importMap = {
+  '@payloadcms/next/rsc#CollectionCards': CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1,
+}

test/trailing-slash/app/(payload)/api/[...slug]/route.ts

@@ -0,0 +1,10 @@
+/* THIS FILE WAS GENERATED AUTOMATICALLY BY PAYLOAD. */
+/* DO NOT MODIFY IT BECAUSE IT COULD BE REWRITTEN AT ANY TIME. */
+import config from '@payload-config'
+import { REST_DELETE, REST_GET, REST_OPTIONS, REST_PATCH, REST_POST } from '@payloadcms/next/routes'
+
+export const GET = REST_GET(config)
+export const POST = REST_POST(config)
+export const DELETE = REST_DELETE(config)
+export const PATCH = REST_PATCH(config)
+export const OPTIONS = REST_OPTIONS(config)

test/trailing-slash/app/(payload)/api/graphql-playground/route.ts

@@ -0,0 +1,6 @@
+/* THIS FILE WAS GENERATED AUTOMATICALLY BY PAYLOAD. */
+/* DO NOT MODIFY IT BECAUSE IT COULD BE REWRITTEN AT ANY TIME. */
+import config from '@payload-config'
+import { GRAPHQL_PLAYGROUND_GET } from '@payloadcms/next/routes/index.js'
+
+export const GET = GRAPHQL_PLAYGROUND_GET(config)

test/trailing-slash/app/(payload)/api/graphql/route.ts

@@ -0,0 +1,8 @@
+/* THIS FILE WAS GENERATED AUTOMATICALLY BY PAYLOAD. */
+/* DO NOT MODIFY IT BECAUSE IT COULD BE REWRITTEN AT ANY TIME. */
+import config from '@payload-config'
+import { GRAPHQL_POST, REST_OPTIONS } from '@payloadcms/next/routes'
+
+export const POST = GRAPHQL_POST(config)
+
+export const OPTIONS = REST_OPTIONS(config)

test/trailing-slash/app/(payload)/custom.scss

@@ -0,0 +1,7 @@
+#custom-css {
+  font-family: monospace;
+}
+
+#custom-css::after {
+  content: 'custom-css';
+}

test/trailing-slash/app/(payload)/layout.tsx

@@ -0,0 +1,31 @@
+/* THIS FILE WAS GENERATED AUTOMATICALLY BY PAYLOAD. */
+/* DO NOT MODIFY IT BECAUSE IT COULD BE REWRITTEN AT ANY TIME. */
+import type { ServerFunctionClient } from 'payload'
+
+import config from '@payload-config'
+import { handleServerFunctions, RootLayout } from '@payloadcms/next/layouts'
+import React from 'react'
+
+import { importMap } from './admin/importMap.js'
+import './custom.scss'
+
+type Args = {
+  children: React.ReactNode
+}
+
+const serverFunction: ServerFunctionClient = async function (args) {
+  'use server'
+  return handleServerFunctions({
+    ...args,
+    config,
+    importMap,
+  })
+}
+
+const Layout = ({ children }: Args) => (
+  <RootLayout config={config} importMap={importMap} serverFunction={serverFunction}>
+    {children}
+  </RootLayout>
+)
+
+export default Layout

test/trailing-slash/collections/Posts.ts

@@ -0,0 +1,19 @@
+import type { CollectionConfig } from 'payload'
+
+export const Posts: CollectionConfig = {
+  slug: 'posts',
+  admin: {
+    useAsTitle: 'title',
+  },
+  fields: [
+    {
+      name: 'title',
+      type: 'text',
+      required: true,
+    },
+    {
+      name: 'content',
+      type: 'textarea',
+    },
+  ],
+}

test/trailing-slash/config.ts

@@ -0,0 +1,14 @@
+import { buildConfigWithDefaults } from '../buildConfigWithDefaults.js'
+import { Posts } from './collections/Posts.js'
+import { seed } from './seed/index.js'
+
+process.env.NEXT_TRAILING_SLASH = 'true'
+
+export default buildConfigWithDefaults({
+  admin: {
+    autoLogin: false,
+  },
+  collections: [Posts],
+  onInit: seed,
+  serverURL: `http://localhost:${process.env.PORT || 3000}`,
+})