github-starred/better-auth
2
0
Fork 0
mirror of https://github.com/better-auth/better-auth.git synced 2026-08-24 14:34:26 -05:00
Code Issues 2.5k Packages Projects Releases 112 Wiki Activity

Incorrect documentation on listening to session changes #2014

New Issue
Closed
opened 2026-03-13 09:21:07 -05:00 by GiteaMirror · 2 comments
GiteaMirror commented 2026-03-13 09:21:07 -05:00
Owner
Copy Link
Copy Source

Originally created by @taylorcode on GitHub (Sep 24, 2025).

Is this suited for github?

  • Yes, this is suited for github

To Reproduce

The documentation at https://www.better-auth.com/docs/basic-usage#client-side provides this example for listening to session changes under the Vanilla tab.

import { authClient } from "~/lib/auth-client"; //import the auth client
authClient.useSession.subscribe((value)=>{
    //do something with the session //
});

This API is not supported at type checking time, nor at runtime. It appears to be a typo, as function starting with use do not (conventionally) have custom properties.

I've looked through the implementation of useSession, and cannot determine its approach to listen to session changes independently from using a hook. It appears that the useSession hook is dynamically generated at runtime, and invokes a function called useStore(), but accessing the session store outside of not obvious to me. https://github.com/better-auth/better-auth/blob/e892a53b89c63c6fad36bc37c2954e5307ef3cd1/packages/better-auth/src/client/react/index.ts#L58-L60

This feature would be valuable even within React and Vue apps because the session object is oftentimes passed into the state management and data fetching layers, which are decoupled from the rendering lifecycle. Since useSession is tied to rendering, it requires the developer to apply a workaround to synchronize it into these other layers. For example:

import {useEffect} from 'react';
import {useSetAtom} from 'jotai';
import {authClient} from '~/lib/auth/client`;
import {setSessionTransaction} from `~/lib/atoms/session`;

// hack - sync the session into the Jotai store as a side effect of rendering
function useSyncSession(): void {
  const {data: sessionData} = authClient.useSession();
  const setSession = useSetAtom(setSessionTransaction);

  useEffect(() => {
    setSession(sessionData);
  }, [sessionData]);
}

Current vs. Expected behavior

current: authClient.useSession.subscribe appears in documentation, but does not exist
expected: authClient.useSession.subscribe exists outside of Vue/React hook naming conventions, such as authClient.subscribe.

What version of Better Auth are you using?

1.3.4

System info

N/A

Which area(s) are affected? (Select all that apply)

Client

Auth config (if applicable)

Additional context

No response

Originally created by @taylorcode on GitHub (Sep 24, 2025). ### Is this suited for github? - [x] Yes, this is suited for github ### To Reproduce The documentation at https://www.better-auth.com/docs/basic-usage#client-side provides this example for listening to session changes under the `Vanilla` tab. ``` import { authClient } from "~/lib/auth-client"; //import the auth client authClient.useSession.subscribe((value)=>{ //do something with the session // }); ``` This API is not supported at type checking time, nor at runtime. It appears to be a typo, as function starting with `use` do not (conventionally) have custom properties. I've looked through the implementation of `useSession`, and _cannot_ determine its approach to listen to session changes independently from using a hook. It appears that the `useSession` hook is dynamically generated at runtime, and invokes a function called `useStore()`, but accessing the session store outside of not obvious to me. https://github.com/better-auth/better-auth/blob/e892a53b89c63c6fad36bc37c2954e5307ef3cd1/packages/better-auth/src/client/react/index.ts#L58-L60 This feature would be valuable even within React and Vue apps because the session object is oftentimes passed into the state management and data fetching layers, which are decoupled from the rendering lifecycle. Since `useSession` is tied to rendering, it requires the developer to apply a workaround to synchronize it into these other layers. For example: ``` import {useEffect} from 'react'; import {useSetAtom} from 'jotai'; import {authClient} from '~/lib/auth/client`; import {setSessionTransaction} from `~/lib/atoms/session`; // hack - sync the session into the Jotai store as a side effect of rendering function useSyncSession(): void { const {data: sessionData} = authClient.useSession(); const setSession = useSetAtom(setSessionTransaction); useEffect(() => { setSession(sessionData); }, [sessionData]); } ``` ### Current vs. Expected behavior current: `authClient.useSession.subscribe` appears in documentation, but does not exist expected: `authClient.useSession.subscribe` exists outside of Vue/React hook naming conventions, such as `authClient.subscribe`. ### What version of Better Auth are you using? 1.3.4 ### System info ```bash N/A ``` ### Which area(s) are affected? (Select all that apply) Client ### Auth config (if applicable) ```typescript ``` ### Additional context _No response_
GiteaMirror added the documentation label 2026-03-13 09:21:07 -05:00
GiteaMirror commented 2026-03-13 09:21:09 -05:00
Author
Owner
Copy Link
Copy Source

