fix(shared): drop docsUrl for Enstall OAuth provider

[SarahSoutoul]

This PR is paired with a dashboard PR.

Problem

The JS SDK was shipping a docsUrl for Enstall that points to a docs page that does not exist: https://clerk.com/docs/authentication/social-connections/enstall. That link surfaces to end users as a 404.

Enstall is a private, single-customer OIDC provider rather than a general public social connection, so we should not ship a public docs link for it.

This PR removes the public docsUrl for the Enstall OAuth provider from clerk/javascript.

Changes

• Made docsUrl optional on OAuthProviderData
• Removed docsUrl from the Enstall provider entry in:
  • packages/shared/src/oauth.ts
  • packages/shared/src/types/runtime-values.ts
• Audited current shared/UI consumers in this repo and did not find any UI surface that assumes docsUrl is always present for OAuth providers

Notes

• This is the SDK-side follow-up only for Enstall.
• The long-lived docs redirect added here still needs to remain in clerk-docs for already-shipped SDK versions that still contain the old URL

Summary by CodeRabbit

Summary by CodeRabbit

• Bug Fixes

  • OAuth provider docsUrl is now optional, allowing provider metadata without documentation links.
  • Removed the documentation URL for the Enstall OAuth provider so it no longer returns docsUrl in its provider data.

• Release Management

  • Updated the package changeset to publish a patch/minor version bump for @clerk/shared.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3c3f1af

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Minor
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 23, 2026 3:10pm
swingset	Ready	Preview, Comment	Jun 23, 2026 3:10pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 83a2cf87-9c7f-47ca-825a-aaeae2d39229

📥 Commits

Reviewing files that changed from the base of the PR and between 9d861e8 and 2ac22ef.

📒 Files selected for processing (1)

• .changeset/curly-roses-yawn.md

✅ Files skipped from review due to trivial changes (1)

• .changeset/curly-roses-yawn.md

---

📝 Walkthrough

Walkthrough

OAuthProviderData.docsUrl is changed from a required to an optional field. The enstall OAuth provider entry has its docsUrl property removed in both packages/shared/src/oauth.ts and packages/shared/src/types/runtime-values.ts. Changesets are added for @clerk/shared documenting the API adjustment.

Changes

OAuthProviderData.docsUrl optionality and enstall data update

Layer / File(s)	Summary
Make docsUrl optional and remove enstall docsUrl packages/shared/src/types/oauth.ts, packages/shared/src/oauth.ts, packages/shared/src/types/runtime-values.ts, .changeset/fresh-lies-film.md, .changeset/curly-roses-yawn.md	docsUrl is marked optional on OAuthProviderData; the enstall provider entry drops its docsUrl property from both OAUTH_PROVIDERS arrays; changesets document the API adjustment.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 A URL once required, now set free,
The enstall provider travels light, you see.
No docs link to carry, no string to bind,
Optional and nimble — what a find!
Hop along, little patch, you're just fine! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: removing the docsUrl field for the Enstall OAuth provider, which is the core focus of the pull request across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@8885

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@8885

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@8885

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 3c3f1af

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/shared/src/types/oauth.ts (1)

5-10: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add JSDoc to document the public OAuthProviderData interface.

The OAuthProviderData interface is a public, reference-facing API exported from @clerk/shared that will appear in generated customer documentation. Per the coding guidelines for packages/**/src/**/*.ts files, all public APIs must be documented with comprehensive JSDoc comments.

This interface lacks documentation explaining:

• The purpose of the interface (OAuth provider configuration metadata)
• Each property and its role
• That docsUrl is now optional (not all providers have public documentation)

This is especially important since this PR changes the API surface by making docsUrl optional—customers using this interface need clear documentation of the change.

📝 Suggested JSDoc for OAuthProviderData

 import type { OAuthStrategy } from './strategies';
