5.0.0 Migration Guide

[jankapunkt]

Let's collect the most important topics here for a migration guide and where to add them.

There should definitely be a migration guide page in the overall docs (.rst file format) but there should also be some mention in the README.

The migration guide should point out two scenarios:

• users coming from 4.x branch
• users coming from oauthjs (which is 3.x branch)

Migration guide should point out what's breaking and strategies to get around most common issues.

We should also make a note that 4.x will be deprecated in the future and will only get security fixes.

[shrihari-prakash]

Do we try to convince users coming from oauthjs to use the node-oauth2-server package directly instead of the express adapter?

Few months before, I remember @HappyZombies mentioning that he prefers to use the package directly instead of the express adapter. In such cases, people coming from the legacy oauthjs package would be having difficulty since they recommend to use express adapter instead of spinning up their own server with the oauthjs package.

@HappyZombies why do you prefer not to use the express adapter package?

[jankapunkt]

Good point. We should underline in the very beginning of the guide, that the express adapter is already 5.x capable and link to it.

[HappyZombies]

@shrihari-prakash using the express adapter means you are tied to express and what other limitations we define on it; this module is framework agonistic -- meaning can be used in anything: like Koa, Next.js, etc.

In addition, I prefer to not use the adapter since I have special/custom flows to support two factor authentication, something that the express adapter won't let me support.

So basically, I use this module directly cuz it gives me a lot more control and customization.

[shrihari-prakash]

On a side note. I also think at this point that a direct integration with node-oauth2-server package gives me a lot more flexibility.

[jankapunkt]

It's all use-case dependent. If you just want things to "work" without big setup then the adapter might be preferable but if you need custom integrations or have most flexibility then the bare usage is recommended.

[shrihari-prakash]

Yes exactly. For me, the use case was complex. I think we can mention this point about the express adapter in migration guide.

[jankapunkt]

this is implemented in the latest 5.0.0 release