Error setting up Local Environment following Contribution Guide: "Module not found: Can't resolve 'react'"

[BenjaminWFox]

Describe the bug
Setting up next-auth local environment following the steps in the contribution guide fails without explicitly installing react in next-auth

To Reproduce
git clone https://github.com/BenjaminWFox/next-auth.git
git clone https://github.com/iaincollins/next-auth-example.git

cd next-auth-example
npm install

cd ../next-auth
npm i
npm run build
npm link ../next-auth-example/node_modules/react

cd ../next-auth-example
npm link ../next-auth
npm run dev

> [email protected] dev /Users/benfox/Documents/Projects/Lumedic/Repositories/next-auth-example
> next

ready - started server on http://localhost:3000
error - ../next-auth/dist/client/index.js
Module not found: Can't resolve 'react' in '/Users/benfox/Documents/Projects/Lumedic/Repositories/next-auth/dist/client'

To Fix
cd ../next-auth
npm i -D react
npm link ../next-auth-example/node_modules/react

cd ../next-auth-example
npm run dev

Additional context
The peer dependencies are called out at the various npm stages. I'm unsure, and didn't find via google, whether there is some other, better, way to solve this issue.

npm WARN [email protected] requires a peer of react@^16.13.1 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of react-dom@^16.13.1 but none is installed. You must install peer dependencies yourself.

If there is not a better way to resolve this issue (and/or if I'm not missing something obvious) and installing react (npm i -D react) is, in fact, the best way to resolve this situation I can submit a PR for the documentation in the Contributing Guide.

I would change step 2 "Install packages and run the build command:" to:

npm i
npm i -D react
npm run build

Documentation feedback
Documentation refers to searching through online documentation, code comments and issue history. The example project refers to next-auth-example.

• Found the documentation helpful
• Found documentation but was incomplete
• Could not find relevant documentation
• Found the example project helpful
• Did not find the example project helpful

[iaincollins]

Hi there! I think it last came up in #181

I don't have React installed in next-auth locally when working on it, so I think it works already, but it is really fiddly.

IME doing this causes problems when using the useSession Hook, which is why React is not a devDependancy of next-auth already. This is all React's fault because it causes needless drama and throws an error if you don't, even if the versions of React in both repos match up - they literally have to point to the same place on disk.

Annoyingly, any time you run npm i to install a module in either the next-auth or the target next-auth-example it breaks this link and you need to do it again. I forget this several times a week.

I can only suggest trying the steps again really pedantically and seeing if that helps. I think they got improved the last time this came up.

We do need to find a better solution to improve the DX as it's a PITA right now. Including an example project in next-auth was how next-auth v1 handled it, but that comes with hidden gotchas too. I would really like to automate this though.

[BenjaminWFox]

Sorry, this is a long response, I got nerdsniped. Feel free to skip to the tl;dr 😁

I definitely agree, the npm link flows and trying to figure out which to do when and what the underlying problems are, especially with react, are awful 😭 I've had the same experience with other libraries I've built & worked on.

I did see that other issue, and spent about an hour and a half trying (what I thought was) every permutation of installation & linking I could think of with both the next-auth-example and the actual project I'm using it in. Explicitly installing it as a devDependency prior to linking it to react in my project directory was the only first thing that worked for me...but after some more digging I think this is a more correct solution.

Some more troubleshooting led me to a couple realizations, the first being that (perhaps obviously, but importantly) my project was looking in the next-auth node_modules folder for react. That's not right, though, because if I'm installing (as normal with npm install) next-auth in my project the peerDependencies of next-auth will already have been installed by my project.

So how to get my project to use the react it already has installed after linking next-auth? Turns out it's a bit of 🤦‍♂️ with npm link, and as my math teachers liked to say, order of operations matters.

I don't understand npm link well enough to know exactly why, but I suspect that existing symlinks are not carried over (or broken somehow) when running npm link in a package that already has a symlink to another package? So the link to the global react (created by npm link ../next-auth-example/node_modules/react) is broken when next-auth is linked & reference by my project with npm link ../next-auth`. (also see diagram at the bottom)

tl;dr

"My project" (whichever project) needs to npm link ../next-auth before next-auth runs npm link ../next-auth-example/node_modules/react

How about this for a proposed update to the documentation?

It would change the "option 1" as currently written to the "option 2" (basically swapping steps 3 & 4 as written):

git clone https://github.com/BenjaminWFox/next-auth.git
git clone https://github.com/iaincollins/next-auth-example.git

cd next-auth-example
npm install

cd ../next-auth
npm i
npm run build

option 1 - doesn't work:
npm link ../next-auth-example/node_modules/react

cd ../next-auth-example
npm link ../next-auth
npm run dev -> error

option 2 - works:
cd ../next-auth-example
npm link ../next-auth

cd ../next-auth
npm link ../next-auth-example/node_modules/react

cd ../next-auth-example
npm run dev -> success

Reference:

These are the links I followed that got me to this solution:

npm/npm#5875 > npm/npm#5875 (comment) > https://stackoverflow.com/a/38818358/1763258

This is a diagram I made to help my brain:

[iaincollins]

Please fee free to submit a change to the steps in the CONTRIBUTING.md 👍

[iaincollins]

Resolved in v3 with update from @BenjaminWFox!