export type OAuthScope = string;
+/**+ * Represents the configuration metadata for an OAuth provider.+ * + * This interface defines the structure of OAuth provider entries used by Clerk's OAuth integration layer.+ * Each provider has a unique identifier, associated strategy, and optional documentation link.+ * + * `@property` provider - The unique provider identifier (e.g., 'google', 'github', 'enstall')+ * `@property` strategy - The OAuth strategy name for this provider+ * `@property` name - Human-readable display name of the provider+ * `@property` docsUrl - Optional URL to the provider's documentation. Not all providers expose public documentation.+ */
export interface OAuthProviderData {
provider: OAuthProvider;
strategy: OAuthStrategy;
name: string;
docsUrl?: string;
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/shared/src/types/oauth.ts` around lines 5 - 10, The public
OAuthProviderData interface is missing JSDoc documentation required for all
public APIs in packages/shared. Add a comprehensive JSDoc comment block above
the interface definition that explains: the purpose of the interface as OAuth
provider configuration metadata, the role of each property (provider, strategy,
name, and docsUrl), and specifically document that docsUrl is optional since not
all providers have public documentation. This ensures the interface is properly
documented for generated customer documentation and clarifies the API surface
change.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@packages/shared/src/types/oauth.ts`:
- Around line 5-10: The public OAuthProviderData interface is missing JSDoc
documentation required for all public APIs in packages/shared. Add a
comprehensive JSDoc comment block above the interface definition that explains:
the purpose of the interface as OAuth provider configuration metadata, the role
of each property (provider, strategy, name, and docsUrl), and specifically
document that docsUrl is optional since not all providers have public
documentation. This ensures the interface is properly documented for generated
customer documentation and clarifies the API surface change.

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 936623be-bf17-4884-ae4f-fe84ff5cda43

📥 Commits

Reviewing files that changed from the base of the PR and between d97a887 and 9d861e8.

📒 Files selected for processing (4)

• .changeset/fresh-lies-film.md
• packages/shared/src/oauth.ts
• packages/shared/src/types/oauth.ts
• packages/shared/src/types/runtime-values.ts

💤 Files with no reviewable changes (2)

• packages/shared/src/oauth.ts
• packages/shared/src/types/runtime-values.ts

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-23T15:11:19.996Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	1
🟡 Non-breaking changes	0
🟢 Additions	0

Warning
1 breaking change(s) detected - Major version bump required

🤖 This report was reviewed by claude-sonnet-4-6.

🔴 Breaking changes index (1)

Every breaking change, up front. Full diffs are in the package sections below.

Package	Subpath	Change
@clerk/shared	./types	OAuthProviderData.docsUrl

---

@clerk/shared

Current version: 4.20.0
Recommended bump: MAJOR → 5.0.0

Subpath ./types

🔴 Breaking Changes (1)

Changed: OAuthProviderData.docsUrl

- docsUrl: string;+ docsUrl?: string;

Static analyzer: Modified property OAuthProviderData.docsUrl: Member became optional

🤖 AI review (reclassified as breaking) (85%): Making an existing output field optional is breaking (rule 4): consumers reading docsUrl from an OAuthProviderData object previously had a guaranteed string but now receive string | undefined, requiring them to add a null check or their existing code may break at runtime.

Migration: Update any code that reads OAuthProviderData.docsUrl to handle the undefined case, e.g. providerData.docsUrl ?? ''.

---

Report generated by Break Check

_{Last ran on 3c3f1af.}

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

[wobsoriano]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

[manovotny]

I ran a full org-wide sweep of docsUrl / OAUTH_PROVIDERS consumers (in-repo + gh search code --owner clerk), and there is the one spot worth a second look — everything appears safe.

clerk/cli reads OAUTH_PROVIDERS[].docsUrl but defensively (?.docsUrl ?? fallback), and the in-repo UI consumers only read .strategy/.provider/.name, never .docsUrl, so we're good here.

The tricky one is clerk/dashboard. Its getSocialSettings.ts imports OAUTH_PROVIDERS from @clerk/shared/oauth and reads item.docsUrl with a name-based fallback:

item.docsUrl??`https://clerk.com/docs/guides/configure/auth-strategies/social-connections/${item.provider}`

Then, it renders that as the provider's docs link on the SSO connection page.

With docsUrl gone, Enstall falls through to …/guides/configure/auth-strategies/social-connections/enstall, which currently 404s — whereas the URL being removed here 308-redirects to the live social-connections overview (via the redirect added in clerk-docs#3391). So on the Enstall-enabled instance, this swaps a working (redirected) link for a hard 404 on the surface that actually renders it.

Since the dashboard is what surfaces this link, should we pair this with a dashboard change that drops the link when docsUrl is absent (or skips the fallback for private providers), or add a clerk-docs redirect for the new …/auth-strategies/social-connections/enstall path so the fallback resolves?

[SarahSoutoul]

Nice catch! Made a sibling dashboard PR. @manovotny

[SarahSoutoul]

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

Makes sense! But I should prob make it a major bump then? @wobsoriano

[manovotny]

I am good with the changes here and in https://github.com/clerk/dashboard/pull/9497 (this PR needs to land first).

I would appreciate another set of eyes and approval before merge to ensure we're not overlooking anything else.

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.
Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

@jacekradko@wobsoriano could I follow up on this?

[wobsoriano]

Given that this is internal, we can disregard the API breaking change break check 👍🏼

[SarahSoutoul]

This PR is paired with a dashboard PR.

Problem

The JS SDK was shipping a docsUrl for Enstall that points to a docs page that does not exist: https://clerk.com/docs/authentication/social-connections/enstall. That link surfaces to end users as a 404.

Enstall is a private, single-customer OIDC provider rather than a general public social connection, so we should not ship a public docs link for it.

This PR removes the public docsUrl for the Enstall OAuth provider from clerk/javascript.

Changes

• Made docsUrl optional on OAuthProviderData
• Removed docsUrl from the Enstall provider entry in:
  • packages/shared/src/oauth.ts
  • packages/shared/src/types/runtime-values.ts
• Audited current shared/UI consumers in this repo and did not find any UI surface that assumes docsUrl is always present for OAuth providers

Notes

• This is the SDK-side follow-up only for Enstall.
• The long-lived docs redirect added here still needs to remain in clerk-docs for already-shipped SDK versions that still contain the old URL

Summary by CodeRabbit

Summary by CodeRabbit

• Bug Fixes

  • OAuth provider docsUrl is now optional, allowing provider metadata without documentation links.
  • Removed the documentation URL for the Enstall OAuth provider so it no longer returns docsUrl in its provider data.

• Release Management

  • Updated the package changeset to publish a patch/minor version bump for @clerk/shared.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3c3f1af

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Minor
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 23, 2026 3:10pm
swingset	Ready	Preview, Comment	Jun 23, 2026 3:10pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 83a2cf87-9c7f-47ca-825a-aaeae2d39229

📥 Commits

Reviewing files that changed from the base of the PR and between 9d861e8 and 2ac22ef.

📒 Files selected for processing (1)

• .changeset/curly-roses-yawn.md

✅ Files skipped from review due to trivial changes (1)

• .changeset/curly-roses-yawn.md

---

📝 Walkthrough

Walkthrough

OAuthProviderData.docsUrl is changed from a required to an optional field. The enstall OAuth provider entry has its docsUrl property removed in both packages/shared/src/oauth.ts and packages/shared/src/types/runtime-values.ts. Changesets are added for @clerk/shared documenting the API adjustment.

Changes

OAuthProviderData.docsUrl optionality and enstall data update

Layer / File(s)	Summary
Make docsUrl optional and remove enstall docsUrl packages/shared/src/types/oauth.ts, packages/shared/src/oauth.ts, packages/shared/src/types/runtime-values.ts, .changeset/fresh-lies-film.md, .changeset/curly-roses-yawn.md	docsUrl is marked optional on OAuthProviderData; the enstall provider entry drops its docsUrl property from both OAUTH_PROVIDERS arrays; changesets document the API adjustment.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 A URL once required, now set free,
The enstall provider travels light, you see.
No docs link to carry, no string to bind,
Optional and nimble — what a find!
Hop along, little patch, you're just fine! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: removing the docsUrl field for the Enstall OAuth provider, which is the core focus of the pull request across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@8885

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@8885

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@8885

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 3c3f1af

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/shared/src/types/oauth.ts (1)

5-10: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add JSDoc to document the public OAuthProviderData interface.

The OAuthProviderData interface is a public, reference-facing API exported from @clerk/shared that will appear in generated customer documentation. Per the coding guidelines for packages/**/src/**/*.ts files, all public APIs must be documented with comprehensive JSDoc comments.

This interface lacks documentation explaining:

• The purpose of the interface (OAuth provider configuration metadata)
• Each property and its role
• That docsUrl is now optional (not all providers have public documentation)

This is especially important since this PR changes the API surface by making docsUrl optional—customers using this interface need clear documentation of the change.

📝 Suggested JSDoc for OAuthProviderData

 import type { OAuthStrategy } from './strategies';
export type OAuthScope = string;
+/**+ * Represents the configuration metadata for an OAuth provider.+ * + * This interface defines the structure of OAuth provider entries used by Clerk's OAuth integration layer.+ * Each provider has a unique identifier, associated strategy, and optional documentation link.+ * + * `@property` provider - The unique provider identifier (e.g., 'google', 'github', 'enstall')+ * `@property` strategy - The OAuth strategy name for this provider+ * `@property` name - Human-readable display name of the provider+ * `@property` docsUrl - Optional URL to the provider's documentation. Not all providers expose public documentation.+ */
export interface OAuthProviderData {
provider: OAuthProvider;
strategy: OAuthStrategy;
name: string;
docsUrl?: string;
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/shared/src/types/oauth.ts` around lines 5 - 10, The public
OAuthProviderData interface is missing JSDoc documentation required for all
public APIs in packages/shared. Add a comprehensive JSDoc comment block above
the interface definition that explains: the purpose of the interface as OAuth
provider configuration metadata, the role of each property (provider, strategy,
name, and docsUrl), and specifically document that docsUrl is optional since not
all providers have public documentation. This ensures the interface is properly
documented for generated customer documentation and clarifies the API surface
change.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@packages/shared/src/types/oauth.ts`:
- Around line 5-10: The public OAuthProviderData interface is missing JSDoc
documentation required for all public APIs in packages/shared. Add a
comprehensive JSDoc comment block above the interface definition that explains:
the purpose of the interface as OAuth provider configuration metadata, the role
of each property (provider, strategy, name, and docsUrl), and specifically
document that docsUrl is optional since not all providers have public
documentation. This ensures the interface is properly documented for generated
customer documentation and clarifies the API surface change.

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 936623be-bf17-4884-ae4f-fe84ff5cda43

📥 Commits

Reviewing files that changed from the base of the PR and between d97a887 and 9d861e8.

📒 Files selected for processing (4)

• .changeset/fresh-lies-film.md
• packages/shared/src/oauth.ts
• packages/shared/src/types/oauth.ts
• packages/shared/src/types/runtime-values.ts

💤 Files with no reviewable changes (2)

• packages/shared/src/oauth.ts
• packages/shared/src/types/runtime-values.ts

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-23T15:11:19.996Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	1
🟡 Non-breaking changes	0
🟢 Additions	0

Warning
1 breaking change(s) detected - Major version bump required

🤖 This report was reviewed by claude-sonnet-4-6.

🔴 Breaking changes index (1)

Every breaking change, up front. Full diffs are in the package sections below.

Package	Subpath	Change
@clerk/shared	./types	OAuthProviderData.docsUrl

---

@clerk/shared

Current version: 4.20.0
Recommended bump: MAJOR → 5.0.0

Subpath ./types

🔴 Breaking Changes (1)

Changed: OAuthProviderData.docsUrl

- docsUrl: string;+ docsUrl?: string;

Static analyzer: Modified property OAuthProviderData.docsUrl: Member became optional

🤖 AI review (reclassified as breaking) (85%): Making an existing output field optional is breaking (rule 4): consumers reading docsUrl from an OAuthProviderData object previously had a guaranteed string but now receive string | undefined, requiring them to add a null check or their existing code may break at runtime.

Migration: Update any code that reads OAuthProviderData.docsUrl to handle the undefined case, e.g. providerData.docsUrl ?? ''.

---

Report generated by Break Check

_{Last ran on 3c3f1af.}

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

[wobsoriano]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

[manovotny]

I ran a full org-wide sweep of docsUrl / OAUTH_PROVIDERS consumers (in-repo + gh search code --owner clerk), and there is the one spot worth a second look — everything appears safe.

clerk/cli reads OAUTH_PROVIDERS[].docsUrl but defensively (?.docsUrl ?? fallback), and the in-repo UI consumers only read .strategy/.provider/.name, never .docsUrl, so we're good here.

The tricky one is clerk/dashboard. Its getSocialSettings.ts imports OAUTH_PROVIDERS from @clerk/shared/oauth and reads item.docsUrl with a name-based fallback:

item.docsUrl??`https://clerk.com/docs/guides/configure/auth-strategies/social-connections/${item.provider}`

Then, it renders that as the provider's docs link on the SSO connection page.

With docsUrl gone, Enstall falls through to …/guides/configure/auth-strategies/social-connections/enstall, which currently 404s — whereas the URL being removed here 308-redirects to the live social-connections overview (via the redirect added in clerk-docs#3391). So on the Enstall-enabled instance, this swaps a working (redirected) link for a hard 404 on the surface that actually renders it.

Since the dashboard is what surfaces this link, should we pair this with a dashboard change that drops the link when docsUrl is absent (or skips the fallback for private providers), or add a clerk-docs redirect for the new …/auth-strategies/social-connections/enstall path so the fallback resolves?

[SarahSoutoul]

Nice catch! Made a sibling dashboard PR. @manovotny

[SarahSoutoul]

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

Makes sense! But I should prob make it a major bump then? @wobsoriano

[manovotny]

I am good with the changes here and in https://github.com/clerk/dashboard/pull/9497 (this PR needs to land first).

I would appreciate another set of eyes and approval before merge to ensure we're not overlooking anything else.

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.
Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

@jacekradko@wobsoriano could I follow up on this?

[wobsoriano]

Given that this is internal, we can disregard the API breaking change break check 👍🏼

[SarahSoutoul]

This PR is paired with a dashboard PR.

Problem

The JS SDK was shipping a docsUrl for Enstall that points to a docs page that does not exist: https://clerk.com/docs/authentication/social-connections/enstall. That link surfaces to end users as a 404.

Enstall is a private, single-customer OIDC provider rather than a general public social connection, so we should not ship a public docs link for it.

This PR removes the public docsUrl for the Enstall OAuth provider from clerk/javascript.

Changes

• Made docsUrl optional on OAuthProviderData
• Removed docsUrl from the Enstall provider entry in:
  • packages/shared/src/oauth.ts
  • packages/shared/src/types/runtime-values.ts
• Audited current shared/UI consumers in this repo and did not find any UI surface that assumes docsUrl is always present for OAuth providers

Notes

• This is the SDK-side follow-up only for Enstall.
• The long-lived docs redirect added here still needs to remain in clerk-docs for already-shipped SDK versions that still contain the old URL

Summary by CodeRabbit

Summary by CodeRabbit

• Bug Fixes

  • OAuth provider docsUrl is now optional, allowing provider metadata without documentation links.
  • Removed the documentation URL for the Enstall OAuth provider so it no longer returns docsUrl in its provider data.

• Release Management

  • Updated the package changeset to publish a patch/minor version bump for @clerk/shared.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3c3f1af

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Minor
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 23, 2026 3:10pm
swingset	Ready	Preview, Comment	Jun 23, 2026 3:10pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 83a2cf87-9c7f-47ca-825a-aaeae2d39229

📥 Commits

Reviewing files that changed from the base of the PR and between 9d861e8 and 2ac22ef.

📒 Files selected for processing (1)

• .changeset/curly-roses-yawn.md

✅ Files skipped from review due to trivial changes (1)

• .changeset/curly-roses-yawn.md

---

📝 Walkthrough

Walkthrough

OAuthProviderData.docsUrl is changed from a required to an optional field. The enstall OAuth provider entry has its docsUrl property removed in both packages/shared/src/oauth.ts and packages/shared/src/types/runtime-values.ts. Changesets are added for @clerk/shared documenting the API adjustment.

Changes

OAuthProviderData.docsUrl optionality and enstall data update

Layer / File(s)	Summary
Make docsUrl optional and remove enstall docsUrl packages/shared/src/types/oauth.ts, packages/shared/src/oauth.ts, packages/shared/src/types/runtime-values.ts, .changeset/fresh-lies-film.md, .changeset/curly-roses-yawn.md	docsUrl is marked optional on OAuthProviderData; the enstall provider entry drops its docsUrl property from both OAUTH_PROVIDERS arrays; changesets document the API adjustment.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 A URL once required, now set free,
The enstall provider travels light, you see.
No docs link to carry, no string to bind,
Optional and nimble — what a find!
Hop along, little patch, you're just fine! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: removing the docsUrl field for the Enstall OAuth provider, which is the core focus of the pull request across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@8885

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@8885

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@8885

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 3c3f1af

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/shared/src/types/oauth.ts (1)

5-10: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add JSDoc to document the public OAuthProviderData interface.

The OAuthProviderData interface is a public, reference-facing API exported from @clerk/shared that will appear in generated customer documentation. Per the coding guidelines for packages/**/src/**/*.ts files, all public APIs must be documented with comprehensive JSDoc comments.

This interface lacks documentation explaining:

• The purpose of the interface (OAuth provider configuration metadata)
• Each property and its role
• That docsUrl is now optional (not all providers have public documentation)

This is especially important since this PR changes the API surface by making docsUrl optional—customers using this interface need clear documentation of the change.

📝 Suggested JSDoc for OAuthProviderData

 import type { OAuthStrategy } from './strategies';
export type OAuthScope = string;
+/**+ * Represents the configuration metadata for an OAuth provider.+ * + * This interface defines the structure of OAuth provider entries used by Clerk's OAuth integration layer.+ * Each provider has a unique identifier, associated strategy, and optional documentation link.+ * + * `@property` provider - The unique provider identifier (e.g., 'google', 'github', 'enstall')+ * `@property` strategy - The OAuth strategy name for this provider+ * `@property` name - Human-readable display name of the provider+ * `@property` docsUrl - Optional URL to the provider's documentation. Not all providers expose public documentation.+ */
export interface OAuthProviderData {
provider: OAuthProvider;
strategy: OAuthStrategy;
name: string;
docsUrl?: string;
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/shared/src/types/oauth.ts` around lines 5 - 10, The public
OAuthProviderData interface is missing JSDoc documentation required for all
public APIs in packages/shared. Add a comprehensive JSDoc comment block above
the interface definition that explains: the purpose of the interface as OAuth
provider configuration metadata, the role of each property (provider, strategy,
name, and docsUrl), and specifically document that docsUrl is optional since not
all providers have public documentation. This ensures the interface is properly
documented for generated customer documentation and clarifies the API surface
change.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@packages/shared/src/types/oauth.ts`:
- Around line 5-10: The public OAuthProviderData interface is missing JSDoc
documentation required for all public APIs in packages/shared. Add a
comprehensive JSDoc comment block above the interface definition that explains:
the purpose of the interface as OAuth provider configuration metadata, the role
of each property (provider, strategy, name, and docsUrl), and specifically
document that docsUrl is optional since not all providers have public
documentation. This ensures the interface is properly documented for generated
customer documentation and clarifies the API surface change.

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 936623be-bf17-4884-ae4f-fe84ff5cda43

📥 Commits

Reviewing files that changed from the base of the PR and between d97a887 and 9d861e8.

📒 Files selected for processing (4)

• .changeset/fresh-lies-film.md
• packages/shared/src/oauth.ts
• packages/shared/src/types/oauth.ts
• packages/shared/src/types/runtime-values.ts

💤 Files with no reviewable changes (2)

• packages/shared/src/oauth.ts
• packages/shared/src/types/runtime-values.ts

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-23T15:11:19.996Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	1
🟡 Non-breaking changes	0
🟢 Additions	0

Warning
1 breaking change(s) detected - Major version bump required

🤖 This report was reviewed by claude-sonnet-4-6.

🔴 Breaking changes index (1)

Every breaking change, up front. Full diffs are in the package sections below.

Package	Subpath	Change
@clerk/shared	./types	OAuthProviderData.docsUrl

---

@clerk/shared

Current version: 4.20.0
Recommended bump: MAJOR → 5.0.0

Subpath ./types

🔴 Breaking Changes (1)

Changed: OAuthProviderData.docsUrl

- docsUrl: string;+ docsUrl?: string;

Static analyzer: Modified property OAuthProviderData.docsUrl: Member became optional

🤖 AI review (reclassified as breaking) (85%): Making an existing output field optional is breaking (rule 4): consumers reading docsUrl from an OAuthProviderData object previously had a guaranteed string but now receive string | undefined, requiring them to add a null check or their existing code may break at runtime.

Migration: Update any code that reads OAuthProviderData.docsUrl to handle the undefined case, e.g. providerData.docsUrl ?? ''.

---

Report generated by Break Check

_{Last ran on 3c3f1af.}

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

[wobsoriano]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

[manovotny]

I ran a full org-wide sweep of docsUrl / OAUTH_PROVIDERS consumers (in-repo + gh search code --owner clerk), and there is the one spot worth a second look — everything appears safe.

clerk/cli reads OAUTH_PROVIDERS[].docsUrl but defensively (?.docsUrl ?? fallback), and the in-repo UI consumers only read .strategy/.provider/.name, never .docsUrl, so we're good here.

The tricky one is clerk/dashboard. Its getSocialSettings.ts imports OAUTH_PROVIDERS from @clerk/shared/oauth and reads item.docsUrl with a name-based fallback:

item.docsUrl??`https://clerk.com/docs/guides/configure/auth-strategies/social-connections/${item.provider}`

Then, it renders that as the provider's docs link on the SSO connection page.

With docsUrl gone, Enstall falls through to …/guides/configure/auth-strategies/social-connections/enstall, which currently 404s — whereas the URL being removed here 308-redirects to the live social-connections overview (via the redirect added in clerk-docs#3391). So on the Enstall-enabled instance, this swaps a working (redirected) link for a hard 404 on the surface that actually renders it.

Since the dashboard is what surfaces this link, should we pair this with a dashboard change that drops the link when docsUrl is absent (or skips the fallback for private providers), or add a clerk-docs redirect for the new …/auth-strategies/social-connections/enstall path so the fallback resolves?

[SarahSoutoul]

Nice catch! Made a sibling dashboard PR. @manovotny

[SarahSoutoul]

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

Makes sense! But I should prob make it a major bump then? @wobsoriano

[manovotny]

I am good with the changes here and in https://github.com/clerk/dashboard/pull/9497 (this PR needs to land first).

I would appreciate another set of eyes and approval before merge to ensure we're not overlooking anything else.

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.
Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

@jacekradko@wobsoriano could I follow up on this?

[wobsoriano]

Given that this is internal, we can disregard the API breaking change break check 👍🏼

[SarahSoutoul]

This PR is paired with a dashboard PR.

Problem

The JS SDK was shipping a docsUrl for Enstall that points to a docs page that does not exist: https://clerk.com/docs/authentication/social-connections/enstall. That link surfaces to end users as a 404.

Enstall is a private, single-customer OIDC provider rather than a general public social connection, so we should not ship a public docs link for it.

This PR removes the public docsUrl for the Enstall OAuth provider from clerk/javascript.

Changes

• Made docsUrl optional on OAuthProviderData
• Removed docsUrl from the Enstall provider entry in:
  • packages/shared/src/oauth.ts
  • packages/shared/src/types/runtime-values.ts
• Audited current shared/UI consumers in this repo and did not find any UI surface that assumes docsUrl is always present for OAuth providers

Notes

• This is the SDK-side follow-up only for Enstall.
• The long-lived docs redirect added here still needs to remain in clerk-docs for already-shipped SDK versions that still contain the old URL

Summary by CodeRabbit

Summary by CodeRabbit

• Bug Fixes

  • OAuth provider docsUrl is now optional, allowing provider metadata without documentation links.
  • Removed the documentation URL for the Enstall OAuth provider so it no longer returns docsUrl in its provider data.

• Release Management

  • Updated the package changeset to publish a patch/minor version bump for @clerk/shared.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3c3f1af

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Minor
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 23, 2026 3:10pm
swingset	Ready	Preview, Comment	Jun 23, 2026 3:10pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 83a2cf87-9c7f-47ca-825a-aaeae2d39229

📥 Commits

Reviewing files that changed from the base of the PR and between 9d861e8 and 2ac22ef.

📒 Files selected for processing (1)

• .changeset/curly-roses-yawn.md

✅ Files skipped from review due to trivial changes (1)

• .changeset/curly-roses-yawn.md

---

📝 Walkthrough

Walkthrough

OAuthProviderData.docsUrl is changed from a required to an optional field. The enstall OAuth provider entry has its docsUrl property removed in both packages/shared/src/oauth.ts and packages/shared/src/types/runtime-values.ts. Changesets are added for @clerk/shared documenting the API adjustment.

Changes

OAuthProviderData.docsUrl optionality and enstall data update

Layer / File(s)	Summary
Make docsUrl optional and remove enstall docsUrl packages/shared/src/types/oauth.ts, packages/shared/src/oauth.ts, packages/shared/src/types/runtime-values.ts, .changeset/fresh-lies-film.md, .changeset/curly-roses-yawn.md	docsUrl is marked optional on OAuthProviderData; the enstall provider entry drops its docsUrl property from both OAUTH_PROVIDERS arrays; changesets document the API adjustment.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 A URL once required, now set free,
The enstall provider travels light, you see.
No docs link to carry, no string to bind,
Optional and nimble — what a find!
Hop along, little patch, you're just fine! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: removing the docsUrl field for the Enstall OAuth provider, which is the core focus of the pull request across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@8885

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@8885

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@8885

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 3c3f1af

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/shared/src/types/oauth.ts (1)

5-10: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add JSDoc to document the public OAuthProviderData interface.

The OAuthProviderData interface is a public, reference-facing API exported from @clerk/shared that will appear in generated customer documentation. Per the coding guidelines for packages/**/src/**/*.ts files, all public APIs must be documented with comprehensive JSDoc comments.

This interface lacks documentation explaining:

• The purpose of the interface (OAuth provider configuration metadata)
• Each property and its role
• That docsUrl is now optional (not all providers have public documentation)

This is especially important since this PR changes the API surface by making docsUrl optional—customers using this interface need clear documentation of the change.

📝 Suggested JSDoc for OAuthProviderData

 import type { OAuthStrategy } from './strategies';
export type OAuthScope = string;
+/**+ * Represents the configuration metadata for an OAuth provider.+ * + * This interface defines the structure of OAuth provider entries used by Clerk's OAuth integration layer.+ * Each provider has a unique identifier, associated strategy, and optional documentation link.+ * + * `@property` provider - The unique provider identifier (e.g., 'google', 'github', 'enstall')+ * `@property` strategy - The OAuth strategy name for this provider+ * `@property` name - Human-readable display name of the provider+ * `@property` docsUrl - Optional URL to the provider's documentation. Not all providers expose public documentation.+ */
export interface OAuthProviderData {
provider: OAuthProvider;
strategy: OAuthStrategy;
name: string;
docsUrl?: string;
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/shared/src/types/oauth.ts` around lines 5 - 10, The public
OAuthProviderData interface is missing JSDoc documentation required for all
public APIs in packages/shared. Add a comprehensive JSDoc comment block above
the interface definition that explains: the purpose of the interface as OAuth
provider configuration metadata, the role of each property (provider, strategy,
name, and docsUrl), and specifically document that docsUrl is optional since not
all providers have public documentation. This ensures the interface is properly
documented for generated customer documentation and clarifies the API surface
change.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@packages/shared/src/types/oauth.ts`:
- Around line 5-10: The public OAuthProviderData interface is missing JSDoc
documentation required for all public APIs in packages/shared. Add a
comprehensive JSDoc comment block above the interface definition that explains:
the purpose of the interface as OAuth provider configuration metadata, the role
of each property (provider, strategy, name, and docsUrl), and specifically
document that docsUrl is optional since not all providers have public
documentation. This ensures the interface is properly documented for generated
customer documentation and clarifies the API surface change.

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 936623be-bf17-4884-ae4f-fe84ff5cda43

📥 Commits

Reviewing files that changed from the base of the PR and between d97a887 and 9d861e8.

📒 Files selected for processing (4)

• .changeset/fresh-lies-film.md
• packages/shared/src/oauth.ts
• packages/shared/src/types/oauth.ts
• packages/shared/src/types/runtime-values.ts

💤 Files with no reviewable changes (2)

• packages/shared/src/oauth.ts
• packages/shared/src/types/runtime-values.ts

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-23T15:11:19.996Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	1
🟡 Non-breaking changes	0
🟢 Additions	0

Warning
1 breaking change(s) detected - Major version bump required

🤖 This report was reviewed by claude-sonnet-4-6.

🔴 Breaking changes index (1)

Every breaking change, up front. Full diffs are in the package sections below.

Package	Subpath	Change
@clerk/shared	./types	OAuthProviderData.docsUrl

---

@clerk/shared

Current version: 4.20.0
Recommended bump: MAJOR → 5.0.0

Subpath ./types

🔴 Breaking Changes (1)

Changed: OAuthProviderData.docsUrl

- docsUrl: string;+ docsUrl?: string;

Static analyzer: Modified property OAuthProviderData.docsUrl: Member became optional

🤖 AI review (reclassified as breaking) (85%): Making an existing output field optional is breaking (rule 4): consumers reading docsUrl from an OAuthProviderData object previously had a guaranteed string but now receive string | undefined, requiring them to add a null check or their existing code may break at runtime.

Migration: Update any code that reads OAuthProviderData.docsUrl to handle the undefined case, e.g. providerData.docsUrl ?? ''.

---

Report generated by Break Check

_{Last ran on 3c3f1af.}

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

[wobsoriano]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

[manovotny]

I ran a full org-wide sweep of docsUrl / OAUTH_PROVIDERS consumers (in-repo + gh search code --owner clerk), and there is the one spot worth a second look — everything appears safe.

clerk/cli reads OAUTH_PROVIDERS[].docsUrl but defensively (?.docsUrl ?? fallback), and the in-repo UI consumers only read .strategy/.provider/.name, never .docsUrl, so we're good here.

The tricky one is clerk/dashboard. Its getSocialSettings.ts imports OAUTH_PROVIDERS from @clerk/shared/oauth and reads item.docsUrl with a name-based fallback:

item.docsUrl??`https://clerk.com/docs/guides/configure/auth-strategies/social-connections/${item.provider}`

Then, it renders that as the provider's docs link on the SSO connection page.

With docsUrl gone, Enstall falls through to …/guides/configure/auth-strategies/social-connections/enstall, which currently 404s — whereas the URL being removed here 308-redirects to the live social-connections overview (via the redirect added in clerk-docs#3391). So on the Enstall-enabled instance, this swaps a working (redirected) link for a hard 404 on the surface that actually renders it.

Since the dashboard is what surfaces this link, should we pair this with a dashboard change that drops the link when docsUrl is absent (or skips the fallback for private providers), or add a clerk-docs redirect for the new …/auth-strategies/social-connections/enstall path so the fallback resolves?

[SarahSoutoul]

Nice catch! Made a sibling dashboard PR. @manovotny

[SarahSoutoul]

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

Makes sense! But I should prob make it a major bump then? @wobsoriano

[manovotny]

I am good with the changes here and in https://github.com/clerk/dashboard/pull/9497 (this PR needs to land first).

I would appreciate another set of eyes and approval before merge to ensure we're not overlooking anything else.

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.
Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

@jacekradko@wobsoriano could I follow up on this?

[wobsoriano]

Given that this is internal, we can disregard the API breaking change break check 👍🏼

[SarahSoutoul]

This PR is paired with a dashboard PR.

Problem

The JS SDK was shipping a docsUrl for Enstall that points to a docs page that does not exist: https://clerk.com/docs/authentication/social-connections/enstall. That link surfaces to end users as a 404.

Enstall is a private, single-customer OIDC provider rather than a general public social connection, so we should not ship a public docs link for it.

This PR removes the public docsUrl for the Enstall OAuth provider from clerk/javascript.

Changes

• Made docsUrl optional on OAuthProviderData
• Removed docsUrl from the Enstall provider entry in:
  • packages/shared/src/oauth.ts
  • packages/shared/src/types/runtime-values.ts
• Audited current shared/UI consumers in this repo and did not find any UI surface that assumes docsUrl is always present for OAuth providers

Notes

• This is the SDK-side follow-up only for Enstall.
• The long-lived docs redirect added here still needs to remain in clerk-docs for already-shipped SDK versions that still contain the old URL

Summary by CodeRabbit

Summary by CodeRabbit

• Bug Fixes

  • OAuth provider docsUrl is now optional, allowing provider metadata without documentation links.
  • Removed the documentation URL for the Enstall OAuth provider so it no longer returns docsUrl in its provider data.

• Release Management

  • Updated the package changeset to publish a patch/minor version bump for @clerk/shared.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3c3f1af

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Minor
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 23, 2026 3:10pm
swingset	Ready	Preview, Comment	Jun 23, 2026 3:10pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 83a2cf87-9c7f-47ca-825a-aaeae2d39229

📥 Commits

Reviewing files that changed from the base of the PR and between 9d861e8 and 2ac22ef.

📒 Files selected for processing (1)

• .changeset/curly-roses-yawn.md

✅ Files skipped from review due to trivial changes (1)

• .changeset/curly-roses-yawn.md

---

📝 Walkthrough

Walkthrough

OAuthProviderData.docsUrl is changed from a required to an optional field. The enstall OAuth provider entry has its docsUrl property removed in both packages/shared/src/oauth.ts and packages/shared/src/types/runtime-values.ts. Changesets are added for @clerk/shared documenting the API adjustment.

Changes

OAuthProviderData.docsUrl optionality and enstall data update

Layer / File(s)	Summary
Make docsUrl optional and remove enstall docsUrl packages/shared/src/types/oauth.ts, packages/shared/src/oauth.ts, packages/shared/src/types/runtime-values.ts, .changeset/fresh-lies-film.md, .changeset/curly-roses-yawn.md	docsUrl is marked optional on OAuthProviderData; the enstall provider entry drops its docsUrl property from both OAUTH_PROVIDERS arrays; changesets document the API adjustment.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 A URL once required, now set free,
The enstall provider travels light, you see.
No docs link to carry, no string to bind,
Optional and nimble — what a find!
Hop along, little patch, you're just fine! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: removing the docsUrl field for the Enstall OAuth provider, which is the core focus of the pull request across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@8885

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@8885

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@8885

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 3c3f1af

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/shared/src/types/oauth.ts (1)

5-10: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add JSDoc to document the public OAuthProviderData interface.

The OAuthProviderData interface is a public, reference-facing API exported from @clerk/shared that will appear in generated customer documentation. Per the coding guidelines for packages/**/src/**/*.ts files, all public APIs must be documented with comprehensive JSDoc comments.

This interface lacks documentation explaining:

• The purpose of the interface (OAuth provider configuration metadata)
• Each property and its role
• That docsUrl is now optional (not all providers have public documentation)

This is especially important since this PR changes the API surface by making docsUrl optional—customers using this interface need clear documentation of the change.

📝 Suggested JSDoc for OAuthProviderData

 import type { OAuthStrategy } from './strategies';
export type OAuthScope = string;
+/**+ * Represents the configuration metadata for an OAuth provider.+ * + * This interface defines the structure of OAuth provider entries used by Clerk's OAuth integration layer.+ * Each provider has a unique identifier, associated strategy, and optional documentation link.+ * + * `@property` provider - The unique provider identifier (e.g., 'google', 'github', 'enstall')+ * `@property` strategy - The OAuth strategy name for this provider+ * `@property` name - Human-readable display name of the provider+ * `@property` docsUrl - Optional URL to the provider's documentation. Not all providers expose public documentation.+ */
export interface OAuthProviderData {
provider: OAuthProvider;
strategy: OAuthStrategy;
name: string;
docsUrl?: string;
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/shared/src/types/oauth.ts` around lines 5 - 10, The public
OAuthProviderData interface is missing JSDoc documentation required for all
public APIs in packages/shared. Add a comprehensive JSDoc comment block above
the interface definition that explains: the purpose of the interface as OAuth
provider configuration metadata, the role of each property (provider, strategy,
name, and docsUrl), and specifically document that docsUrl is optional since not
all providers have public documentation. This ensures the interface is properly
documented for generated customer documentation and clarifies the API surface
change.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@packages/shared/src/types/oauth.ts`:
- Around line 5-10: The public OAuthProviderData interface is missing JSDoc
documentation required for all public APIs in packages/shared. Add a
comprehensive JSDoc comment block above the interface definition that explains:
the purpose of the interface as OAuth provider configuration metadata, the role
of each property (provider, strategy, name, and docsUrl), and specifically
document that docsUrl is optional since not all providers have public
documentation. This ensures the interface is properly documented for generated
customer documentation and clarifies the API surface change.

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 936623be-bf17-4884-ae4f-fe84ff5cda43

📥 Commits

Reviewing files that changed from the base of the PR and between d97a887 and 9d861e8.

📒 Files selected for processing (4)

• .changeset/fresh-lies-film.md
• packages/shared/src/oauth.ts
• packages/shared/src/types/oauth.ts
• packages/shared/src/types/runtime-values.ts

💤 Files with no reviewable changes (2)

• packages/shared/src/oauth.ts
• packages/shared/src/types/runtime-values.ts

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-23T15:11:19.996Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	1
🟡 Non-breaking changes	0
🟢 Additions	0

Warning
1 breaking change(s) detected - Major version bump required

🤖 This report was reviewed by claude-sonnet-4-6.

🔴 Breaking changes index (1)

Every breaking change, up front. Full diffs are in the package sections below.

Package	Subpath	Change
@clerk/shared	./types	OAuthProviderData.docsUrl

---

@clerk/shared

Current version: 4.20.0
Recommended bump: MAJOR → 5.0.0

Subpath ./types

🔴 Breaking Changes (1)

Changed: OAuthProviderData.docsUrl

- docsUrl: string;+ docsUrl?: string;

Static analyzer: Modified property OAuthProviderData.docsUrl: Member became optional

🤖 AI review (reclassified as breaking) (85%): Making an existing output field optional is breaking (rule 4): consumers reading docsUrl from an OAuthProviderData object previously had a guaranteed string but now receive string | undefined, requiring them to add a null check or their existing code may break at runtime.

Migration: Update any code that reads OAuthProviderData.docsUrl to handle the undefined case, e.g. providerData.docsUrl ?? ''.

---

Report generated by Break Check

_{Last ran on 3c3f1af.}

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

[wobsoriano]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

[manovotny]

I ran a full org-wide sweep of docsUrl / OAUTH_PROVIDERS consumers (in-repo + gh search code --owner clerk), and there is the one spot worth a second look — everything appears safe.

clerk/cli reads OAUTH_PROVIDERS[].docsUrl but defensively (?.docsUrl ?? fallback), and the in-repo UI consumers only read .strategy/.provider/.name, never .docsUrl, so we're good here.

The tricky one is clerk/dashboard. Its getSocialSettings.ts imports OAUTH_PROVIDERS from @clerk/shared/oauth and reads item.docsUrl with a name-based fallback:

item.docsUrl??`https://clerk.com/docs/guides/configure/auth-strategies/social-connections/${item.provider}`

Then, it renders that as the provider's docs link on the SSO connection page.

With docsUrl gone, Enstall falls through to …/guides/configure/auth-strategies/social-connections/enstall, which currently 404s — whereas the URL being removed here 308-redirects to the live social-connections overview (via the redirect added in clerk-docs#3391). So on the Enstall-enabled instance, this swaps a working (redirected) link for a hard 404 on the surface that actually renders it.

Since the dashboard is what surfaces this link, should we pair this with a dashboard change that drops the link when docsUrl is absent (or skips the fallback for private providers), or add a clerk-docs redirect for the new …/auth-strategies/social-connections/enstall path so the fallback resolves?

[SarahSoutoul]

Nice catch! Made a sibling dashboard PR. @manovotny

[SarahSoutoul]

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

Makes sense! But I should prob make it a major bump then? @wobsoriano

[manovotny]

I am good with the changes here and in https://github.com/clerk/dashboard/pull/9497 (this PR needs to land first).

I would appreciate another set of eyes and approval before merge to ensure we're not overlooking anything else.

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.
Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

@jacekradko@wobsoriano could I follow up on this?

[wobsoriano]

Given that this is internal, we can disregard the API breaking change break check 👍🏼

[SarahSoutoul]

This PR is paired with a dashboard PR.

Problem

The JS SDK was shipping a docsUrl for Enstall that points to a docs page that does not exist: https://clerk.com/docs/authentication/social-connections/enstall. That link surfaces to end users as a 404.

Enstall is a private, single-customer OIDC provider rather than a general public social connection, so we should not ship a public docs link for it.

This PR removes the public docsUrl for the Enstall OAuth provider from clerk/javascript.

Changes

• Made docsUrl optional on OAuthProviderData
• Removed docsUrl from the Enstall provider entry in:
  • packages/shared/src/oauth.ts
  • packages/shared/src/types/runtime-values.ts
• Audited current shared/UI consumers in this repo and did not find any UI surface that assumes docsUrl is always present for OAuth providers

Notes

• This is the SDK-side follow-up only for Enstall.
• The long-lived docs redirect added here still needs to remain in clerk-docs for already-shipped SDK versions that still contain the old URL

Summary by CodeRabbit

Summary by CodeRabbit

• Bug Fixes

  • OAuth provider docsUrl is now optional, allowing provider metadata without documentation links.
  • Removed the documentation URL for the Enstall OAuth provider so it no longer returns docsUrl in its provider data.

• Release Management

  • Updated the package changeset to publish a patch/minor version bump for @clerk/shared.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3c3f1af

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Minor
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 23, 2026 3:10pm
swingset	Ready	Preview, Comment	Jun 23, 2026 3:10pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 83a2cf87-9c7f-47ca-825a-aaeae2d39229

📥 Commits

Reviewing files that changed from the base of the PR and between 9d861e8 and 2ac22ef.

📒 Files selected for processing (1)

• .changeset/curly-roses-yawn.md

✅ Files skipped from review due to trivial changes (1)

• .changeset/curly-roses-yawn.md

---

📝 Walkthrough

Walkthrough

OAuthProviderData.docsUrl is changed from a required to an optional field. The enstall OAuth provider entry has its docsUrl property removed in both packages/shared/src/oauth.ts and packages/shared/src/types/runtime-values.ts. Changesets are added for @clerk/shared documenting the API adjustment.

Changes

OAuthProviderData.docsUrl optionality and enstall data update

Layer / File(s)	Summary
Make docsUrl optional and remove enstall docsUrl packages/shared/src/types/oauth.ts, packages/shared/src/oauth.ts, packages/shared/src/types/runtime-values.ts, .changeset/fresh-lies-film.md, .changeset/curly-roses-yawn.md	docsUrl is marked optional on OAuthProviderData; the enstall provider entry drops its docsUrl property from both OAUTH_PROVIDERS arrays; changesets document the API adjustment.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 A URL once required, now set free,
The enstall provider travels light, you see.
No docs link to carry, no string to bind,
Optional and nimble — what a find!
Hop along, little patch, you're just fine! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: removing the docsUrl field for the Enstall OAuth provider, which is the core focus of the pull request across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@8885

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@8885

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@8885

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 3c3f1af

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/shared/src/types/oauth.ts (1)

5-10: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add JSDoc to document the public OAuthProviderData interface.

The OAuthProviderData interface is a public, reference-facing API exported from @clerk/shared that will appear in generated customer documentation. Per the coding guidelines for packages/**/src/**/*.ts files, all public APIs must be documented with comprehensive JSDoc comments.

This interface lacks documentation explaining:

• The purpose of the interface (OAuth provider configuration metadata)
• Each property and its role
• That docsUrl is now optional (not all providers have public documentation)

This is especially important since this PR changes the API surface by making docsUrl optional—customers using this interface need clear documentation of the change.

📝 Suggested JSDoc for OAuthProviderData

 import type { OAuthStrategy } from './strategies';
export type OAuthScope = string;
+/**+ * Represents the configuration metadata for an OAuth provider.+ * + * This interface defines the structure of OAuth provider entries used by Clerk's OAuth integration layer.+ * Each provider has a unique identifier, associated strategy, and optional documentation link.+ * + * `@property` provider - The unique provider identifier (e.g., 'google', 'github', 'enstall')+ * `@property` strategy - The OAuth strategy name for this provider+ * `@property` name - Human-readable display name of the provider+ * `@property` docsUrl - Optional URL to the provider's documentation. Not all providers expose public documentation.+ */
export interface OAuthProviderData {
provider: OAuthProvider;
strategy: OAuthStrategy;
name: string;
docsUrl?: string;
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/shared/src/types/oauth.ts` around lines 5 - 10, The public
OAuthProviderData interface is missing JSDoc documentation required for all
public APIs in packages/shared. Add a comprehensive JSDoc comment block above
the interface definition that explains: the purpose of the interface as OAuth
provider configuration metadata, the role of each property (provider, strategy,
name, and docsUrl), and specifically document that docsUrl is optional since not
all providers have public documentation. This ensures the interface is properly
documented for generated customer documentation and clarifies the API surface
change.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@packages/shared/src/types/oauth.ts`:
- Around line 5-10: The public OAuthProviderData interface is missing JSDoc
documentation required for all public APIs in packages/shared. Add a
comprehensive JSDoc comment block above the interface definition that explains:
the purpose of the interface as OAuth provider configuration metadata, the role
of each property (provider, strategy, name, and docsUrl), and specifically
document that docsUrl is optional since not all providers have public
documentation. This ensures the interface is properly documented for generated
customer documentation and clarifies the API surface change.

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 936623be-bf17-4884-ae4f-fe84ff5cda43

📥 Commits

Reviewing files that changed from the base of the PR and between d97a887 and 9d861e8.

📒 Files selected for processing (4)

• .changeset/fresh-lies-film.md
• packages/shared/src/oauth.ts
• packages/shared/src/types/oauth.ts
• packages/shared/src/types/runtime-values.ts

💤 Files with no reviewable changes (2)

• packages/shared/src/oauth.ts
• packages/shared/src/types/runtime-values.ts

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-23T15:11:19.996Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	1
🟡 Non-breaking changes	0
🟢 Additions	0

Warning
1 breaking change(s) detected - Major version bump required

🤖 This report was reviewed by claude-sonnet-4-6.

🔴 Breaking changes index (1)

Every breaking change, up front. Full diffs are in the package sections below.

Package	Subpath	Change
@clerk/shared	./types	OAuthProviderData.docsUrl

---

@clerk/shared

Current version: 4.20.0
Recommended bump: MAJOR → 5.0.0

Subpath ./types

🔴 Breaking Changes (1)

Changed: OAuthProviderData.docsUrl

- docsUrl: string;+ docsUrl?: string;

Static analyzer: Modified property OAuthProviderData.docsUrl: Member became optional

🤖 AI review (reclassified as breaking) (85%): Making an existing output field optional is breaking (rule 4): consumers reading docsUrl from an OAuthProviderData object previously had a guaranteed string but now receive string | undefined, requiring them to add a null check or their existing code may break at runtime.

Migration: Update any code that reads OAuthProviderData.docsUrl to handle the undefined case, e.g. providerData.docsUrl ?? ''.

---

Report generated by Break Check

_{Last ran on 3c3f1af.}

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

[wobsoriano]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

[manovotny]

I ran a full org-wide sweep of docsUrl / OAUTH_PROVIDERS consumers (in-repo + gh search code --owner clerk), and there is the one spot worth a second look — everything appears safe.

clerk/cli reads OAUTH_PROVIDERS[].docsUrl but defensively (?.docsUrl ?? fallback), and the in-repo UI consumers only read .strategy/.provider/.name, never .docsUrl, so we're good here.

The tricky one is clerk/dashboard. Its getSocialSettings.ts imports OAUTH_PROVIDERS from @clerk/shared/oauth and reads item.docsUrl with a name-based fallback:

item.docsUrl??`https://clerk.com/docs/guides/configure/auth-strategies/social-connections/${item.provider}`

Then, it renders that as the provider's docs link on the SSO connection page.

With docsUrl gone, Enstall falls through to …/guides/configure/auth-strategies/social-connections/enstall, which currently 404s — whereas the URL being removed here 308-redirects to the live social-connections overview (via the redirect added in clerk-docs#3391). So on the Enstall-enabled instance, this swaps a working (redirected) link for a hard 404 on the surface that actually renders it.

Since the dashboard is what surfaces this link, should we pair this with a dashboard change that drops the link when docsUrl is absent (or skips the fallback for private providers), or add a clerk-docs redirect for the new …/auth-strategies/social-connections/enstall path so the fallback resolves?

[SarahSoutoul]

Nice catch! Made a sibling dashboard PR. @manovotny

[SarahSoutoul]

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

Makes sense! But I should prob make it a major bump then? @wobsoriano

[manovotny]

I am good with the changes here and in https://github.com/clerk/dashboard/pull/9497 (this PR needs to land first).

I would appreciate another set of eyes and approval before merge to ensure we're not overlooking anything else.

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.
Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

@jacekradko@wobsoriano could I follow up on this?

[wobsoriano]

Given that this is internal, we can disregard the API breaking change break check 👍🏼

[SarahSoutoul]

This PR is paired with a dashboard PR.

Problem

The JS SDK was shipping a docsUrl for Enstall that points to a docs page that does not exist: https://clerk.com/docs/authentication/social-connections/enstall. That link surfaces to end users as a 404.

Enstall is a private, single-customer OIDC provider rather than a general public social connection, so we should not ship a public docs link for it.

This PR removes the public docsUrl for the Enstall OAuth provider from clerk/javascript.

Changes

• Made docsUrl optional on OAuthProviderData
• Removed docsUrl from the Enstall provider entry in:
  • packages/shared/src/oauth.ts
  • packages/shared/src/types/runtime-values.ts
• Audited current shared/UI consumers in this repo and did not find any UI surface that assumes docsUrl is always present for OAuth providers

Notes

• This is the SDK-side follow-up only for Enstall.
• The long-lived docs redirect added here still needs to remain in clerk-docs for already-shipped SDK versions that still contain the old URL

Summary by CodeRabbit

Summary by CodeRabbit

• Bug Fixes

  • OAuth provider docsUrl is now optional, allowing provider metadata without documentation links.
  • Removed the documentation URL for the Enstall OAuth provider so it no longer returns docsUrl in its provider data.

• Release Management

  • Updated the package changeset to publish a patch/minor version bump for @clerk/shared.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3c3f1af

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Minor
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 23, 2026 3:10pm
swingset	Ready	Preview, Comment	Jun 23, 2026 3:10pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 83a2cf87-9c7f-47ca-825a-aaeae2d39229

📥 Commits

Reviewing files that changed from the base of the PR and between 9d861e8 and 2ac22ef.

📒 Files selected for processing (1)

• .changeset/curly-roses-yawn.md

✅ Files skipped from review due to trivial changes (1)

• .changeset/curly-roses-yawn.md

---

📝 Walkthrough

Walkthrough

OAuthProviderData.docsUrl is changed from a required to an optional field. The enstall OAuth provider entry has its docsUrl property removed in both packages/shared/src/oauth.ts and packages/shared/src/types/runtime-values.ts. Changesets are added for @clerk/shared documenting the API adjustment.

Changes

OAuthProviderData.docsUrl optionality and enstall data update

Layer / File(s)	Summary
Make docsUrl optional and remove enstall docsUrl packages/shared/src/types/oauth.ts, packages/shared/src/oauth.ts, packages/shared/src/types/runtime-values.ts, .changeset/fresh-lies-film.md, .changeset/curly-roses-yawn.md	docsUrl is marked optional on OAuthProviderData; the enstall provider entry drops its docsUrl property from both OAUTH_PROVIDERS arrays; changesets document the API adjustment.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 A URL once required, now set free,
The enstall provider travels light, you see.
No docs link to carry, no string to bind,
Optional and nimble — what a find!
Hop along, little patch, you're just fine! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: removing the docsUrl field for the Enstall OAuth provider, which is the core focus of the pull request across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@8885

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@8885

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@8885

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 3c3f1af

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/shared/src/types/oauth.ts (1)

5-10: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add JSDoc to document the public OAuthProviderData interface.

The OAuthProviderData interface is a public, reference-facing API exported from @clerk/shared that will appear in generated customer documentation. Per the coding guidelines for packages/**/src/**/*.ts files, all public APIs must be documented with comprehensive JSDoc comments.

This interface lacks documentation explaining:

• The purpose of the interface (OAuth provider configuration metadata)
• Each property and its role
• That docsUrl is now optional (not all providers have public documentation)

This is especially important since this PR changes the API surface by making docsUrl optional—customers using this interface need clear documentation of the change.

📝 Suggested JSDoc for OAuthProviderData

 import type { OAuthStrategy } from './strategies';
export type OAuthScope = string;
+/**+ * Represents the configuration metadata for an OAuth provider.+ * + * This interface defines the structure of OAuth provider entries used by Clerk's OAuth integration layer.+ * Each provider has a unique identifier, associated strategy, and optional documentation link.+ * + * `@property` provider - The unique provider identifier (e.g., 'google', 'github', 'enstall')+ * `@property` strategy - The OAuth strategy name for this provider+ * `@property` name - Human-readable display name of the provider+ * `@property` docsUrl - Optional URL to the provider's documentation. Not all providers expose public documentation.+ */
export interface OAuthProviderData {
provider: OAuthProvider;
strategy: OAuthStrategy;
name: string;
docsUrl?: string;
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/shared/src/types/oauth.ts` around lines 5 - 10, The public
OAuthProviderData interface is missing JSDoc documentation required for all
public APIs in packages/shared. Add a comprehensive JSDoc comment block above
the interface definition that explains: the purpose of the interface as OAuth
provider configuration metadata, the role of each property (provider, strategy,
name, and docsUrl), and specifically document that docsUrl is optional since not
all providers have public documentation. This ensures the interface is properly
documented for generated customer documentation and clarifies the API surface
change.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@packages/shared/src/types/oauth.ts`:
- Around line 5-10: The public OAuthProviderData interface is missing JSDoc
documentation required for all public APIs in packages/shared. Add a
comprehensive JSDoc comment block above the interface definition that explains:
the purpose of the interface as OAuth provider configuration metadata, the role
of each property (provider, strategy, name, and docsUrl), and specifically
document that docsUrl is optional since not all providers have public
documentation. This ensures the interface is properly documented for generated
customer documentation and clarifies the API surface change.

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 936623be-bf17-4884-ae4f-fe84ff5cda43

📥 Commits

Reviewing files that changed from the base of the PR and between d97a887 and 9d861e8.

📒 Files selected for processing (4)

• .changeset/fresh-lies-film.md
• packages/shared/src/oauth.ts
• packages/shared/src/types/oauth.ts
• packages/shared/src/types/runtime-values.ts

💤 Files with no reviewable changes (2)

• packages/shared/src/oauth.ts
• packages/shared/src/types/runtime-values.ts

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-23T15:11:19.996Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	1
🟡 Non-breaking changes	0
🟢 Additions	0

Warning
1 breaking change(s) detected - Major version bump required

🤖 This report was reviewed by claude-sonnet-4-6.

🔴 Breaking changes index (1)

Every breaking change, up front. Full diffs are in the package sections below.

Package	Subpath	Change
@clerk/shared	./types	OAuthProviderData.docsUrl

---

@clerk/shared

Current version: 4.20.0
Recommended bump: MAJOR → 5.0.0

Subpath ./types

🔴 Breaking Changes (1)

Changed: OAuthProviderData.docsUrl

- docsUrl: string;+ docsUrl?: string;

Static analyzer: Modified property OAuthProviderData.docsUrl: Member became optional

🤖 AI review (reclassified as breaking) (85%): Making an existing output field optional is breaking (rule 4): consumers reading docsUrl from an OAuthProviderData object previously had a guaranteed string but now receive string | undefined, requiring them to add a null check or their existing code may break at runtime.

Migration: Update any code that reads OAuthProviderData.docsUrl to handle the undefined case, e.g. providerData.docsUrl ?? ''.

---

Report generated by Break Check

_{Last ran on 3c3f1af.}

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

[wobsoriano]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

[manovotny]

I ran a full org-wide sweep of docsUrl / OAUTH_PROVIDERS consumers (in-repo + gh search code --owner clerk), and there is the one spot worth a second look — everything appears safe.

clerk/cli reads OAUTH_PROVIDERS[].docsUrl but defensively (?.docsUrl ?? fallback), and the in-repo UI consumers only read .strategy/.provider/.name, never .docsUrl, so we're good here.

The tricky one is clerk/dashboard. Its getSocialSettings.ts imports OAUTH_PROVIDERS from @clerk/shared/oauth and reads item.docsUrl with a name-based fallback:

item.docsUrl??`https://clerk.com/docs/guides/configure/auth-strategies/social-connections/${item.provider}`

Then, it renders that as the provider's docs link on the SSO connection page.

With docsUrl gone, Enstall falls through to …/guides/configure/auth-strategies/social-connections/enstall, which currently 404s — whereas the URL being removed here 308-redirects to the live social-connections overview (via the redirect added in clerk-docs#3391). So on the Enstall-enabled instance, this swaps a working (redirected) link for a hard 404 on the surface that actually renders it.

Since the dashboard is what surfaces this link, should we pair this with a dashboard change that drops the link when docsUrl is absent (or skips the fallback for private providers), or add a clerk-docs redirect for the new …/auth-strategies/social-connections/enstall path so the fallback resolves?

[SarahSoutoul]

Nice catch! Made a sibling dashboard PR. @manovotny

[SarahSoutoul]

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

Makes sense! But I should prob make it a major bump then? @wobsoriano

[manovotny]

I am good with the changes here and in https://github.com/clerk/dashboard/pull/9497 (this PR needs to land first).

I would appreciate another set of eyes and approval before merge to ensure we're not overlooking anything else.

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.
Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

@jacekradko@wobsoriano could I follow up on this?

[wobsoriano]

Given that this is internal, we can disregard the API breaking change break check 👍🏼

[SarahSoutoul]

This PR is paired with a dashboard PR.

Problem

The JS SDK was shipping a docsUrl for Enstall that points to a docs page that does not exist: https://clerk.com/docs/authentication/social-connections/enstall. That link surfaces to end users as a 404.

Enstall is a private, single-customer OIDC provider rather than a general public social connection, so we should not ship a public docs link for it.

This PR removes the public docsUrl for the Enstall OAuth provider from clerk/javascript.

Changes

• Made docsUrl optional on OAuthProviderData
• Removed docsUrl from the Enstall provider entry in:
  • packages/shared/src/oauth.ts
  • packages/shared/src/types/runtime-values.ts
• Audited current shared/UI consumers in this repo and did not find any UI surface that assumes docsUrl is always present for OAuth providers

Notes

• This is the SDK-side follow-up only for Enstall.
• The long-lived docs redirect added here still needs to remain in clerk-docs for already-shipped SDK versions that still contain the old URL

Summary by CodeRabbit

Summary by CodeRabbit

• Bug Fixes

  • OAuth provider docsUrl is now optional, allowing provider metadata without documentation links.
  • Removed the documentation URL for the Enstall OAuth provider so it no longer returns docsUrl in its provider data.

• Release Management

  • Updated the package changeset to publish a patch/minor version bump for @clerk/shared.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3c3f1af

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Minor
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 23, 2026 3:10pm
swingset	Ready	Preview, Comment	Jun 23, 2026 3:10pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 83a2cf87-9c7f-47ca-825a-aaeae2d39229

📥 Commits

Reviewing files that changed from the base of the PR and between 9d861e8 and 2ac22ef.

📒 Files selected for processing (1)

• .changeset/curly-roses-yawn.md

✅ Files skipped from review due to trivial changes (1)

• .changeset/curly-roses-yawn.md

---

📝 Walkthrough

Walkthrough

OAuthProviderData.docsUrl is changed from a required to an optional field. The enstall OAuth provider entry has its docsUrl property removed in both packages/shared/src/oauth.ts and packages/shared/src/types/runtime-values.ts. Changesets are added for @clerk/shared documenting the API adjustment.

Changes

OAuthProviderData.docsUrl optionality and enstall data update

Layer / File(s)	Summary
Make docsUrl optional and remove enstall docsUrl packages/shared/src/types/oauth.ts, packages/shared/src/oauth.ts, packages/shared/src/types/runtime-values.ts, .changeset/fresh-lies-film.md, .changeset/curly-roses-yawn.md	docsUrl is marked optional on OAuthProviderData; the enstall provider entry drops its docsUrl property from both OAUTH_PROVIDERS arrays; changesets document the API adjustment.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 A URL once required, now set free,
The enstall provider travels light, you see.
No docs link to carry, no string to bind,
Optional and nimble — what a find!
Hop along, little patch, you're just fine! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: removing the docsUrl field for the Enstall OAuth provider, which is the core focus of the pull request across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@8885

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@8885

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@8885

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 3c3f1af

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/shared/src/types/oauth.ts (1)

5-10: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add JSDoc to document the public OAuthProviderData interface.

The OAuthProviderData interface is a public, reference-facing API exported from @clerk/shared that will appear in generated customer documentation. Per the coding guidelines for packages/**/src/**/*.ts files, all public APIs must be documented with comprehensive JSDoc comments.

This interface lacks documentation explaining:

• The purpose of the interface (OAuth provider configuration metadata)
• Each property and its role
• That docsUrl is now optional (not all providers have public documentation)

This is especially important since this PR changes the API surface by making docsUrl optional—customers using this interface need clear documentation of the change.

📝 Suggested JSDoc for OAuthProviderData

 import type { OAuthStrategy } from './strategies';
export type OAuthScope = string;
+/**+ * Represents the configuration metadata for an OAuth provider.+ * + * This interface defines the structure of OAuth provider entries used by Clerk's OAuth integration layer.+ * Each provider has a unique identifier, associated strategy, and optional documentation link.+ * + * `@property` provider - The unique provider identifier (e.g., 'google', 'github', 'enstall')+ * `@property` strategy - The OAuth strategy name for this provider+ * `@property` name - Human-readable display name of the provider+ * `@property` docsUrl - Optional URL to the provider's documentation. Not all providers expose public documentation.+ */
export interface OAuthProviderData {
provider: OAuthProvider;
strategy: OAuthStrategy;
name: string;
docsUrl?: string;
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/shared/src/types/oauth.ts` around lines 5 - 10, The public
OAuthProviderData interface is missing JSDoc documentation required for all
public APIs in packages/shared. Add a comprehensive JSDoc comment block above
the interface definition that explains: the purpose of the interface as OAuth
provider configuration metadata, the role of each property (provider, strategy,
name, and docsUrl), and specifically document that docsUrl is optional since not
all providers have public documentation. This ensures the interface is properly
documented for generated customer documentation and clarifies the API surface
change.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@packages/shared/src/types/oauth.ts`:
- Around line 5-10: The public OAuthProviderData interface is missing JSDoc
documentation required for all public APIs in packages/shared. Add a
comprehensive JSDoc comment block above the interface definition that explains:
the purpose of the interface as OAuth provider configuration metadata, the role
of each property (provider, strategy, name, and docsUrl), and specifically
document that docsUrl is optional since not all providers have public
documentation. This ensures the interface is properly documented for generated
customer documentation and clarifies the API surface change.

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 936623be-bf17-4884-ae4f-fe84ff5cda43

📥 Commits

Reviewing files that changed from the base of the PR and between d97a887 and 9d861e8.

📒 Files selected for processing (4)

• .changeset/fresh-lies-film.md
• packages/shared/src/oauth.ts
• packages/shared/src/types/oauth.ts
• packages/shared/src/types/runtime-values.ts

💤 Files with no reviewable changes (2)

• packages/shared/src/oauth.ts
• packages/shared/src/types/runtime-values.ts

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-23T15:11:19.996Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	1
🟡 Non-breaking changes	0
🟢 Additions	0

Warning
1 breaking change(s) detected - Major version bump required

🤖 This report was reviewed by claude-sonnet-4-6.

🔴 Breaking changes index (1)

Every breaking change, up front. Full diffs are in the package sections below.

Package	Subpath	Change
@clerk/shared	./types	OAuthProviderData.docsUrl

---

@clerk/shared

Current version: 4.20.0
Recommended bump: MAJOR → 5.0.0

Subpath ./types

🔴 Breaking Changes (1)

Changed: OAuthProviderData.docsUrl

- docsUrl: string;+ docsUrl?: string;

Static analyzer: Modified property OAuthProviderData.docsUrl: Member became optional

🤖 AI review (reclassified as breaking) (85%): Making an existing output field optional is breaking (rule 4): consumers reading docsUrl from an OAuthProviderData object previously had a guaranteed string but now receive string | undefined, requiring them to add a null check or their existing code may break at runtime.

Migration: Update any code that reads OAuthProviderData.docsUrl to handle the undefined case, e.g. providerData.docsUrl ?? ''.

---

Report generated by Break Check

_{Last ran on 3c3f1af.}

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

[wobsoriano]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.

Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

[manovotny]

I ran a full org-wide sweep of docsUrl / OAUTH_PROVIDERS consumers (in-repo + gh search code --owner clerk), and there is the one spot worth a second look — everything appears safe.

clerk/cli reads OAUTH_PROVIDERS[].docsUrl but defensively (?.docsUrl ?? fallback), and the in-repo UI consumers only read .strategy/.provider/.name, never .docsUrl, so we're good here.

The tricky one is clerk/dashboard. Its getSocialSettings.ts imports OAUTH_PROVIDERS from @clerk/shared/oauth and reads item.docsUrl with a name-based fallback:

item.docsUrl??`https://clerk.com/docs/guides/configure/auth-strategies/social-connections/${item.provider}`

Then, it renders that as the provider's docs link on the SSO connection page.

With docsUrl gone, Enstall falls through to …/guides/configure/auth-strategies/social-connections/enstall, which currently 404s — whereas the URL being removed here 308-redirects to the live social-connections overview (via the redirect added in clerk-docs#3391). So on the Enstall-enabled instance, this swaps a working (redirected) link for a hard 404 on the surface that actually renders it.

Since the dashboard is what surfaces this link, should we pair this with a dashboard change that drops the link when docsUrl is absent (or skips the fallback for private providers), or add a clerk-docs redirect for the new …/auth-strategies/social-connections/enstall path so the fallback resolves?

[SarahSoutoul]

Nice catch! Made a sibling dashboard PR. @manovotny

[SarahSoutoul]

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

Makes sense! But I should prob make it a major bump then? @wobsoriano

[manovotny]

I am good with the changes here and in https://github.com/clerk/dashboard/pull/9497 (this PR needs to land first).

I would appreciate another set of eyes and approval before merge to ensure we're not overlooking anything else.

[SarahSoutoul]

@manovotny a bit worried about this warning. Making OAuthProviderData.docsUrl optional fixes the Enstall 404 cleanly on the SDK side, but it also changes a public @clerk/shared type from string to string | undefined, which the analyzer is classifying as a breaking change. That would imply a major bump just for this fix, which feels heavier than what we want here.
Wanted to sanity-check whether we’re okay treating this as a real breaking change, or if we'd rather preserve the current type shape and use a safer fallback for Enstall instead?

This is expected result with our new break check tool. But this type is only used by docs correct? Tagging @jacekradko here

@jacekradko@wobsoriano could I follow up on this?

[wobsoriano]

Given that this is internal, we can disregard the API breaking change break check 👍🏼