@dosubot[bot] commented on GitHub (Sep 24, 2025):

You're correct—the documentation example using authClient.useSession.subscribe is a mistake. That API does not exist at type or runtime in Better Auth v1.3.4, and the useSession function is a React/Vue hook, not an object with a subscribe method. There is currently no vanilla JS subscription API (like authClient.subscribe) for listening to session changes outside of hooks see discussion.

For synchronizing session state outside of React/Vue rendering (for example, into state management libraries), the recommended workaround is to use a bridge component or a custom context provider that listens to session changes via the hook and propagates updates to your state layer. You can see a detailed example of this approach in this issue.

As of v1.3.4, there is no evidence of a planned or available non-hook subscription API for session changes. If you need this feature for vanilla or non-framework usage, you may want to monitor the project for future updates.

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other  Chat with Dosu Join Discord Share on X

@dosubot[bot] commented on GitHub (Sep 24, 2025): <!-- Answer --> You're correct—the documentation example using `authClient.useSession.subscribe` is a mistake. That API does not exist at type or runtime in Better Auth v1.3.4, and the `useSession` function is a React/Vue hook, not an object with a `subscribe` method. There is currently no vanilla JS subscription API (like `authClient.subscribe`) for listening to session changes outside of hooks [see discussion](https://github.com/better-auth/better-auth/issues/4105). For synchronizing session state outside of React/Vue rendering (for example, into state management libraries), the recommended workaround is to use a bridge component or a custom context provider that listens to session changes via the hook and propagates updates to your state layer. You can see a detailed example of this approach in [this issue](https://github.com/better-auth/better-auth/issues/4609). As of v1.3.4, there is no evidence of a planned or available non-hook subscription API for session changes. If you need this feature for vanilla or non-framework usage, you may want to monitor the project for future updates. <!-- 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/c6b70867-d9c3-4720-939e-314fddecc1fd?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/c6b70867-d9c3-4720-939e-314fddecc1fd?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/c6b70867-d9c3-4720-939e-314fddecc1fd?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/c6b70867-d9c3-4720-939e-314fddecc1fd?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/c6b70867-d9c3-4720-939e-314fddecc1fd?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/c6b70867-d9c3-4720-939e-314fddecc1fd?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/c6b70867-d9c3-4720-939e-314fddecc1fd?feedback_type=other)</sup>&nbsp;&nbsp;[![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/cdda13d9-dd27-4d31-b09a-5d8bec92de21/ask?utm_source=github)&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/4879)
GiteaMirror commented 2026-03-13 09:21:09 -05:00
Author
Owner
Copy Link
Copy Source

@himself65 commented on GitHub (Sep 24, 2025):

It's there. Please note that you are looking at the Vanilla tab. not react

Image
@himself65 commented on GitHub (Sep 24, 2025): It's there. Please note that you are looking at the Vanilla tab. not react <img width="1136" height="577" alt="Image" src="https://github.com/user-attachments/assets/644e39fa-b50a-4a31-955c-fced6a48117a" />
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 labels documentation
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
GiteaMirror ninjasurge (Kaehlen Rog)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/better-auth#2014