Payload CMS — Custom Admin Panel Location

Payload is flexible about where the Admin Panel lives in a Next.js App Router project. You can rename the route, nest it deeper, or co-locate it with custom admin dashboards.

Default Folder Structure

app/ (or src/app/)
└── (payload)/
    ├── admin/
    │   ├── [[...segments]]/
    │   │   ├── not-found.tsx
    │   │   └── page.tsx
    │   └── importMap.js        ← auto-generated, never edit manually
    ├── api/
    │   └── [...slug]/route.ts
    ├── custom.scss
    └── layout.tsx              ← safe to edit despite the "DO NOT MODIFY" warning

Scenario 1 — Rename the Route (`/admin` → `/dashboard`)

Config:

buildConfig({ routes: { admin: '/dashboard' } })

Move folder: mv app/(payload)/admin app/(payload)/dashboard

Update layout.tsx import:

import { importMap } from './dashboard/importMap.js'

Restart dev server.

Scenario 2 — Move the Entire `(payload)` Folder

Moves both Admin UI and REST API under a custom prefix (e.g. /admin/content).

Gotcha: (payload)/admin/ is a Next.js route segment, so placing (payload) at app/admin/content/(payload) gives you /admin/content/admin, not /admin/content.

Config:

buildConfig({
  routes: {
    admin: '/admin/content/admin',
    api: '/admin/content/api',
    graphQL: '/admin/content/api/graphql',
    graphQLPlayground: '/admin/content/api/graphql-playground',
  },
  admin: {
    importMap: {
      baseDir: path.resolve(dirname, './src/app/admin/content/(payload)'),
      importMapFile: path.resolve(
        dirname,
        './src/app/admin/content/(payload)/admin/importMap.js',
      ),
    },
  },
})

Steps:

mkdir -p app/admin/content && mv app/(payload) app/admin/content/(payload)
Verify layout.tsx import path (usually stays './admin/importMap.js')
pnpm payload generate:importmap

Scenario 3 — Multiple Admin Dashboards

app/admin/
├── content/(payload)/   ← Payload CMS
├── platform/            ← custom admin
└── page.tsx             ← landing page choosing between admins

Same config as Scenario 2; just add your custom routes alongside (payload).

Auto-Generated vs Safe-to-Edit Files

File	Auto-Generated?	Safe to Edit?
`layout.tsx`	No (created once by create-payload-app)	Yes — update import paths here
`admin/importMap.js`	Yes (startup, HMR, manual cmd)	No — configure via `admin.importMap`
`admin/[[...segments]]/page.tsx`	No	Rarely needed
`api/[...slug]/route.ts`	No	Rarely needed
`custom.scss`	No	Yes

Note: The "DO NOT MODIFY" comment in layout.tsx is misleading — it was generated once during create-payload-app and Payload never overwrites it. Safe to edit import paths.

`importMap.js` Regeneration Triggers

App startup (dev or prod build)
HMR (when component files change)
pnpm payload generate:importmap (manual)

Never edit importMap.js directly — configure paths via admin.importMap.baseDir / importMapFile.

Troubleshooting

Symptom	Fix
Import map not found	Check `admin.importMap.importMapFile` is absolute; run `pnpm payload generate:importmap`
`layout.tsx` import error	Path must be relative from `layout.tsx` → `importMap.js`; verify after folder move
Admin panel 404	Verify `routes.admin` matches actual folder structure; ensure entire `(payload)` was moved
Custom components not loading	Check `admin.importMap.baseDir`; regenerate import map

Key Takeaways

routes.admin in Payload config must match the actual Next.js folder path.
When you rename/move admin/, update the import { importMap } line in layout.tsx.
Moving (payload) deeper adds its subfolder names to the URL — plan the nesting accordingly.
importMap.js is always auto-generated; configure its location via admin.importMap, never edit the file.
layout.tsx is safe to edit despite the generated-file warning.
After any folder move, run pnpm payload generate:importmap to be safe.

Sources

raw/admin__admin-panel-location.md
https://payloadcms.com/docs/admin/admin-panel-location

5 KiB Raw Blame History

Payload CMS — Custom Admin Panel Location

Default Folder Structure

Scenario 1 — Rename the Route (/admin → /dashboard)

Scenario 2 — Move the Entire (payload) Folder