Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

sannajammeh
Copy link
Contributor

@sannajammeh sannajammeh commented Aug 5, 2025

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

@sannajammeh sannajammeh changed the title [plugin-cloud-storage]: move @payloadcms/ui to peerDependency to avoid dep conflict with react-context fix: move @payloadcms/ui to peerDependency to avoid dep conflict with react-context Aug 5, 2025
@sannajammeh sannajammeh changed the title fix: move @payloadcms/ui to peerDependency to avoid dep conflict with react-context fix: move @payloadcms/ui to peerDependency in plugin-cloud-storage to avoid dep conflict with react-context Aug 5, 2025
@AlessioGr
Copy link
Member

AlessioGr commented Aug 5, 2025

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
Copy link

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
Copy link

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

@sannajammeh
Copy link
Contributor Author

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
Copy link

@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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants