fix: move @payloadcms/ui to peerDependency in plugin-cloud-storage to avoid dep conflict with react-context

[sannajammeh]

What?

Fixes a dependency issue inside of @payloadcms/plugin-cloud-storage

Why?

Bun, NPM and rarely pnpm experience a dependency conflict from @payloadcms/ui inside of @payloadcms/plugin-cloud-storage. The dependency conflict triggers duplicated React Context references causing the admin UI to crash and become inaccessible

How?

Moves @payloadcms/ui out of dependencies and into peerDependencies & devDependencies

Fixes #

#11717
#13353

[AlessioGr]

My initial thoughts: the root issue likely stems from installing a different version of plugin-cloud-storage (can happen unintentionally, e.g. by prefixing the version with ^) than @payloadcms/next or other payload packages. This is not supported and should be fixed by ensuring dependencies are not duplicated. We could also look into improving our runtime dependency checker.

This happens more frequently in monorepos where package managers sometimes behave in very unpredictable ways. I think eventually this should be fixed by those package managers - in the meantime, webpack aliases could help.

This change would force the user to install @payloadcms/ui which would be a breaking change, + I don't think manually installing that package should be required unless you plan on directly using it in your app

[robinscholz]

My initial thoughts: the root issue likely stems from installing a different version of plugin-cloud-storage (can happen unintentionally, e.g. by prefixing the version with ^) than @payloadcms/next or other payload packages. This is not supported and should be fixed by ensuring dependencies are not duplicated. We could also look into improving our runtime dependency checker.

This happens more frequently in monorepos where package managers sometimes behave in very unpredictable ways. I think eventually this should be fixed by those package managers - in the meantime, webpack aliases could help.

This change would force the user to install @payloadcms/ui which would be a breaking change, + I don't think manually installing that package should be required unless you plan on directly using it in your app

Wouldn’t @payloadcms/ui already be installed by payload itself anyways? I’d argue no one is using this package without also using payload.

Having certain payload packages as peer deps with a minimum version needs to be the way to go for any external payload plugins as well. So its something that will occur within the ecosystem either way.

[robinscholz]

As far as I understand npm installs peer deps automatically. For pnpm you could set peerDependenciesMeta to optional: false for the package.

[sannajammeh]

My initial thoughts: the root issue likely stems from installing a different version of plugin-cloud-storage (can happen unintentionally, e.g. by prefixing the version with ^) than @payloadcms/next or other payload packages. This is not supported and should be fixed by ensuring dependencies are not duplicated. We could also look into improving our runtime dependency checker.
This happens more frequently in monorepos where package managers sometimes behave in very unpredictable ways. I think eventually this should be fixed by those package managers - in the meantime, webpack aliases could help.
This change would force the user to install @payloadcms/ui which would be a breaking change, + I don't think manually installing that package should be required unless you plan on directly using it in your app

Wouldn’t @payloadcms/ui already be installed by payload itself anyways? I’d argue no one is using this package without also using payload.

Having certain payload packages as peer deps with a minimum version needs to be the way to go for any external payload plugins as well. So its something that will occur within the ecosystem either way.

Agreed.

Additionally for me, this occurs in Bun PM with all versions pinned to 3.50.0 . @payloadcms/ui is by definition a peer dependency in this case as its already pre-installed by payload.

[robinscholz]

@AlessioGr How should we setup dependencies in payload plugins that are not maintained by the payload team?

We have opted now to set them up like this:

"peerDependencies": {
    "@mux/mux-player-react": "^3",
    "@payloadcms/plugin-cloud-storage": "^3.49",
    "@payloadcms/ui": "^3.49",
    "payload": "^3.49",
    "react": "^19.1",
    "react-dom": "^19.1"
  },
  "peerDependenciesMeta": {
    "@mux/mux-player-react": {
      "optional": false
    },
    "@payloadcms/plugin-cloud-storage": {
      "optional": false
    }
  },

The reason being that payload, @payloadcms/ui, react and react-dom are essentially always present within payload itself. The other dependencies could either be peer dependencies or dependencies, but we have opted for peer deps, to allow the user to control the versioning. They might use @mux/mux-player-react in their frontend as well, and we didn’t want to set a hard dependency for @payloadcms/plugin-cloud-storage since it always needs to be in sync with payload itself.

Though this still leads to the aforementioned bug appearing from time to time, at least in our monorepo. What would you suggest we do?