search

nextauthjs / next-auth

Authentication for the Web.
https://authjs.dev
ISC License
24.28k stars 3.38k forks source link

Unclear Documentation #7271

Closed yourcodesnotworking closed 1 year ago

yourcodesnotworking commented 1 year ago

What is the improvement or update you wish to see?

I wanna see code examples for Next.js 13.2+ Once you codes copied from your get started page, it should work.

Also, if you are trying give example for Next.js 13.2+,

  1. Getting Started ?? Getting Started Page NO CODE EXAMPLE WHATSOEVER!

  2. "Credentials Provider is as simple as initializing it in the Auth.js configuration file" ? Credentials authentication What about Next.js 13.2+? NO NEED? or anyone should understand your code automatically after seen your code example?

  3. Ok next link: Database ?? Databases Do you mean those first two steps should definitely works, so we should choose if using database? Do I need come back to next-auth page? It's a kind of scary choice, cause you're saying "NextAuth.js is becoming Auth.js! 🎉 "

It seems your https://authjs.dev is for advanced developers to read. Does that mean if you're not advanced developers you should be abandoned on default?

Is there any context that might help us understand?

  1. Getting Started ?? Getting Started Page

  2. "Credentials Provider is as simple as initializing it in the Auth.js configuration file" ? (Credentials authentication)[https://authjs.dev/getting-started/credentials-tutorial]

  3. Ok next link: Database ?? Databases

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

See above links, thanks.

Dav3whit3 commented 1 year ago

There are maaaany 404 among the docs links as well

balazsorban44 commented 1 year ago

Please don't use pages directory, as it will be outdated in the future for sure.

This is incorrect. (note, I am part of the Next.js core team as well) pages is going to be maintained.

Please use app directory for API

https://next-auth.js.org/configuration/initialization#route-handlers-app

  1. The getting started page will be a high-level introduction to the different libraries, linking to the corresponding package documentation, which will have full code examples, showing up in your IDE as well. Example. https://authjs.dev/reference/core#usage The Getting Started page is work-in-progress though, thanks for the callout! I want it to look something like https://authjs.dev/reference/adapters
  2. The API has not changed between NextAuth.js and Auth.js for the Credentials provider, and if it will, we will document it clearly/add a migration guide. Long-term, we want a tab-like solution where the documentation reader can choose their framework and all code examples will show that version across the guide docs. This is work-in-progress.
  3. I see this page is confusing, and I think we can safely remove it. You can visit https://authjs.dev/reference/adapters instead.

    It's a kind of scary choice, cause you're saying "NextAuth.js is becoming Auth.js!

We control both domains and we are committed to making the transition seamless, so when it is ready, you will have a clear path! It is totally safe to keep using next-auth, it even receives frequent updates. See https://github.com/nextauthjs/next-auth/releases

There are many 404s among the docs links as well

@Dav3whit3 could you report the broken links in an issue, with a link to the broken page, and where it came up/where did you find it? :pray: we cannot fix these unless we are aware! :green_heart:

As a general note, we acknowledge the current state has cases that need more work, and we are working on the documentation constantly. However authjs.dev does have a banner with the following "Note, this site is under active development. 🏗" to make it clear there might be issues. Also note, @auth/core and its ecosystem (@auth/*) is also under active development. If you care about stability, we recommend keeping relying on next-auth for the time being.

_But as a hint into the future, I am working on @auth/nextjs (Next.js Auth), the true successor of next-auth (NextAuth.js). Expect an announcement in the not-so-distant future. :shushingface:

I'm closing this issue as it's not actionable (apart from 3., which I'll get to right after this comment.)

If you have actionable feedback on the documentation (like missing pages or confusing documentation) please report them as separate issues with clear steps you would like to be taken. :pray:

Hope this helps!

balazsorban44 commented 1 year ago

Hmm. Upon re-reading, I actually think https://authjs.dev/getting-started/databases could be kept, but I cleaned it up and fixed a broken link. https://github.com/nextauthjs/next-auth/commit/9018939ee754304e802186809894a3728fc140f3