Improve Auth.js Intro

[maticzav]

What is the improvement or update you wish to see?

Hey,

I tried checking out Auth.js today and I noticed that the first line of getting started might be very confusing to newcomers like me.

My main question when opening getting started was "why would I use auth.js" which I think roughly translates to "which problem does auth.js help me solve".

Auth.js is a runtime agnostic library based on standard Web APIs that deeply integrates with modern JavaScript frameworks via additional libraries that wrap the core functionality and tailor it to the framework’s best practices. This documentation covers next-auth@5.0.0-beta and later and all other frameworks under the @auth/* namespace. Documentation for next-auth@4.x.y can still be found at next-auth.js.org.

After reading the first line I cannot really understand why I would use auth.js or better said, if I didn't know that it's considered a go to auth library for NextJS I'd have no idea what it does.

Consider

X is a runtime agnostic library based on standard Web APIs that deeply integrates with modern JavaScript frameworks via additional libraries that wrap the core functionality and tailor it to the framework’s best practices. This documentation covers X@beta and later and all other frameworks under the @X/* namespace. Documentation for X@legacy can still be found at xyz.com.

My gut feeling tells me that this headline aims to answer the following questions

• does it work with Bun, NodeJS, AWS, ...?
• is this NextJS framework specific?
• where can I find old docs?

which all seem very valid questions, but again don't seem very suitable to me for a newcomer who just wants to know what this library is about.

Is there any context that might help us understand?

I only checked the front page and I am very confident that the first three pages also answer my question.

Does the docs page already exist? Please link to it.

https://authjs.dev/getting-started

[balazsorban44]

I agree! We will try to rephrase this section.

[github-actions]

This issue was marked with the good first issue label by a maintainer.

This means that it is a good candidate for someone interested in contributing to the project, but does not know where to start.

Have a look at the Contributing Guide first.

This will help you set up your development environment to get started. When you are ready, open a PR, and link back to this issue in the form of adding Fixes #1234 to the PR description, where 1234 is the issue number. This will auto-close the issue when the PR gets merged, making it easier for us to keep track of what has been fixed.

Please make sure that - if applicable - you add tests for the changes you make.

If you have any questions, feel free to ask in the comments below or the PR. Generally, you don't need to @mention anyone directly, as we will get notified anyway and will respond as soon as we can)

Note

There is no need to ask for permission "can I work on this?" Please, go ahead if there is no linked PR 🙂