feat(shared,nextjs,react): Introduce `useOAuthConsent` hook by jfoshee · Pull Request #8286 · clerk/javascript

jfoshee · 2026-04-10T19:58:52Z

Description

This PR introduces an internal (for now) useOAuthConsent() hook for fetching OAuth consent screen metadata for the signed-in user.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

changeset-bot · 2026-04-10T19:58:57Z

🦋 Changeset detected

Latest commit: 71ad9f6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 21 packages

Name	Type
@clerk/shared	Minor
@clerk/react	Minor
@clerk/nextjs	Minor
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-04-10T19:58:58Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Apr 11, 2026 3:06am

coderabbitai · 2026-04-10T21:09:48Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new useOAuthConsent React hook and its types to @clerk/shared, plus supporting utilities: readOAuthConsentFromSearch and useOAuthConsentCacheKeys, and a stable key OAUTH_CONSENT_INFO_KEY. The hook reads optional client_id/scope (with fallback to window.location.search), records telemetry, builds cache keys, and calls clerk.oauthApplication.getConsentInfo when enabled and a user is present. Exports of the hook were added to shared hooks index and re-exported from packages/react and packages/nextjs. Includes unit tests for the parser and hook behavior and a changeset declaring a minor release.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and accurately summarizes the main change: introducing the `useOAuthConsent` hook across three packages.
Description check	✅ Passed	The description is related to the changeset, explaining that the PR introduces an internal `useOAuthConsent()` hook for fetching OAuth consent metadata.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/shared/src/react/hooks/useOAuthConsent.tsx`:
- Around line 53-59: The hook accesses window.location.search unsafely in the
useOAuthConsent hook: update the initial state for searchSnapshot and the
useLayoutEffect so they only read window.location.search when window and
window.location exist (e.g. check typeof window !== 'undefined' &&
window.location) or use optional chaining (window?.location?.search) before
calling setSearchSnapshot; modify references to searchSnapshot/setSearchSnapshot
and the useLayoutEffect callback accordingly to avoid reads when location is
undefined (this prevents crashes in React Native/Expo).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: b1f703c3-9260-48ce-b420-5e1b7b372cea

📥 Commits

Reviewing files that changed from the base of the PR and between 68d1d8d and 7444213.

📒 Files selected for processing (12)

.changeset/oauth-consent-use-hook.md
packages/expo/src/hooks/index.ts
packages/nextjs/src/client-boundary/hooks.ts
packages/nextjs/src/index.ts
packages/react/src/hooks/index.ts
packages/shared/src/react/hooks/__tests__/useOAuthConsent.shared.spec.ts
packages/shared/src/react/hooks/__tests__/useOAuthConsent.spec.tsx
packages/shared/src/react/hooks/index.ts
packages/shared/src/react/hooks/useOAuthConsent.shared.ts
packages/shared/src/react/hooks/useOAuthConsent.tsx
packages/shared/src/react/hooks/useOAuthConsent.types.ts
packages/shared/src/react/stable-keys.ts

packages/shared/src/react/hooks/useOAuthConsent.tsx

jfoshee · 2026-04-10T20:05:29Z

packages/shared/src/react/hooks/useOAuthConsent.types.ts

+   * OAuth consent screen metadata from Clerk, or `undefined` before the first successful fetch.
+   * Additional fields (e.g. submission helpers) may be added in the future without renaming this hook.
+   */
+  data: OAuthConsentInfo | undefined;


Might I regret typing this as OAuthConsentInfo? If I need to add a member for e.g. post consent response endpoint? or a method?

Good instinct. Let's keep data as the raw FAPI response and put the submission helpers (even the submissionEndpoint property we talked about) at root level alongside data, similar to how other hooks return additional properties.

That way data stays a clean mirror of the API response, and hook utilities live at the top level

jfoshee · 2026-04-10T20:05:57Z

packages/shared/src/react/stable-keys.ts

 const ORGANIZATION_CREATION_DEFAULTS_KEY = 'organizationCreationDefaults';

+// Keys for `useOAuthConsent` (consent metadata GET; keep distinct from future submit/mutation keys)
+const OAUTH_CONSENT_INFO_KEY = 'oauthConsentInfo';


what are these keys for? Do I need to think about future members?

These are tanstack query cache keys. Every query-based hook needs a unique stable key for caching/invalidation.

Tbh we dont really need caching/invalidation here as the page gets visited only once by user, but since we are using our tanstack query wrapper internally, we need a cache key

jfoshee · 2026-04-10T20:06:12Z

packages/shared/src/react/hooks/useOAuthConsent.types.ts

+  /**
+   * Whether any request is still in flight, including background updates.
+   */
+  isFetching: boolean;


Do we need both isFetching and isLoading?

We need the isLoading here to check if the consent info is being fetched initially or not.

The isFetching is useless here as the page gets visited only once (this is for backgroudn fetches) but to follow existing hooks, we keep it for consistency

jfoshee · 2026-04-10T20:14:32Z

packages/shared/src/react/hooks/useOAuthConsent.types.ts

+   *
+   * @default true
+   */
+  keepPreviousData?: boolean;


do we need these?

To be consistent with other hooks, yes

jfoshee · 2026-04-10T20:19:18Z

packages/shared/src/react/hooks/useOAuthConsent.tsx

+    typeof window !== 'undefined' ? window.location.search : '',
+  );
+
+  useLayoutEffect(() => {


why not use useEffect here? 🤔

Agreed, useEffect would be fine here. But I think we can simplify further: the URL doesn't change after load (consent pages are full-navigation redirects), so we can drop the state + effect entirely and just read it once in a useMemo.

Also coderabbit flagged this for Expo users, I'll clean this up

jfoshee · 2026-04-10T20:20:39Z

packages/shared/src/react/hooks/useOAuthConsent.tsx

+    if (!getConsentInfo) {
+      return Promise.reject(new Error('OAuth consent is not available in this Clerk instance'));
+    }
+    const p: GetOAuthConsentInfoParams = scope !== undefined ? { oauthClientId, scope } : { oauthClientId };


note that scope is optional

jfoshee · 2026-04-10T22:14:40Z

packages/shared/src/react/hooks/useOAuthConsent.tsx

+  });
+
+  return {
+    data: query.data,


let's change data to consentInfo

After doing another review, I'd say we should keep data here. Every other useClerkQuery-based hook returns data, not a named field.

The hook name already tells us what data is here, which is the consent info, and consumers can always destructure as const { data: consentInfo } = useOAuthConsent() if they want a named variable.

wobsoriano · 2026-04-10T22:17:06Z

!snapshot

pkg-pr-new · 2026-04-10T22:20:06Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@8286

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8286

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8286

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8286

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8286

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8286

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8286

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8286

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8286

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8286

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8286

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8286

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8286

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8286

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8286

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8286

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8286

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8286

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8286

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8286

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8286

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8286

commit: 71ad9f6

wobsoriano

Looks good overall! Just pushed a few cleanup commits.

Let's also export it from react and nextjs /internal path until public release

wobsoriano · 2026-04-10T23:28:00Z

packages/shared/src/react/hooks/useOAuthConsent.tsx

+  });
+
+  return {
+    data: query.data,


After doing another review, I'd say we should keep data here. Every other useClerkQuery-based hook returns data, not a named field.

The hook name already tells us what data is here, which is the consent info, and consumers can always destructure as const { data: consentInfo } = useOAuthConsent() if they want a named variable.

wobsoriano · 2026-04-10T23:29:43Z

packages/shared/src/react/stable-keys.ts

 const ORGANIZATION_CREATION_DEFAULTS_KEY = 'organizationCreationDefaults';

+// Keys for `useOAuthConsent` (consent metadata GET; keep distinct from future submit/mutation keys)
+const OAUTH_CONSENT_INFO_KEY = 'oauthConsentInfo';


These are tanstack query cache keys. Every query-based hook needs a unique stable key for caching/invalidation.

Tbh we dont really need caching/invalidation here as the page gets visited only once by user, but since we are using our tanstack query wrapper internally, we need a cache key

wobsoriano · 2026-04-10T23:30:39Z

packages/shared/src/react/hooks/useOAuthConsent.tsx

+    typeof window !== 'undefined' ? window.location.search : '',
+  );
+
+  useLayoutEffect(() => {


Agreed, useEffect would be fine here. But I think we can simplify further: the URL doesn't change after load (consent pages are full-navigation redirects), so we can drop the state + effect entirely and just read it once in a useMemo.

Also coderabbit flagged this for Expo users, I'll clean this up

wobsoriano · 2026-04-10T23:34:22Z

packages/shared/src/react/hooks/useOAuthConsent.types.ts

+  /**
+   * Whether any request is still in flight, including background updates.
+   */
+  isFetching: boolean;


We need the isLoading here to check if the consent info is being fetched initially or not.

The isFetching is useless here as the page gets visited only once (this is for backgroudn fetches) but to follow existing hooks, we keep it for consistency

wobsoriano · 2026-04-10T23:36:47Z

packages/shared/src/react/hooks/useOAuthConsent.types.ts

+   * OAuth consent screen metadata from Clerk, or `undefined` before the first successful fetch.
+   * Additional fields (e.g. submission helpers) may be added in the future without renaming this hook.
+   */
+  data: OAuthConsentInfo | undefined;


Good instinct. Let's keep data as the raw FAPI response and put the submission helpers (even the submissionEndpoint property we talked about) at root level alongside data, similar to how other hooks return additional properties.

That way data stays a clean mirror of the API response, and hook utilities live at the top level

wobsoriano · 2026-04-10T23:37:44Z

packages/shared/src/react/hooks/useOAuthConsent.types.ts

+   *
+   * @default true
+   */
+  keepPreviousData?: boolean;


To be consistent with other hooks, yes

- Simplify search snapshot logic (remove useState + useLayoutEffect) - Extract fetchConsentInfo into standalone function - Gate placeholderData on queryEnabled - Mark hook and types as @internal - Export from @clerk/react/internal and @clerk/nextjs/internal - Update export snapshots and changeset

jfoshee added 2 commits April 10, 2026 14:17

feat(react): add useOAuthConsent hook

7aaf6ed

read scope and client_id from location search params

7444213

github-actions bot added nextjs react expo labels Apr 10, 2026

vercel bot deployed to Preview April 10, 2026 19:59 View deployment

jfoshee marked this pull request as ready for review April 10, 2026 21:04

coderabbitai bot reviewed Apr 10, 2026

View reviewed changes

packages/shared/src/react/hooks/useOAuthConsent.tsx Outdated Show resolved Hide resolved

jfoshee commented Apr 10, 2026

View reviewed changes

Merge branch 'main' into jfoshee/add-hook-use-oauth-consent

439b3b8

vercel bot deployed to Preview April 10, 2026 22:17 View deployment

chore: Clean up hook

7bf0994

vercel bot deployed to Preview April 10, 2026 23:52 View deployment

wobsoriano approved these changes Apr 10, 2026

View reviewed changes

Merge branch 'main' into jfoshee/add-hook-use-oauth-consent

26604b8

vercel bot deployed to Preview April 10, 2026 23:53 View deployment

github-actions bot added tanstack react-router labels Apr 11, 2026

vercel bot deployed to Preview April 11, 2026 00:04 View deployment

wobsoriano changed the title ~~feat(react): add useOAuthConsent hook~~ feat(shared): Introduce useOAuthConsent hook Apr 11, 2026

vercel bot temporarily deployed to Preview April 11, 2026 00:09 Inactive

vercel bot deployed to Preview April 11, 2026 00:12 View deployment

vercel bot temporarily deployed to Preview April 11, 2026 00:18 Inactive

wobsoriano removed nextjs react labels Apr 11, 2026

wobsoriano removed expo tanstack react-router labels Apr 11, 2026

github-actions bot added nextjs react labels Apr 11, 2026

wobsoriano changed the title ~~feat(shared): Introduce useOAuthConsent hook~~ feat(shared,nextjs,react): Introduce useOAuthConsent hook Apr 11, 2026

vercel bot deployed to Preview April 11, 2026 00:48 View deployment

vercel bot deployed to Preview April 11, 2026 00:49 View deployment

vercel bot deployed to Preview April 11, 2026 00:56 View deployment

clerk deleted a comment from github-actions bot Apr 11, 2026

vercel bot deployed to Preview April 11, 2026 01:03 View deployment

vercel bot deployed to Preview April 11, 2026 02:47 View deployment

wobsoriano force-pushed the jfoshee/add-hook-use-oauth-consent branch from 8393e6f to 844917f Compare April 11, 2026 02:51

vercel bot deployed to Preview April 11, 2026 02:52 View deployment

wobsoriano added 2 commits April 10, 2026 20:05

chore: fix jsdoc imports

9e8a4fe

Merge branch 'main' into jfoshee/add-hook-use-oauth-consent

71ad9f6

vercel bot deployed to Preview April 11, 2026 03:06 View deployment

wobsoriano merged commit f9ff9e9 into main Apr 11, 2026
42 checks passed

wobsoriano deleted the jfoshee/add-hook-use-oauth-consent branch April 11, 2026 03:15

clerk-cookie mentioned this pull request Apr 11, 2026

ci(repo): Version packages #8277

Open

Conversation

jfoshee commented Apr 10, 2026 • edited by wobsoriano Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

changeset-bot bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

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!

wobsoriano commented Apr 10, 2026

Uh oh!

pkg-pr-new bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wobsoriano left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

jfoshee commented Apr 10, 2026 •

edited by wobsoriano

Loading

changeset-bot bot commented Apr 10, 2026 •

edited

Loading

vercel bot commented Apr 10, 2026 •

edited

Loading

coderabbitai bot commented Apr 10, 2026 •

edited

Loading

pkg-pr-new bot commented Apr 10, 2026 •

edited

Loading

wobsoriano left a comment •

edited

Loading