github-starred/better-auth
2
0
Fork 0
mirror of https://github.com/better-auth/better-auth.git synced 2026-05-22 22:32:01 -05:00
Code Issues 2.5k Packages Projects Releases 112 Wiki Activity

docs: middleware examples in Next.js intergration docs is bit misleading #2349

New Issue
Open
opened 2026-03-13 09:45:47 -05:00 by GiteaMirror · 7 comments
GiteaMirror commented 2026-03-13 09:45:47 -05:00
Owner
Copy Link

Originally created by @DarkstarXDD on GitHub (Nov 22, 2025).

https://www.better-auth.com/docs/integrations/next#nextjs-16-proxy

In this first example code, I think the comment is bit confusing. It says it's not secure and it's the recommended approach as well. However, it's actually doing a full session lookup from the database using the getSession() function. So I think it's actually secure, but not recommended since it's doing a database lookup inside middleware, which Next,js recommends against.

So I feel like the comment should just say "It's not recommended" or something like that, instead of saying "Secure or Not secure".

This same issue is present in here as well: https://www.better-auth.com/docs/integrations/next#nextjs-1520-nodejs-runtime-middleware

There is also another small typo at the beginning of that docs page where the text says the file name is client.ts but the code snippet's file name block says auth-client.ts. https://www.better-auth.com/docs/integrations/next#create-a-client

I am happy to make a PR updating those parts, but wanted to mention it here first to make sure I am not missing something.

Originally created by @DarkstarXDD on GitHub (Nov 22, 2025). https://www.better-auth.com/docs/integrations/next#nextjs-16-proxy In this first example code, I think the comment is bit confusing. It says it's not secure and it's the recommended approach as well. However, it's actually doing a full session lookup from the database using the `getSession()` function. So I think it's actually secure, but not recommended since it's doing a database lookup inside middleware, which Next,js recommends against. So I feel like the comment should just say "It's not recommended" or something like that, instead of saying "Secure or Not secure". This same issue is present in here as well: https://www.better-auth.com/docs/integrations/next#nextjs-1520-nodejs-runtime-middleware There is also another small typo at the beginning of that docs page where the text says the file name is `client.ts` but the code snippet's file name block says `auth-client.ts`. https://www.better-auth.com/docs/integrations/next#create-a-client I am happy to make a PR updating those parts, but wanted to mention it here first to make sure I am not missing something.
GiteaMirror added the documentation label 2026-03-13 09:45:47 -05:00
GiteaMirror commented 2026-03-13 09:45:48 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Nov 22, 2025):

(tag @better-auth-agent if you would like an answer from the Agent)

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Nov 22, 2025): (tag @better-auth-agent if you would like an answer from the Agent) <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-03-13 09:45:49 -05:00
Author
Owner
Copy Link

@dosubot[bot] commented on GitHub (Nov 22, 2025):

You're right—doing a full session lookup with getSession() in middleware is secure, but it's not recommended due to performance concerns and Next.js best practices. The documentation comments should clarify this distinction, focusing on recommendation rather than security alone. This feedback matches ongoing community requests for clearer warnings and examples in the docs (example, example).

Recent updates have improved the docs, but the specific typo between client.ts and auth-client.ts hasn't been addressed yet (PR #5296). Your proposed changes—clarifying the comment wording and fixing the typo—are spot on and would be a helpful contribution. If you want a suggestion for the comment, something like:
// This is secure, but not recommended in middleware due to performance.
would be clear and accurate.

Feel free to proceed with your PR!

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other

Chat with Dosu Open in Cursor Join Discord Share on X

