React Peer Dependency Issue with gatsby-plugin-mdx

[pburrows]

Preliminary Checks

• This issue is not a duplicate. Before opening a new issue, please search existing issues: https://github.com/gatsbyjs/gatsby/issues
• This issue is not a question, feature request, RFC, or anything other than a bug report directly related to Gatsby. Please post those things in GitHub Discussions: https://github.com/gatsbyjs/gatsby/discussions

Description

I see bug reports that have been converted to discussions saying that running npm install --legacy-peer-deps is the solution for this issue.

If that is, indeed, the official response and solution for these issues, please update the documentation to say that using gatsby-plugin-mdx requires the use of legacy-peer-deps.

Honestly, I'm surprised this isn't considered an actual bug to fix. The default behavior to install apps is running npm install. Using the --legacy-peer-deps option should not be considered the official solution.

Reproduction Link

https://github.com/gatsbyjs/gatsby

Steps to Reproduce

1. run gatsby new
2. When prompted for additional functions choose Add Markdown and MDX support
3. Complete the wizard
4. Switch to the newly created directory and run npm install
   ...
   (note: I chose typescript when prompted, not sure if that matters)

Expected Result

npm install runs with no errors.

Actual Result

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: gatsby-plugin-mdx@5.13.1
npm ERR! Found: @mdx-js/react@3.0.1
npm ERR! node_modules/@mdx-js/react
npm ERR!   @mdx-js/react@"^3.0.1" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer @mdx-js/react@"^2.0.0" from gatsby-plugin-mdx@5.13.1
npm ERR! node_modules/gatsby-plugin-mdx
npm ERR!   gatsby-plugin-mdx@"^5.13.1" from the root project
npm ERR!
npm ERR! Conflicting peer dependency: @mdx-js/react@2.3.0
npm ERR! node_modules/@mdx-js/react
npm ERR!   peer @mdx-js/react@"^2.0.0" from gatsby-plugin-mdx@5.13.1
npm ERR!   node_modules/gatsby-plugin-mdx
npm ERR!     gatsby-plugin-mdx@"^5.13.1" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

Environment

System:
    OS: Windows 10 10.0.22631
    CPU: (32) x64 13th Gen Intel(R) Core(TM) i9-13900KF
  Binaries:
    Node: 18.18.2 - C:\Program Files\nodejs\node.EXE
    npm: 9.8.1 - C:\Program Files\nodejs\npm.CMD
  Languages:
    Python: 3.12.0
  Browsers:
    Edge: Chromium (123.0.2420.81)
  npmPackages:
    gatsby: ^5.13.3 => 5.13.3
    gatsby-plugin-mdx: ^5.13.1 => 5.13.1
    gatsby-source-filesystem: ^5.13.1 => 5.13.1

Config Flags

No response

[pburrows]

If it matters, I updated to the LTS version of node and this still happens (20.12.2 as of the time I write this)

[pburrows]

Keeping this alive. Still having to do this every single time you add a new dependency

[ishan123456789]

Same issue I just created a new project also on LTS version, also tried with v18 facing same error

[mgreiler]

I'm also running into this problem.

[Sewdohe]

This has been a longstanding issue with running MDX on Gatsby for way too long now :| At this point I guess I'll just create a command alias to append --legacy-peer-deps automatically from now on v_v Feels janky to use.

[KriszKecskes]

This solved me the issue:
https://stackoverflow.com/a/73557005

[patrickdemers6]

Related PR: #39009