Custom Admin Panel Location

Payload is flexible about where your Admin Panel lives within your Next.js application. You can customize routes, move folders, and organize your project structure to match your application's needs.

• Custom admin routes - Change /admin to /dashboard, /cms, etc.
• Nested admin panels - Place Payload at /admin/content alongside custom admin routes
• Multiple admin interfaces - Organize Payload and custom dashboards together
• Organizational preferences - Match your team's folder structure conventions

By default, Payload creates this structure in your Next.js app:

• (payload)/ - Parent folder containing all Payload-related routes
• admin/ - Admin Panel UI routes
• api/ - REST API routes
• layout.tsx - Root layout that imports the import map
• importMap.js - Auto-generated file mapping component paths (regenerated on startup)

To change the admin route from /admin to /dashboard:

1. Update your Payload Config:

2. Move the folder:

3. Update the import path in layout.tsx:

Edit app/(payload)/layout.tsx and update the import map reference to match the new folder name:

4. Restart your dev server

Payload will now be available at /dashboard.

To move both the Payload Admin Panel and API under a custom path, you move the entire (payload) folder. This example places everything under /admin/content.

1. Update your Payload Config with all routes and import map settings:

2. Move the (payload) folder:

3. Update the import path in layout.tsx:

Edit app/admin/content/(payload)/layout.tsx:

The import path should be relative from layout.tsx to importMap.js. In this case, it remains './admin/importMap.js'.

4. Regenerate the import map:

Your Payload admin is now at /admin/content/admin and the API at /admin/content/api.

If you want both Payload and custom admin routes under /admin:

Folder Structure:

Configuration:

Not all files in the (payload) folder are auto-generated. Here's what you need to know:

You may see this warning in layout.tsx:

This warning is misleading. The file was generated during initial project setup by create-payload-app, but it is never regenerated by Payload. It is completely safe to modify this file, especially when customizing your folder structure.

When you move the Payload folder, you'll need to update the import path in layout.tsx:

What you can safely edit:

• Import map path (required when moving folders)
• Custom imports for additional functionality
• Custom SCSS imports
• Server function logic (advanced use cases)

What you should NOT edit:

• The core RootLayout usage (required for Payload)
• The serverFunction pattern (required for Payload to work)
• The import map prop to RootLayout

The importMap.js file is automatically regenerated in these scenarios:

• Application startup - Every time you start your dev server or production build
• Hot Module Replacement (HMR) - When you save changes to component files in development
• Manual generation - When you run pnpm payload generate:importmap

The import map is never regenerated during:

• Normal runtime (only at startup)
• After the production build completes

If you see an error about the import map not being found:

1. Verify admin.importMap.importMapFile points to the correct location
2. Run pnpm payload generate:importmap manually
3. Check that the path is absolute, not relative

If you see an import error in layout.tsx:

1. Verify the import path is relative from layout.tsx to importMap.js
2. Use ./admin/importMap.js if importMap is in a sibling admin folder
3. Use ./importMap.js if you moved importMap to the same folder as layout

If the admin panel returns 404:

1. Verify routes.admin matches your actual folder structure
2. Ensure you moved the entire (payload) folder, not just admin
3. Check that Next.js is recognizing your new routes

If custom components aren't loading:

1. Verify admin.importMap.baseDir is correct
2. Regenerate the import map: pnpm payload generate:importmap
3. Check component paths in your config are relative to baseDir

• Admin Panel Overview
• Custom Components
• Import Map Configuration
• Customizing Routes