feat(#964): Add Hooks provider by phoenix-ru · Pull Request #1062 · sidebase/nuxt-auth

phoenix-ru · 2025-10-17T14:59:35Z

🔗 Linked issue

Closes #964

❓ Type of change

📖 Documentation (updates to the documentation, readme or JSdoc annotations)
🐞 Bug fix (a non-breaking change that fixes an issue)
👌 Enhancement (improving an existing functionality like performance)
✨ New feature (a non-breaking change that adds functionality)
🧹 Chore (updates to the build process or auxiliary tools and libraries)
⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

📝 Checklist

I have linked an issue or discussion.
I have added tests (if possible).
I have updated the documentation accordingly.

pkg-pr-new · 2025-10-17T15:00:27Z

Open in StackBlitz

npm i https://pkg.pr.new/@sidebase/nuxt-auth@1062

commit: 62a5fc2

pkg-pr-new · 2025-10-17T15:00:27Z

Open in StackBlitz

npm i https://pkg.pr.new/@sidebase/nuxt-auth@1062

commit: 0c38105

docs: improve documentation

zoey-kaiser · 2026-04-24T14:26:35Z

+## `createRequest(data, authState, nuxt)`
+
+Prepare data for the fetch call.
+
+Must return either an object conforming to:
+
+```ts
+interface CreateRequestResult {
+  // Path to the endpoint
+  path: string
+  // Request: body, headers, etc.
+  request: NitroFetchOptions
+}
+```


Why did you decide to abstract the returns of the hooks provider? While I think it is a good step forward compared to the current local-provider I think it could still limit you if you e.g. want to switch from ofetch to axios under the hood.

I don't think it would ever make sense for us to switch the underlying fetch library to something outside Nuxt ecosystem. At the moment ofetch is the default library of Nuxt, therefore it is being used

zoey-kaiser · 2026-04-24T14:26:59Z

+### `authState` argument
+
+This argument gives you access to the state of the module, allowing to read or modify session data or tokens.


Do we have a schema for this or this is e.g. based off the session object you can provide via the nuxt config?

Yes, we do! I updated the documentation for it to point to useAuthState:

zoey-kaiser · 2026-04-24T14:28:17Z

+
+This argument gives you access to the state of the module, allowing to read or modify session data or tokens.
+
+### `nuxt` argument


Should we call this nuxtApp like Nuxt also does in the docs you linked below?

zoey-kaiser · 2026-04-24T14:29:02Z

+Handle the response and optionally instruct the module how to update state.
+
+May return:
+* `false` — stop further processing (module will not update auth state).


Does this false act the same way as the return false from the createRequest hook?

Yep, exactly the same - the meaning of false is to stop execution without an error

zoey-kaiser · 2026-04-24T14:29:41Z

+* `ResponseAccept` object — instruct the module what to set in `authState` (see below).
+* Throw an `Error` to propagate a failure.
+
+The `response` argument is the [`ofetch` raw response](https://github.com/unjs/ofetch?tab=readme-ov-file#-access-to-raw-response) that the module uses as well. `response._data` usually contains parsed body.


What else can response._data contain if not the parsed body? E.g. do we do error handling here or just return whatever was in the body?

We do error handling for the request:

nuxt-auth/src/runtime/composables/hooks/useAuth.ts

Lines 78 to 92 in c416c1e

let response: FetchResponse<T>

try {

response = await _fetchRaw<T>(nuxt, createRequestResult.path, createRequestResult.request)

}

catch (e) {

if (hooks.onError) {

await hooks.onError({

error: transformToError(e),

requestData: createRequestResult,

}, authState, nuxt)

}

// Do not proceed when error occurred

return

}

But thinking a bit more, we are silently consuming the error which is not very good for this usecase:

nuxt-auth/src/runtime/utils/fetch.ts

Lines 75 to 88 in c416c1e

catch (error) {

let errorMessage = `${ERROR_PREFIX} Error while requesting ${joinedPath}.`

if (runtimeConfig.public.auth.provider.type === 'authjs') {

errorMessage += ' Have you added the authentication handler server-endpoint `[...].ts`? Have you added the authentication handler in a non-default location (default is `~/server/api/auth/[...].ts`) and not updated the module-setting `auth.basePath`?'

}

errorMessage += ' Error is:'

console.error(errorMessage)

console.error(error)

throw new FetchConfigurationError(

'Runtime error, check the console logs to debug, open an issue at https://github.com/sidebase/nuxt-auth/issues/new/choose if you continue to have this problem'

)

}

}

It was done like so to avoid leaking exact error details (which might not be caught by consuming code and passed to the app side -> viewable by the frontend). I will consider if this could be improved, there's an external PR for better error handling:
#1069

zoey-kaiser · 2026-04-24T14:30:32Z

+    onResponse(response) {
+      // Backend returns { access: 'xxx', refresh: 'yyy', user: {...} }
+      const body = response._data
+      // Default to `undefined` to not reset the tokens and session (but you may want to reset it)
+      return {
+        token: body?.access ?? undefined,
+        refreshToken: body?.refresh ?? undefined,
+        session: body?.user ?? undefined,
+      }
+    },


Are these hooks promises? E.g. if I wanted to do another DB or API call here, would the hooks provider support this?

Yes, the hooks are awaitable:

nuxt-auth/src/runtime/composables/hooks/useAuth.ts

Line 94 in c416c1e

const signInResponseAccept = await Promise.resolve(hooks.onResponse(response, authState, nuxt))

zoey-kaiser · 2026-04-24T14:31:22Z

+      }
+    },
+
+    onResponse(response) {


If I return false from the getSession.createRequest hook is this response:

false

null / undefined

onResponse is never called

The onResponse is never called:

nuxt-auth/src/runtime/composables/hooks/useAuth.ts

Lines 73 to 76 in c416c1e

const createRequestResult = await Promise.resolve(hooks.createRequest({ credentials, options }, authState, nuxt))

if (createRequestResult === false) {

return

}

zoey-kaiser · 2026-04-24T14:32:47Z

+
+This argument gives you access to the state of the module, allowing to read or modify session data or tokens.
+
+### `nuxt` argument


Do we want to add a guide on how you can use this to e.g. access runtimeConfig variables? I think this could be a pretty common workflow.

Will do, thanks

feat(#964): implement hooks provider (WIP)

0c38105

BracketJohn mentioned this pull request Oct 24, 2025

RFC: Hooks for the local provider #964

Open

5 tasks

phoenix-ru added 2 commits November 5, 2025 14:26

feat: implement hooks for signOut

a1e73ce

docs: add documentation about Hooks provider

0b15c6f

bitfactory-frank-spee mentioned this pull request Nov 7, 2025

Prevent clear auth data when getSession error #763

Open

5 tasks

phoenix-ru and others added 9 commits December 18, 2025 10:28

Merge branch 'main' into feat/964-add-hooks-provider

37da522

feat: add hooks playground and refine implementation

591ecb0

chore: run lint fix

860d592

fix: fix typecheck

89c9d51

test: add CI for hooks provider

ac6b958

fix: fix signup in playground

454a698

enh: export defineHooksAdapter from module

7288895

test: fix signUp test

4422a44

chore: fix lint

e2bda57

phoenix-ru marked this pull request as ready for review December 18, 2025 17:24

phoenix-ru mentioned this pull request Dec 24, 2025

CORS error after upgrading from 1.1.0 to 1.1.1 #1070

Open

chore: resolve remaining TODOs

c416c1e

docs: improve documentation

phoenix-ru requested a review from zoey-kaiser January 15, 2026 12:12

This was referenced Jan 30, 2026

User gets logged out when the user endpoint encounters any kind of error (Not just 401) #998

Open

Maybe this is a little thing for getting user informations inside getSession function. #699

Closed

phoenix-ru mentioned this pull request Mar 26, 2026

fix(#947): only call refresh when auth token is expired #1087

Merged

9 tasks

zoey-kaiser reviewed Apr 24, 2026

View reviewed changes

phoenix-ru added 3 commits June 26, 2026 18:02

enh: add extraCtx support

136c4d7

docs: improve the documentation

bc9c505

chore: change function ordering

62a5fc2

		### `authState` argument

		This argument gives you access to the state of the module, allowing to read or modify session data or tokens.


		This argument gives you access to the state of the module, allowing to read or modify session data or tokens.

		### `nuxt` argument

	let response: FetchResponse<T>
	try {
	response = await _fetchRaw<T>(nuxt, createRequestResult.path, createRequestResult.request)
	}
	catch (e) {
	if (hooks.onError) {
	await hooks.onError({
	error: transformToError(e),
	requestData: createRequestResult,
	}, authState, nuxt)
	}

	// Do not proceed when error occurred
	return
	}

	catch (error) {
	let errorMessage = `${ERROR_PREFIX} Error while requesting ${joinedPath}.`
	if (runtimeConfig.public.auth.provider.type === 'authjs') {
	errorMessage += ' Have you added the authentication handler server-endpoint `[...].ts`? Have you added the authentication handler in a non-default location (default is `~/server/api/auth/[...].ts`) and not updated the module-setting `auth.basePath`?'
	}
	errorMessage += ' Error is:'
	console.error(errorMessage)
	console.error(error)

	throw new FetchConfigurationError(
	'Runtime error, check the console logs to debug, open an issue at https://github.com/sidebase/nuxt-auth/issues/new/choose if you continue to have this problem'
	)
	}
	}

	const createRequestResult = await Promise.resolve(hooks.createRequest({ credentials, options }, authState, nuxt))
	if (createRequestResult === false) {
	return
	}

Uh oh!

Uh oh!

Conversation

phoenix-ru commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Linked issue

❓ Type of change

📚 Description

📝 Checklist

Uh oh!

pkg-pr-new Bot commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Oct 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

phoenix-ru commented Oct 17, 2025 •

edited

Loading

pkg-pr-new Bot commented Oct 17, 2025 •

edited

Loading