Payload needs better documentation around moving the payload folder/root access

[AndreasGalster2]

Documentation Issue

I wanted to achieve this structure for my two admin dashboards:

• /admin/content
  • this should be the payload folder, so basically /(payload)/admin route
  • Effectively, this would mean I'd need /admin/(payload)/admin and maybe have a rewrite for the double admin to point to admin/content... or better, rename it to /admin/(payload)/content...
    • I really did NOT want to do the rewrite, because I figured something would be bound to go wrong with payload's setup
• /admin/platform
  • This is my own admin routes for my product

It appeared (payload) folder cannot be moved. When you moved the payload folder from the root of the project into /admin, it complained about not finding the right import maps in /src/app/(payload)... Or was it /src/(payload)... I forgot... Anyway, point is that payload tries to find import maps by looking for the default root folder.

I then spent a long time figuring out if this possible. The confusing parts are about the fact that all payload files say "do not edit, they can be overwritten by payload at any time.", but also, there's no mention on how to completely move the entire payload directory.

The solution

I solved this. I think. It seems to work. Though I am not sure about implications. I moved the /(payload)/admin folder content into /(payload), so I moved everything in admin into its root... This means, you need to change the import to the admin folder, to the root payload folder in the layout.

Also your payload config needs to edit import maps and routes:

  admin: {
    importMap: {
      importMapFile: "./src/app/admin/content/(payload)/importMap.ts",
      baseDir: "./src/app/admin/content/(payload)",
    },
  },
  routes: { 
    admin: "/admin/content",
    api: "/admin/content/api",
    graphQL: "/admin/content/api/graphql",
    graphQLPlayground: "/admin/content/api/graphql-playground",        
  },

Admin here is the high level folder for BOTH my admin dashboards, app admin dashboard, AND payload.

• /content is payload
• /platform is normal dashboards

page.tsx is a page just to choose between general admin, or payload admin.

I really think this needs better documentation. It was not obvious at all and I spent quite some time figuring this out. But more so, I have no idea if this is safe. I ultimately had to change the importMap path in layout.tsx

From this...
import { importMap } from '../importMap.js'

to this...
import { importMap } from './importMap.js'

But the files all say "do not edit"... So this would imply you absolutely SHOULD NOT change this path since it may revert back to ../importMap.js, but the docs say if you want to have it in root, move the admin folder, plus, the payload config that I mentioned above make no sense if this isn't supported... It's very contradictory. I really think this needs more specific documentation about

• moving the entire payload folder in general.. it seems via importMap settings, this works, but who knows long-term what may happen
• implications of moving the admin folder, you HAVE to edit the layout.tsx... so is it safe?
• why should we not edit it, or rather, what causes edits to those files to be overwritten? If even the docs tell you to move the admin folder, but then you HAVE to edit at least the layout.tsx file, this is 100% a contradiction... I assume edits to any of the payload files only happen for import maps, and maybe when you run some kind of npx update payload-like commands, but it's not clear what may cause for the files to be overwritten

I believe that I have a working version, but I really do not know if anything here will break in the future, of if there is something in Payload that's not working, that I simply haven't discovered yet.