@dosubot[bot] commented on GitHub (Nov 22, 2025): <!-- Answer --> You're right—doing a full session lookup with `getSession()` in middleware is secure, but it's not recommended due to performance concerns and Next.js best practices. The documentation comments should clarify this distinction, focusing on recommendation rather than security alone. This feedback matches ongoing community requests for clearer warnings and examples in the docs ([example](https://github.com/better-auth/better-auth/issues/5120), [example](https://github.com/better-auth/better-auth/issues/5376)). Recent updates have improved the docs, but the specific typo between `client.ts` and `auth-client.ts` hasn't been addressed yet ([PR #5296](https://github.com/better-auth/better-auth/pull/5296)). Your proposed changes—clarifying the comment wording and fixing the typo—are spot on and would be a helpful contribution. If you want a suggestion for the comment, something like: `// This is secure, but not recommended in middleware due to performance.` would be clear and accurate. Feel free to proceed with your PR! <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/b180c641-9c3d-4c42-97bb-d10df30f7daa?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/b180c641-9c3d-4c42-97bb-d10df30f7daa?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/b180c641-9c3d-4c42-97bb-d10df30f7daa?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/b180c641-9c3d-4c42-97bb-d10df30f7daa?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/b180c641-9c3d-4c42-97bb-d10df30f7daa?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/b180c641-9c3d-4c42-97bb-d10df30f7daa?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/b180c641-9c3d-4c42-97bb-d10df30f7daa?feedback_type=other)</sup> [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/cdda13d9-dd27-4d31-b09a-5d8bec92de21/ask?utm_source=github)&nbsp;[![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=You%27re%20right%E2%80%94doing%20a%20full%20session%20lookup%20with%20%60getSession%28%29%60%20in%20middleware%20is%20secure%2C%20but%20it%27s%20not%20recommended%20due%20to%20performance%20concerns%20and%20Next.js%20best%20practices.%20The%20documentation%20comments%20should%20clarify%20this%20distinction%2C%20focusing%20on%20recommendation%20rather%20than%20security%20alone.%20This%20feedback%20matches%20ongoing%20community%20requests%20for%20clearer%20warnings%20and%20examples%20in%20the%20docs%20%28%5Bexample%5D%28https%3A//github.com/better-auth/better-auth/issues/5120%29%2C%20%5Bexample%5D%28https%3A//github.com/better-auth/better-auth/issues/5376%29%29.%20%0A%0ARecent%20updates%20have%20improved%20the%20docs%2C%20but%20the%20specific%20typo%20between%20%60client.ts%60%20and%20%60auth-client.ts%60%20hasn%27t%20been%20addressed%20yet%20%28%5BPR%20%235296%5D%28https%3A//github.com/better-auth/better-auth/pull/5296%29%29.%20Your%20proposed%20changes%E2%80%94clarifying%20the%20comment%20wording%20and%20fixing%20the%20typo%E2%80%94are%20spot%20on%20and%20would%20be%20a%20helpful%20contribution.%20If%20you%20want%20a%20suggestion%20for%20the%20comment%2C%20something%20like%3A%20%20%0A%60//%20This%20is%20secure%2C%20but%20not%20recommended%20in%20middleware%20due%20to%20performance.%60%20%20%0Awould%20be%20clear%20and%20accurate.%0A%0AFeel%20free%20to%20proceed%20with%20your%20PR%21)&nbsp;[![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot)&nbsp;[![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/better-auth/better-auth/issues/6187)
GiteaMirror commented 2026-03-13 09:45:49 -05:00
Author
Owner
Copy Link

@AntonVishal commented on GitHub (Nov 22, 2025):

Hey @DarkstarXDD the typo can be fixed, but reg the proxy/middleware upto my knowledge what it conveys is that Better Auth recommends checking auth session in every route/page separately, but if you deliberately want to check auth session in proxy/middleware you can use that example but with a caution it is not secure.

@AntonVishal commented on GitHub (Nov 22, 2025): Hey @DarkstarXDD the typo can be fixed, but reg the proxy/middleware upto my knowledge what it conveys is that Better Auth recommends checking auth session in every route/page separately, but if you deliberately want to check auth session in proxy/middleware you can use that example but with a caution it is not secure.
GiteaMirror commented 2026-03-13 09:45:50 -05:00
Author
Owner
Copy Link

@DarkstarXDD commented on GitHub (Nov 23, 2025):

@AntonVishal Hey, thanks for the response.

Yeah, what you are saying is correct. However, that is not the idea the inline comments in the first code example currently convery.

https://www.better-auth.com/docs/integrations/next#nextjs-16-proxy

It says,

  1. This is not secure.
  2. This is the recommended approach to optimistically redirect users.

But the optimisitc check is not that first example. It's the second example. First example uses the getSession() function which calls the database, so it can't be called an "optimistic check". And since it's doing a full session lookup using the database call it's actually secure (thgouh this ideally shouldn't be done in middleware).

Happy to be corrected if I am missing something.

@DarkstarXDD commented on GitHub (Nov 23, 2025): @AntonVishal Hey, thanks for the response. Yeah, what you are saying is correct. However, that is not the idea the inline comments in the first code example currently convery. https://www.better-auth.com/docs/integrations/next#nextjs-16-proxy It says, 1. This is not secure. 2. This is the recommended approach to optimistically redirect users. But the optimisitc check is not that first example. It's the second example. First example uses the `getSession()` function which calls the database, so it can't be called an "optimistic check". And since it's doing a full session lookup using the database call it's actually secure (thgouh this ideally shouldn't be done in middleware). Happy to be corrected if I am missing something.
GiteaMirror commented 2026-03-13 09:45:51 -05:00
Author
Owner
Copy Link

@AntonVishal commented on GitHub (Nov 23, 2025):

Agree, um @better-auth-agent your thoughts here

@AntonVishal commented on GitHub (Nov 23, 2025): Agree, um @better-auth-agent your thoughts here
GiteaMirror commented 2026-03-13 09:45:51 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Nov 23, 2025):

Thanks for pointing this out! You're right that the example is secure since it performs a full session lookup using getSession(), but it’s not recommended due to the performance hit from the database lookup in middleware. We should definitely update the comment to clarify that it's not recommended instead of calling it "not secure." The typo regarding the file name should also be fixed to avoid confusion. It’d be great if you could open a PR with these changes, or let us know if you’d prefer our team to handle them. Tag @bekacru and @ping__ for further input from the core team. Tag @better-auth-agent if you would like an answer from the Agent.

What additional clarifications or changes would you like to see in the Next.js integration docs?

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Nov 23, 2025): Thanks for pointing this out! You're right that the example is secure since it performs a full session lookup using getSession(), but it’s not recommended due to the performance hit from the database lookup in middleware. We should definitely update the comment to clarify that it's not recommended instead of calling it "not secure." The typo regarding the file name should also be fixed to avoid confusion. It’d be great if you could open a PR with these changes, or let us know if you’d prefer our team to handle them. Tag @bekacru and @ping__ for further input from the core team. Tag @better-auth-agent if you would like an answer from the Agent. What additional clarifications or changes would you like to see in the Next.js integration docs? <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-03-13 09:45:52 -05:00
Author
Owner
Copy Link

@pvgpe commented on GitHub (Jan 7, 2026):

as a new user i was confused by this bit in the docs

@pvgpe commented on GitHub (Jan 7, 2026): as a new user i was confused by this bit in the docs
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
adapter
astro
awaiting external contributor
blocked
breaking
breaking change
bug
c-devops
core
credentials
database
dependencies
devops
devtools
docs
documentation
duplicate
elysia
enhancement
enterprise
expo
express
fastify
good first issue
help wanted
hono
identity
infra
integration
invalid
javascript
locked
maintenance
need-more-information
needs: info
needs: repro
nextjs
nuxt
oauth
organization
P0
payments
perf
platform
plugin
pull-request
Mirrored from GitHub Pull Request
 question
ready
regression
remix
security
social-provider
solid
stale
svelte
tanstack-start
tracking
version-bump
vue
wontfix
No Label documentation
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/better-auth#2349
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?