docs(shared): reframe the apiUrlFromPublishableKey return type rationale - #8794

Merged
jacekradko merged 1 commit into
mainfrom
jacek/unpin-apiurl-return-type
Jun 11, 2026
Merged

docs(shared): reframe the apiUrlFromPublishableKey return type rationale#8794
jacekradko merged 1 commit into
mainfrom
jacek/unpin-apiurl-return-type

Conversation

@jacekradko

@jacekradkojacekradko commented Jun 10, 2026•
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Contributor

Follow-up to #8793. The comment on apiUrlFromPublishableKey claimed the explicit return type exists because break-check thrashes on inferred union order; that stopped being true once the v0.2.0 pin landed the root fix (clerk/break-check#85). The annotation itself stays. As CodeRabbit pointed out, it matches the repo TypeScript guideline for public APIs, and it has to be the literal form: annotating with typeof CONST pulls a hashed _chunks/* import into the published d.ts (verified against the actual emit), which is the unresolvable-reference problem all over again.

So this just rewrites the comment to give the real, current reasons.

Summary by CodeRabbit

  • Chores
    • Updated internal documentation and code comments to clarify implementation details.

@changeset-bot

changeset-botBot commented Jun 10, 2026•
edited
Loading

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: d705eb3

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

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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

vercelBot commented Jun 10, 2026•
edited
Loading

Copy link
Copy Markdown

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

ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreview, CommentJun 10, 2026 3:38am

Request Review

@coderabbitai

coderabbitaiBot commented Jun 10, 2026•
edited
Loading

Copy link
Copy Markdown
Contributor

Review Change Stack

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: bf843b88-766a-48fd-8705-b605c8258f9b

📥 Commits

Reviewing files that changed from the base of the PR and between 7d8b9ec and d705eb3.

📒 Files selected for processing (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
✅ Files skipped from review due to trivial changes (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
📝 Walkthrough

Walkthrough

This PR documents the rationale for using explicit string-literal return types in apiUrlFromPublishableKey. The function's pre-export comment block was updated to explain the determinism requirement, and a changeset file was added to track this documentation change for release notes.

Changes

Explicit return type rationale documentation

Layer / File(s)Summary
Return type determinism rationale
packages/shared/src/apiUrlFromPublishableKey.ts, .changeset/apiurl-return-type-rationale.md		The comment block preceding apiUrlFromPublishableKey is updated to explain the explicit string-literal return type requirement for deterministic .d.ts emission, and a changeset entry documents this pattern for release notes.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

  • clerk/javascript#8783: Directly related—both PRs focus on the apiUrlFromPublishableKey return type annotation and its role in maintaining deterministic declaration emit.

Suggested reviewers

  • wobsoriano

Poem

🐰 A comment's path so clear and bright,
Explains why types must be just right,
String literals pinned for emit's delight,
Deterministic declarations—what a sight!
The changelog marks this rationale's flight.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check nameStatusExplanationResolution
Title check⚠️ WarningThe PR title mentions 'reframe the apiUrlFromPublishableKey return type rationale' which refers to updating documentation/comments about the return type, but the actual PR objective is to remove the pinned return-type annotation itself—a functional change, not just a rationale reframing.Align the title with the actual intent: 'refactor(shared): drop the pinned apiUrlFromPublishableKey return type' better reflects the substantive change being made.
✅ Passed checks (4 passed)
Check nameStatusExplanation
Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

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

@pkg-pr-new

pkg-pr-newBot commented Jun 10, 2026•
edited
Loading

Copy link
Copy Markdown

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: d705eb3

@github-actions

github-actionsBot commented Jun 10, 2026•
edited
Loading

Copy link
Copy Markdown
Contributor

API Changes Report

Generated by Break Check on 2026-06-10T03:41:13.256Z

Summary

MetricCount
Packages analyzed19
Packages with changes0
🔴 Breaking changes0
🟡 Non-breaking changes0
🟢 Additions0

Note
Break Check could not snapshot 3 subpaths; the diff below excludes them.

  • @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/testing ./cypress: Symbol not found for identifier: Cypress

No API Changes Detected

All packages have stable APIs with no detected changes.

Report generated by Break Check

Last ran on d705eb3.

coderabbitai[bot]
coderabbitaiBot reviewed Jun 10, 2026
View reviewed changes

@coderabbitaicoderabbitaiBot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 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.
Inline comments:
In `@packages/shared/src/apiUrlFromPublishableKey.ts`:
- Line 17: Restore an explicit return type on the exported function
apiUrlFromPublishableKey: update its signature to include the correct return
type (e.g., string or the appropriate union type used elsewhere) so the public
API has an explicit TypeScript return annotation; locate the function
declaration "export const apiUrlFromPublishableKey = (publishableKey: string)
=>" and add the explicit return type after the parameter list to match
repository guidelines and existing usage.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 5f37ead0-2b07-40b0-8723-398024073fb5

📥 Commits

Reviewing files that changed from the base of the PR and between 400d10c and 7d8b9ec.

📒 Files selected for processing (2)
  • .changeset/unpin-apiurl-return-type.md
  • packages/shared/src/apiUrlFromPublishableKey.ts

Comment threadpackages/shared/src/apiUrlFromPublishableKey.ts Outdated
@jacekradko
jacekradkoforce-pushed the jacek/unpin-apiurl-return-type branch from 7d8b9ec to d705eb3CompareJune 10, 2026 03:37
@jacekradkojacekradko changed the title refactor(shared): drop the pinned apiUrlFromPublishableKey return typedocs(shared): reframe the apiUrlFromPublishableKey return type rationaleJun 10, 2026
@jacekradko
jacekradko merged commit b7cac0a into mainJun 11, 2026
50 checks passed
@jacekradko
jacekradko deleted the jacek/unpin-apiurl-return-type branch June 11, 2026 00:37
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@coderabbitaicoderabbitai[bot]coderabbitai[bot] left review comments
@wobsorianowobsorianowobsoriano approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@jacekradko@wobsoriano
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
docs(shared): reframe the apiUrlFromPublishableKey return type rationale - #8794
Merged
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Jun 11, 2026
Merged
docs(shared): reframe the apiUrlFromPublishableKey return type rationale#8794
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Conversation
@jacekradko
@jacekradkojacekradko
commented
Jun 10, 2026•

edited by coderabbitai
Bot
Loading

Copy link


Copy Markdown

Contributor
Follow-up to #8793. The comment on apiUrlFromPublishableKey claimed the explicit return type exists because break-check thrashes on inferred union order; that stopped being true once the v0.2.0 pin landed the root fix (clerk/break-check#85). The annotation itself stays. As CodeRabbit pointed out, it matches the repo TypeScript guideline for public APIs, and it has to be the literal form: annotating with typeof CONST pulls a hashed _chunks/* import into the published d.ts (verified against the actual emit), which is the unresolvable-reference problem all over again.
So this just rewrites the comment to give the real, current reasons.
Summary by CodeRabbit
  • Chores
    • Updated internal documentation and code comments to clarify implementation details.
@changeset-bot
changeset-botBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

🦋 Changeset detected
Latest commit: d705eb3
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 0 packages
When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types
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
vercelBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.
ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreview, CommentJun 10, 2026 3:38am
Request Review
@coderabbitai
coderabbitaiBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
Review Change Stack
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: bf843b88-766a-48fd-8705-b605c8258f9b
📥 Commits
Reviewing files that changed from the base of the PR and between 7d8b9ec and d705eb3.
📒 Files selected for processing (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
✅ Files skipped from review due to trivial changes (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
📝 Walkthrough
Walkthrough
This PR documents the rationale for using explicit string-literal return types in apiUrlFromPublishableKey. The function's pre-export comment block was updated to explain the determinism requirement, and a changeset file was added to track this documentation change for release notes.
Changes
Explicit return type rationale documentation
Layer / File(s)Summary
Return type determinism rationale
packages/shared/src/apiUrlFromPublishableKey.ts, .changeset/apiurl-return-type-rationale.md		The comment block preceding apiUrlFromPublishableKey is updated to explain the explicit string-literal return type requirement for deterministic .d.ts emission, and a changeset entry documents this pattern for release notes.
Estimated code review effort
🎯 1 (Trivial) | ⏱️ ~3 minutes
Possibly related PRs
  • clerk/javascript#8783: Directly related—both PRs focus on the apiUrlFromPublishableKey return type annotation and its role in maintaining deterministic declaration emit.
Suggested reviewers
  • wobsoriano
Poem
🐰 A comment's path so clear and bright,

Explains why types must be just right,

String literals pinned for emit's delight,

Deterministic declarations—what a sight!

The changelog marks this rationale's flight.
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)
Check nameStatusExplanationResolution
Title check⚠️ WarningThe PR title mentions 'reframe the apiUrlFromPublishableKey return type rationale' which refers to updating documentation/comments about the return type, but the actual PR objective is to remove the pinned return-type annotation itself—a functional change, not just a rationale reframing.Align the title with the actual intent: 'refactor(shared): drop the pinned apiUrlFromPublishableKey return type' better reflects the substantive change being made.
✅ Passed checks (4 passed)
Check nameStatusExplanation
Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
✏️ Tip: You can configure your own custom pre-merge checks in the settings.
✨ Finishing Touches
📝 Generate docstrings
  •  Create stacked PR
  •  Commit on current branch
Comment @coderabbitai help to get the list of available commands and usage tips.
@pkg-pr-new
pkg-pr-newBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Open in StackBlitz
@clerk/astro
npm i https://pkg.pr.new/@clerk/astro@8794

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

commit: d705eb3
@github-actions
github-actionsBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
API Changes Report
Generated by Break Check on 2026-06-10T03:41:13.256Z
Summary
MetricCount
Packages analyzed19
Packages with changes0
🔴 Breaking changes0
🟡 Non-breaking changes0
🟢 Additions0
Note

Break Check could not snapshot 3 subpaths; the diff below excludes them.
  • @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/testing ./cypress: Symbol not found for identifier: Cypress
No API Changes Detected
All packages have stable APIs with no detected changes.
Report generated by Break Check
Last ran on d705eb3.
coderabbitai[bot]
coderabbitaiBot
reviewed
Jun 10, 2026
View reviewed changes
@coderabbitaicoderabbitaiBot
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1
🤖 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.
Inline comments:
In `@packages/shared/src/apiUrlFromPublishableKey.ts`:
- Line 17: Restore an explicit return type on the exported function
apiUrlFromPublishableKey: update its signature to include the correct return
type (e.g., string or the appropriate union type used elsewhere) so the public
API has an explicit TypeScript return annotation; locate the function
declaration "export const apiUrlFromPublishableKey = (publishableKey: string)
=>" and add the explicit return type after the parameter list to match
repository guidelines and existing usage.

🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
  •  Push a commit to this branch (recommended)
  •  Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 5f37ead0-2b07-40b0-8723-398024073fb5
📥 Commits
Reviewing files that changed from the base of the PR and between 400d10c and 7d8b9ec.
📒 Files selected for processing (2)
  • .changeset/unpin-apiurl-return-type.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
Comment threadpackages/shared/src/apiUrlFromPublishableKey.ts
Outdated

@jacekradko
jacekradkoforce-pushed
the
jacek/unpin-apiurl-return-type
branch
from
7d8b9ec to
d705eb3CompareJune 10, 2026 03:37
@jacekradkojacekradko
changed the title
refactor(shared): drop the pinned apiUrlFromPublishableKey return typedocs(shared): reframe the apiUrlFromPublishableKey return type rationaleJun 10, 2026
@jacekradko
jacekradko
merged commit b7cac0a
into
mainJun 11, 2026

50 checks passed

@jacekradko
jacekradko
deleted the

jacek/unpin-apiurl-return-type

branch
June 11, 2026 00:37
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@coderabbitaicoderabbitai[bot]coderabbitai[bot] left review comments
@wobsorianowobsorianowobsoriano approved these changes

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

2 participants

@jacekradko@wobsoriano

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs(shared): reframe the apiUrlFromPublishableKey return type rationale - #8794
Merged
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Jun 11, 2026
Merged
docs(shared): reframe the apiUrlFromPublishableKey return type rationale#8794
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Conversation
@jacekradko
@jacekradkojacekradko
commented
Jun 10, 2026•

edited by coderabbitai
Bot
Loading

Copy link


Copy Markdown

Contributor
Follow-up to #8793. The comment on apiUrlFromPublishableKey claimed the explicit return type exists because break-check thrashes on inferred union order; that stopped being true once the v0.2.0 pin landed the root fix (clerk/break-check#85). The annotation itself stays. As CodeRabbit pointed out, it matches the repo TypeScript guideline for public APIs, and it has to be the literal form: annotating with typeof CONST pulls a hashed _chunks/* import into the published d.ts (verified against the actual emit), which is the unresolvable-reference problem all over again.
So this just rewrites the comment to give the real, current reasons.
Summary by CodeRabbit
  • Chores
    • Updated internal documentation and code comments to clarify implementation details.
@changeset-bot
changeset-botBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

🦋 Changeset detected
Latest commit: d705eb3
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 0 packages
When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types
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
vercelBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.
ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreview, CommentJun 10, 2026 3:38am
Request Review
@coderabbitai
coderabbitaiBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
Review Change Stack
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: bf843b88-766a-48fd-8705-b605c8258f9b
📥 Commits
Reviewing files that changed from the base of the PR and between 7d8b9ec and d705eb3.
📒 Files selected for processing (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
✅ Files skipped from review due to trivial changes (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
📝 Walkthrough
Walkthrough
This PR documents the rationale for using explicit string-literal return types in apiUrlFromPublishableKey. The function's pre-export comment block was updated to explain the determinism requirement, and a changeset file was added to track this documentation change for release notes.
Changes
Explicit return type rationale documentation
Layer / File(s)Summary
Return type determinism rationale
packages/shared/src/apiUrlFromPublishableKey.ts, .changeset/apiurl-return-type-rationale.md		The comment block preceding apiUrlFromPublishableKey is updated to explain the explicit string-literal return type requirement for deterministic .d.ts emission, and a changeset entry documents this pattern for release notes.
Estimated code review effort
🎯 1 (Trivial) | ⏱️ ~3 minutes
Possibly related PRs
  • clerk/javascript#8783: Directly related—both PRs focus on the apiUrlFromPublishableKey return type annotation and its role in maintaining deterministic declaration emit.
Suggested reviewers
  • wobsoriano
Poem
🐰 A comment's path so clear and bright,

Explains why types must be just right,

String literals pinned for emit's delight,

Deterministic declarations—what a sight!

The changelog marks this rationale's flight.
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)
Check nameStatusExplanationResolution
Title check⚠️ WarningThe PR title mentions 'reframe the apiUrlFromPublishableKey return type rationale' which refers to updating documentation/comments about the return type, but the actual PR objective is to remove the pinned return-type annotation itself—a functional change, not just a rationale reframing.Align the title with the actual intent: 'refactor(shared): drop the pinned apiUrlFromPublishableKey return type' better reflects the substantive change being made.
✅ Passed checks (4 passed)
Check nameStatusExplanation
Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
✏️ Tip: You can configure your own custom pre-merge checks in the settings.
✨ Finishing Touches
📝 Generate docstrings
  •  Create stacked PR
  •  Commit on current branch
Comment @coderabbitai help to get the list of available commands and usage tips.
@pkg-pr-new
pkg-pr-newBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Open in StackBlitz
@clerk/astro
npm i https://pkg.pr.new/@clerk/astro@8794

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

commit: d705eb3
@github-actions
github-actionsBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
API Changes Report
Generated by Break Check on 2026-06-10T03:41:13.256Z
Summary
MetricCount
Packages analyzed19
Packages with changes0
🔴 Breaking changes0
🟡 Non-breaking changes0
🟢 Additions0
Note

Break Check could not snapshot 3 subpaths; the diff below excludes them.
  • @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/testing ./cypress: Symbol not found for identifier: Cypress
No API Changes Detected
All packages have stable APIs with no detected changes.
Report generated by Break Check
Last ran on d705eb3.
coderabbitai[bot]
coderabbitaiBot
reviewed
Jun 10, 2026
View reviewed changes
@coderabbitaicoderabbitaiBot
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1
🤖 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.
Inline comments:
In `@packages/shared/src/apiUrlFromPublishableKey.ts`:
- Line 17: Restore an explicit return type on the exported function
apiUrlFromPublishableKey: update its signature to include the correct return
type (e.g., string or the appropriate union type used elsewhere) so the public
API has an explicit TypeScript return annotation; locate the function
declaration "export const apiUrlFromPublishableKey = (publishableKey: string)
=>" and add the explicit return type after the parameter list to match
repository guidelines and existing usage.

🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
  •  Push a commit to this branch (recommended)
  •  Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 5f37ead0-2b07-40b0-8723-398024073fb5
📥 Commits
Reviewing files that changed from the base of the PR and between 400d10c and 7d8b9ec.
📒 Files selected for processing (2)
  • .changeset/unpin-apiurl-return-type.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
Comment threadpackages/shared/src/apiUrlFromPublishableKey.ts
Outdated

@jacekradko
jacekradkoforce-pushed
the
jacek/unpin-apiurl-return-type
branch
from
7d8b9ec to
d705eb3CompareJune 10, 2026 03:37
@jacekradkojacekradko
changed the title
refactor(shared): drop the pinned apiUrlFromPublishableKey return typedocs(shared): reframe the apiUrlFromPublishableKey return type rationaleJun 10, 2026
@jacekradko
jacekradko
merged commit b7cac0a
into
mainJun 11, 2026

50 checks passed

@jacekradko
jacekradko
deleted the

jacek/unpin-apiurl-return-type

branch
June 11, 2026 00:37
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@coderabbitaicoderabbitai[bot]coderabbitai[bot] left review comments
@wobsorianowobsorianowobsoriano approved these changes

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

2 participants

@jacekradko@wobsoriano

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs(shared): reframe the apiUrlFromPublishableKey return type rationale - #8794
Merged
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Jun 11, 2026
Merged
docs(shared): reframe the apiUrlFromPublishableKey return type rationale#8794
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Conversation
@jacekradko
@jacekradkojacekradko
commented
Jun 10, 2026•

edited by coderabbitai
Bot
Loading

Copy link


Copy Markdown

Contributor
Follow-up to #8793. The comment on apiUrlFromPublishableKey claimed the explicit return type exists because break-check thrashes on inferred union order; that stopped being true once the v0.2.0 pin landed the root fix (clerk/break-check#85). The annotation itself stays. As CodeRabbit pointed out, it matches the repo TypeScript guideline for public APIs, and it has to be the literal form: annotating with typeof CONST pulls a hashed _chunks/* import into the published d.ts (verified against the actual emit), which is the unresolvable-reference problem all over again.
So this just rewrites the comment to give the real, current reasons.
Summary by CodeRabbit
  • Chores
    • Updated internal documentation and code comments to clarify implementation details.
@changeset-bot
changeset-botBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

🦋 Changeset detected
Latest commit: d705eb3
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 0 packages
When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types
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
vercelBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.
ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreview, CommentJun 10, 2026 3:38am
Request Review
@coderabbitai
coderabbitaiBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
Review Change Stack
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: bf843b88-766a-48fd-8705-b605c8258f9b
📥 Commits
Reviewing files that changed from the base of the PR and between 7d8b9ec and d705eb3.
📒 Files selected for processing (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
✅ Files skipped from review due to trivial changes (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
📝 Walkthrough
Walkthrough
This PR documents the rationale for using explicit string-literal return types in apiUrlFromPublishableKey. The function's pre-export comment block was updated to explain the determinism requirement, and a changeset file was added to track this documentation change for release notes.
Changes
Explicit return type rationale documentation
Layer / File(s)Summary
Return type determinism rationale
packages/shared/src/apiUrlFromPublishableKey.ts, .changeset/apiurl-return-type-rationale.md		The comment block preceding apiUrlFromPublishableKey is updated to explain the explicit string-literal return type requirement for deterministic .d.ts emission, and a changeset entry documents this pattern for release notes.
Estimated code review effort
🎯 1 (Trivial) | ⏱️ ~3 minutes
Possibly related PRs
  • clerk/javascript#8783: Directly related—both PRs focus on the apiUrlFromPublishableKey return type annotation and its role in maintaining deterministic declaration emit.
Suggested reviewers
  • wobsoriano
Poem
🐰 A comment's path so clear and bright,

Explains why types must be just right,

String literals pinned for emit's delight,

Deterministic declarations—what a sight!

The changelog marks this rationale's flight.
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)
Check nameStatusExplanationResolution
Title check⚠️ WarningThe PR title mentions 'reframe the apiUrlFromPublishableKey return type rationale' which refers to updating documentation/comments about the return type, but the actual PR objective is to remove the pinned return-type annotation itself—a functional change, not just a rationale reframing.Align the title with the actual intent: 'refactor(shared): drop the pinned apiUrlFromPublishableKey return type' better reflects the substantive change being made.
✅ Passed checks (4 passed)
Check nameStatusExplanation
Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
✏️ Tip: You can configure your own custom pre-merge checks in the settings.
✨ Finishing Touches
📝 Generate docstrings
  •  Create stacked PR
  •  Commit on current branch
Comment @coderabbitai help to get the list of available commands and usage tips.
@pkg-pr-new
pkg-pr-newBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Open in StackBlitz
@clerk/astro
npm i https://pkg.pr.new/@clerk/astro@8794

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

commit: d705eb3
@github-actions
github-actionsBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
API Changes Report
Generated by Break Check on 2026-06-10T03:41:13.256Z
Summary
MetricCount
Packages analyzed19
Packages with changes0
🔴 Breaking changes0
🟡 Non-breaking changes0
🟢 Additions0
Note

Break Check could not snapshot 3 subpaths; the diff below excludes them.
  • @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/testing ./cypress: Symbol not found for identifier: Cypress
No API Changes Detected
All packages have stable APIs with no detected changes.
Report generated by Break Check
Last ran on d705eb3.
coderabbitai[bot]
coderabbitaiBot
reviewed
Jun 10, 2026
View reviewed changes
@coderabbitaicoderabbitaiBot
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1
🤖 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.
Inline comments:
In `@packages/shared/src/apiUrlFromPublishableKey.ts`:
- Line 17: Restore an explicit return type on the exported function
apiUrlFromPublishableKey: update its signature to include the correct return
type (e.g., string or the appropriate union type used elsewhere) so the public
API has an explicit TypeScript return annotation; locate the function
declaration "export const apiUrlFromPublishableKey = (publishableKey: string)
=>" and add the explicit return type after the parameter list to match
repository guidelines and existing usage.

🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
  •  Push a commit to this branch (recommended)
  •  Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 5f37ead0-2b07-40b0-8723-398024073fb5
📥 Commits
Reviewing files that changed from the base of the PR and between 400d10c and 7d8b9ec.
📒 Files selected for processing (2)
  • .changeset/unpin-apiurl-return-type.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
Comment threadpackages/shared/src/apiUrlFromPublishableKey.ts
Outdated

@jacekradko
jacekradkoforce-pushed
the
jacek/unpin-apiurl-return-type
branch
from
7d8b9ec to
d705eb3CompareJune 10, 2026 03:37
@jacekradkojacekradko
changed the title
refactor(shared): drop the pinned apiUrlFromPublishableKey return typedocs(shared): reframe the apiUrlFromPublishableKey return type rationaleJun 10, 2026
@jacekradko
jacekradko
merged commit b7cac0a
into
mainJun 11, 2026

50 checks passed

@jacekradko
jacekradko
deleted the

jacek/unpin-apiurl-return-type

branch
June 11, 2026 00:37
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@coderabbitaicoderabbitai[bot]coderabbitai[bot] left review comments
@wobsorianowobsorianowobsoriano approved these changes

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

2 participants

@jacekradko@wobsoriano

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
docs(shared): reframe the apiUrlFromPublishableKey return type rationale - #8794
Merged
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Jun 11, 2026
Merged
docs(shared): reframe the apiUrlFromPublishableKey return type rationale#8794
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Conversation
@jacekradko
@jacekradkojacekradko
commented
Jun 10, 2026•

edited by coderabbitai
Bot
Loading

Copy link


Copy Markdown

Contributor
Follow-up to #8793. The comment on apiUrlFromPublishableKey claimed the explicit return type exists because break-check thrashes on inferred union order; that stopped being true once the v0.2.0 pin landed the root fix (clerk/break-check#85). The annotation itself stays. As CodeRabbit pointed out, it matches the repo TypeScript guideline for public APIs, and it has to be the literal form: annotating with typeof CONST pulls a hashed _chunks/* import into the published d.ts (verified against the actual emit), which is the unresolvable-reference problem all over again.
So this just rewrites the comment to give the real, current reasons.
Summary by CodeRabbit
  • Chores
    • Updated internal documentation and code comments to clarify implementation details.
@changeset-bot
changeset-botBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

🦋 Changeset detected
Latest commit: d705eb3
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 0 packages
When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types
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
vercelBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.
ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreview, CommentJun 10, 2026 3:38am
Request Review
@coderabbitai
coderabbitaiBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
Review Change Stack
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: bf843b88-766a-48fd-8705-b605c8258f9b
📥 Commits
Reviewing files that changed from the base of the PR and between 7d8b9ec and d705eb3.
📒 Files selected for processing (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
✅ Files skipped from review due to trivial changes (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
📝 Walkthrough
Walkthrough
This PR documents the rationale for using explicit string-literal return types in apiUrlFromPublishableKey. The function's pre-export comment block was updated to explain the determinism requirement, and a changeset file was added to track this documentation change for release notes.
Changes
Explicit return type rationale documentation
Layer / File(s)Summary
Return type determinism rationale
packages/shared/src/apiUrlFromPublishableKey.ts, .changeset/apiurl-return-type-rationale.md		The comment block preceding apiUrlFromPublishableKey is updated to explain the explicit string-literal return type requirement for deterministic .d.ts emission, and a changeset entry documents this pattern for release notes.
Estimated code review effort
🎯 1 (Trivial) | ⏱️ ~3 minutes
Possibly related PRs
  • clerk/javascript#8783: Directly related—both PRs focus on the apiUrlFromPublishableKey return type annotation and its role in maintaining deterministic declaration emit.
Suggested reviewers
  • wobsoriano
Poem
🐰 A comment's path so clear and bright,

Explains why types must be just right,

String literals pinned for emit's delight,

Deterministic declarations—what a sight!

The changelog marks this rationale's flight.
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)
Check nameStatusExplanationResolution
Title check⚠️ WarningThe PR title mentions 'reframe the apiUrlFromPublishableKey return type rationale' which refers to updating documentation/comments about the return type, but the actual PR objective is to remove the pinned return-type annotation itself—a functional change, not just a rationale reframing.Align the title with the actual intent: 'refactor(shared): drop the pinned apiUrlFromPublishableKey return type' better reflects the substantive change being made.
✅ Passed checks (4 passed)
Check nameStatusExplanation
Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
✏️ Tip: You can configure your own custom pre-merge checks in the settings.
✨ Finishing Touches
📝 Generate docstrings
  •  Create stacked PR
  •  Commit on current branch
Comment @coderabbitai help to get the list of available commands and usage tips.
@pkg-pr-new
pkg-pr-newBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Open in StackBlitz
@clerk/astro
npm i https://pkg.pr.new/@clerk/astro@8794

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

commit: d705eb3
@github-actions
github-actionsBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
API Changes Report
Generated by Break Check on 2026-06-10T03:41:13.256Z
Summary
MetricCount
Packages analyzed19
Packages with changes0
🔴 Breaking changes0
🟡 Non-breaking changes0
🟢 Additions0
Note

Break Check could not snapshot 3 subpaths; the diff below excludes them.
  • @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/testing ./cypress: Symbol not found for identifier: Cypress
No API Changes Detected
All packages have stable APIs with no detected changes.
Report generated by Break Check
Last ran on d705eb3.
coderabbitai[bot]
coderabbitaiBot
reviewed
Jun 10, 2026
View reviewed changes
@coderabbitaicoderabbitaiBot
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1
🤖 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.
Inline comments:
In `@packages/shared/src/apiUrlFromPublishableKey.ts`:
- Line 17: Restore an explicit return type on the exported function
apiUrlFromPublishableKey: update its signature to include the correct return
type (e.g., string or the appropriate union type used elsewhere) so the public
API has an explicit TypeScript return annotation; locate the function
declaration "export const apiUrlFromPublishableKey = (publishableKey: string)
=>" and add the explicit return type after the parameter list to match
repository guidelines and existing usage.

🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
  •  Push a commit to this branch (recommended)
  •  Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 5f37ead0-2b07-40b0-8723-398024073fb5
📥 Commits
Reviewing files that changed from the base of the PR and between 400d10c and 7d8b9ec.
📒 Files selected for processing (2)
  • .changeset/unpin-apiurl-return-type.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
Comment threadpackages/shared/src/apiUrlFromPublishableKey.ts
Outdated

@jacekradko
jacekradkoforce-pushed
the
jacek/unpin-apiurl-return-type
branch
from
7d8b9ec to
d705eb3CompareJune 10, 2026 03:37
@jacekradkojacekradko
changed the title
refactor(shared): drop the pinned apiUrlFromPublishableKey return typedocs(shared): reframe the apiUrlFromPublishableKey return type rationaleJun 10, 2026
@jacekradko
jacekradko
merged commit b7cac0a
into
mainJun 11, 2026

50 checks passed

@jacekradko
jacekradko
deleted the

jacek/unpin-apiurl-return-type

branch
June 11, 2026 00:37
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@coderabbitaicoderabbitai[bot]coderabbitai[bot] left review comments
@wobsorianowobsorianowobsoriano approved these changes

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

2 participants

@jacekradko@wobsoriano

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs(shared): reframe the apiUrlFromPublishableKey return type rationale - #8794
Merged
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Jun 11, 2026
Merged
docs(shared): reframe the apiUrlFromPublishableKey return type rationale#8794
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Conversation
@jacekradko
@jacekradkojacekradko
commented
Jun 10, 2026•

edited by coderabbitai
Bot
Loading

Copy link


Copy Markdown

Contributor
Follow-up to #8793. The comment on apiUrlFromPublishableKey claimed the explicit return type exists because break-check thrashes on inferred union order; that stopped being true once the v0.2.0 pin landed the root fix (clerk/break-check#85). The annotation itself stays. As CodeRabbit pointed out, it matches the repo TypeScript guideline for public APIs, and it has to be the literal form: annotating with typeof CONST pulls a hashed _chunks/* import into the published d.ts (verified against the actual emit), which is the unresolvable-reference problem all over again.
So this just rewrites the comment to give the real, current reasons.
Summary by CodeRabbit
  • Chores
    • Updated internal documentation and code comments to clarify implementation details.
@changeset-bot
changeset-botBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

🦋 Changeset detected
Latest commit: d705eb3
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 0 packages
When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types
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
vercelBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.
ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreview, CommentJun 10, 2026 3:38am
Request Review
@coderabbitai
coderabbitaiBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
Review Change Stack
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: bf843b88-766a-48fd-8705-b605c8258f9b
📥 Commits
Reviewing files that changed from the base of the PR and between 7d8b9ec and d705eb3.
📒 Files selected for processing (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
✅ Files skipped from review due to trivial changes (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
📝 Walkthrough
Walkthrough
This PR documents the rationale for using explicit string-literal return types in apiUrlFromPublishableKey. The function's pre-export comment block was updated to explain the determinism requirement, and a changeset file was added to track this documentation change for release notes.
Changes
Explicit return type rationale documentation
Layer / File(s)Summary
Return type determinism rationale
packages/shared/src/apiUrlFromPublishableKey.ts, .changeset/apiurl-return-type-rationale.md		The comment block preceding apiUrlFromPublishableKey is updated to explain the explicit string-literal return type requirement for deterministic .d.ts emission, and a changeset entry documents this pattern for release notes.
Estimated code review effort
🎯 1 (Trivial) | ⏱️ ~3 minutes
Possibly related PRs
  • clerk/javascript#8783: Directly related—both PRs focus on the apiUrlFromPublishableKey return type annotation and its role in maintaining deterministic declaration emit.
Suggested reviewers
  • wobsoriano
Poem
🐰 A comment's path so clear and bright,

Explains why types must be just right,

String literals pinned for emit's delight,

Deterministic declarations—what a sight!

The changelog marks this rationale's flight.
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)
Check nameStatusExplanationResolution
Title check⚠️ WarningThe PR title mentions 'reframe the apiUrlFromPublishableKey return type rationale' which refers to updating documentation/comments about the return type, but the actual PR objective is to remove the pinned return-type annotation itself—a functional change, not just a rationale reframing.Align the title with the actual intent: 'refactor(shared): drop the pinned apiUrlFromPublishableKey return type' better reflects the substantive change being made.
✅ Passed checks (4 passed)
Check nameStatusExplanation
Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
✏️ Tip: You can configure your own custom pre-merge checks in the settings.
✨ Finishing Touches
📝 Generate docstrings
  •  Create stacked PR
  •  Commit on current branch
Comment @coderabbitai help to get the list of available commands and usage tips.
@pkg-pr-new
pkg-pr-newBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Open in StackBlitz
@clerk/astro
npm i https://pkg.pr.new/@clerk/astro@8794

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

commit: d705eb3
@github-actions
github-actionsBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
API Changes Report
Generated by Break Check on 2026-06-10T03:41:13.256Z
Summary
MetricCount
Packages analyzed19
Packages with changes0
🔴 Breaking changes0
🟡 Non-breaking changes0
🟢 Additions0
Note

Break Check could not snapshot 3 subpaths; the diff below excludes them.
  • @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/testing ./cypress: Symbol not found for identifier: Cypress
No API Changes Detected
All packages have stable APIs with no detected changes.
Report generated by Break Check
Last ran on d705eb3.
coderabbitai[bot]
coderabbitaiBot
reviewed
Jun 10, 2026
View reviewed changes
@coderabbitaicoderabbitaiBot
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1
🤖 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.
Inline comments:
In `@packages/shared/src/apiUrlFromPublishableKey.ts`:
- Line 17: Restore an explicit return type on the exported function
apiUrlFromPublishableKey: update its signature to include the correct return
type (e.g., string or the appropriate union type used elsewhere) so the public
API has an explicit TypeScript return annotation; locate the function
declaration "export const apiUrlFromPublishableKey = (publishableKey: string)
=>" and add the explicit return type after the parameter list to match
repository guidelines and existing usage.

🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
  •  Push a commit to this branch (recommended)
  •  Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 5f37ead0-2b07-40b0-8723-398024073fb5
📥 Commits
Reviewing files that changed from the base of the PR and between 400d10c and 7d8b9ec.
📒 Files selected for processing (2)
  • .changeset/unpin-apiurl-return-type.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
Comment threadpackages/shared/src/apiUrlFromPublishableKey.ts
Outdated

@jacekradko
jacekradkoforce-pushed
the
jacek/unpin-apiurl-return-type
branch
from
7d8b9ec to
d705eb3CompareJune 10, 2026 03:37
@jacekradkojacekradko
changed the title
refactor(shared): drop the pinned apiUrlFromPublishableKey return typedocs(shared): reframe the apiUrlFromPublishableKey return type rationaleJun 10, 2026
@jacekradko
jacekradko
merged commit b7cac0a
into
mainJun 11, 2026

50 checks passed

@jacekradko
jacekradko
deleted the

jacek/unpin-apiurl-return-type

branch
June 11, 2026 00:37
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@coderabbitaicoderabbitai[bot]coderabbitai[bot] left review comments
@wobsorianowobsorianowobsoriano approved these changes

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

2 participants

@jacekradko@wobsoriano

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs(shared): reframe the apiUrlFromPublishableKey return type rationale - #8794
Merged
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Jun 11, 2026
Merged
docs(shared): reframe the apiUrlFromPublishableKey return type rationale#8794
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Conversation
@jacekradko
@jacekradkojacekradko
commented
Jun 10, 2026•

edited by coderabbitai
Bot
Loading

Copy link


Copy Markdown

Contributor
Follow-up to #8793. The comment on apiUrlFromPublishableKey claimed the explicit return type exists because break-check thrashes on inferred union order; that stopped being true once the v0.2.0 pin landed the root fix (clerk/break-check#85). The annotation itself stays. As CodeRabbit pointed out, it matches the repo TypeScript guideline for public APIs, and it has to be the literal form: annotating with typeof CONST pulls a hashed _chunks/* import into the published d.ts (verified against the actual emit), which is the unresolvable-reference problem all over again.
So this just rewrites the comment to give the real, current reasons.
Summary by CodeRabbit
  • Chores
    • Updated internal documentation and code comments to clarify implementation details.
@changeset-bot
changeset-botBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

🦋 Changeset detected
Latest commit: d705eb3
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 0 packages
When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types
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
vercelBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.
ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreview, CommentJun 10, 2026 3:38am
Request Review
@coderabbitai
coderabbitaiBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
Review Change Stack
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: bf843b88-766a-48fd-8705-b605c8258f9b
📥 Commits
Reviewing files that changed from the base of the PR and between 7d8b9ec and d705eb3.
📒 Files selected for processing (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
✅ Files skipped from review due to trivial changes (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
📝 Walkthrough
Walkthrough
This PR documents the rationale for using explicit string-literal return types in apiUrlFromPublishableKey. The function's pre-export comment block was updated to explain the determinism requirement, and a changeset file was added to track this documentation change for release notes.
Changes
Explicit return type rationale documentation
Layer / File(s)Summary
Return type determinism rationale
packages/shared/src/apiUrlFromPublishableKey.ts, .changeset/apiurl-return-type-rationale.md		The comment block preceding apiUrlFromPublishableKey is updated to explain the explicit string-literal return type requirement for deterministic .d.ts emission, and a changeset entry documents this pattern for release notes.
Estimated code review effort
🎯 1 (Trivial) | ⏱️ ~3 minutes
Possibly related PRs
  • clerk/javascript#8783: Directly related—both PRs focus on the apiUrlFromPublishableKey return type annotation and its role in maintaining deterministic declaration emit.
Suggested reviewers
  • wobsoriano
Poem
🐰 A comment's path so clear and bright,

Explains why types must be just right,

String literals pinned for emit's delight,

Deterministic declarations—what a sight!

The changelog marks this rationale's flight.
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)
Check nameStatusExplanationResolution
Title check⚠️ WarningThe PR title mentions 'reframe the apiUrlFromPublishableKey return type rationale' which refers to updating documentation/comments about the return type, but the actual PR objective is to remove the pinned return-type annotation itself—a functional change, not just a rationale reframing.Align the title with the actual intent: 'refactor(shared): drop the pinned apiUrlFromPublishableKey return type' better reflects the substantive change being made.
✅ Passed checks (4 passed)
Check nameStatusExplanation
Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
✏️ Tip: You can configure your own custom pre-merge checks in the settings.
✨ Finishing Touches
📝 Generate docstrings
  •  Create stacked PR
  •  Commit on current branch
Comment @coderabbitai help to get the list of available commands and usage tips.
@pkg-pr-new
pkg-pr-newBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Open in StackBlitz
@clerk/astro
npm i https://pkg.pr.new/@clerk/astro@8794

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

commit: d705eb3
@github-actions
github-actionsBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
API Changes Report
Generated by Break Check on 2026-06-10T03:41:13.256Z
Summary
MetricCount
Packages analyzed19
Packages with changes0
🔴 Breaking changes0
🟡 Non-breaking changes0
🟢 Additions0
Note

Break Check could not snapshot 3 subpaths; the diff below excludes them.
  • @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/testing ./cypress: Symbol not found for identifier: Cypress
No API Changes Detected
All packages have stable APIs with no detected changes.
Report generated by Break Check
Last ran on d705eb3.
coderabbitai[bot]
coderabbitaiBot
reviewed
Jun 10, 2026
View reviewed changes
@coderabbitaicoderabbitaiBot
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1
🤖 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.
Inline comments:
In `@packages/shared/src/apiUrlFromPublishableKey.ts`:
- Line 17: Restore an explicit return type on the exported function
apiUrlFromPublishableKey: update its signature to include the correct return
type (e.g., string or the appropriate union type used elsewhere) so the public
API has an explicit TypeScript return annotation; locate the function
declaration "export const apiUrlFromPublishableKey = (publishableKey: string)
=>" and add the explicit return type after the parameter list to match
repository guidelines and existing usage.

🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
  •  Push a commit to this branch (recommended)
  •  Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 5f37ead0-2b07-40b0-8723-398024073fb5
📥 Commits
Reviewing files that changed from the base of the PR and between 400d10c and 7d8b9ec.
📒 Files selected for processing (2)
  • .changeset/unpin-apiurl-return-type.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
Comment threadpackages/shared/src/apiUrlFromPublishableKey.ts
Outdated

@jacekradko
jacekradkoforce-pushed
the
jacek/unpin-apiurl-return-type
branch
from
7d8b9ec to
d705eb3CompareJune 10, 2026 03:37
@jacekradkojacekradko
changed the title
refactor(shared): drop the pinned apiUrlFromPublishableKey return typedocs(shared): reframe the apiUrlFromPublishableKey return type rationaleJun 10, 2026
@jacekradko
jacekradko
merged commit b7cac0a
into
mainJun 11, 2026

50 checks passed

@jacekradko
jacekradko
deleted the

jacek/unpin-apiurl-return-type

branch
June 11, 2026 00:37
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@coderabbitaicoderabbitai[bot]coderabbitai[bot] left review comments
@wobsorianowobsorianowobsoriano approved these changes

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

2 participants

@jacekradko@wobsoriano

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
docs(shared): reframe the apiUrlFromPublishableKey return type rationale - #8794
Merged
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Jun 11, 2026
Merged
docs(shared): reframe the apiUrlFromPublishableKey return type rationale#8794
jacekradko merged 1 commit into
mainfrom 
jacek/unpin-apiurl-return-type
Conversation
@jacekradko
@jacekradkojacekradko
commented
Jun 10, 2026•

edited by coderabbitai
Bot
Loading

Copy link


Copy Markdown

Contributor
Follow-up to #8793. The comment on apiUrlFromPublishableKey claimed the explicit return type exists because break-check thrashes on inferred union order; that stopped being true once the v0.2.0 pin landed the root fix (clerk/break-check#85). The annotation itself stays. As CodeRabbit pointed out, it matches the repo TypeScript guideline for public APIs, and it has to be the literal form: annotating with typeof CONST pulls a hashed _chunks/* import into the published d.ts (verified against the actual emit), which is the unresolvable-reference problem all over again.
So this just rewrites the comment to give the real, current reasons.
Summary by CodeRabbit
  • Chores
    • Updated internal documentation and code comments to clarify implementation details.
@changeset-bot
changeset-botBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

🦋 Changeset detected
Latest commit: d705eb3
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 0 packages
When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types
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
vercelBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.
ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreview, CommentJun 10, 2026 3:38am
Request Review
@coderabbitai
coderabbitaiBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
Review Change Stack
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: bf843b88-766a-48fd-8705-b605c8258f9b
📥 Commits
Reviewing files that changed from the base of the PR and between 7d8b9ec and d705eb3.
📒 Files selected for processing (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
✅ Files skipped from review due to trivial changes (2)
  • .changeset/apiurl-return-type-rationale.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
📝 Walkthrough
Walkthrough
This PR documents the rationale for using explicit string-literal return types in apiUrlFromPublishableKey. The function's pre-export comment block was updated to explain the determinism requirement, and a changeset file was added to track this documentation change for release notes.
Changes
Explicit return type rationale documentation
Layer / File(s)Summary
Return type determinism rationale
packages/shared/src/apiUrlFromPublishableKey.ts, .changeset/apiurl-return-type-rationale.md		The comment block preceding apiUrlFromPublishableKey is updated to explain the explicit string-literal return type requirement for deterministic .d.ts emission, and a changeset entry documents this pattern for release notes.
Estimated code review effort
🎯 1 (Trivial) | ⏱️ ~3 minutes
Possibly related PRs
  • clerk/javascript#8783: Directly related—both PRs focus on the apiUrlFromPublishableKey return type annotation and its role in maintaining deterministic declaration emit.
Suggested reviewers
  • wobsoriano
Poem
🐰 A comment's path so clear and bright,

Explains why types must be just right,

String literals pinned for emit's delight,

Deterministic declarations—what a sight!

The changelog marks this rationale's flight.
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)
Check nameStatusExplanationResolution
Title check⚠️ WarningThe PR title mentions 'reframe the apiUrlFromPublishableKey return type rationale' which refers to updating documentation/comments about the return type, but the actual PR objective is to remove the pinned return-type annotation itself—a functional change, not just a rationale reframing.Align the title with the actual intent: 'refactor(shared): drop the pinned apiUrlFromPublishableKey return type' better reflects the substantive change being made.
✅ Passed checks (4 passed)
Check nameStatusExplanation
Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
✏️ Tip: You can configure your own custom pre-merge checks in the settings.
✨ Finishing Touches
📝 Generate docstrings
  •  Create stacked PR
  •  Commit on current branch
Comment @coderabbitai help to get the list of available commands and usage tips.
@pkg-pr-new
pkg-pr-newBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Open in StackBlitz
@clerk/astro
npm i https://pkg.pr.new/@clerk/astro@8794

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

commit: d705eb3
@github-actions
github-actionsBot
commented
Jun 10, 2026•

edited

Loading

Copy link


Copy Markdown

Contributor
API Changes Report
Generated by Break Check on 2026-06-10T03:41:13.256Z
Summary
MetricCount
Packages analyzed19
Packages with changes0
🔴 Breaking changes0
🟡 Non-breaking changes0
🟢 Additions0
Note

Break Check could not snapshot 3 subpaths; the diff below excludes them.
  • @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
  • @clerk/testing ./cypress: Symbol not found for identifier: Cypress
No API Changes Detected
All packages have stable APIs with no detected changes.
Report generated by Break Check
Last ran on d705eb3.
coderabbitai[bot]
coderabbitaiBot
reviewed
Jun 10, 2026
View reviewed changes
@coderabbitaicoderabbitaiBot
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1
🤖 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.
Inline comments:
In `@packages/shared/src/apiUrlFromPublishableKey.ts`:
- Line 17: Restore an explicit return type on the exported function
apiUrlFromPublishableKey: update its signature to include the correct return
type (e.g., string or the appropriate union type used elsewhere) so the public
API has an explicit TypeScript return annotation; locate the function
declaration "export const apiUrlFromPublishableKey = (publishableKey: string)
=>" and add the explicit return type after the parameter list to match
repository guidelines and existing usage.

🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
  •  Push a commit to this branch (recommended)
  •  Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 5f37ead0-2b07-40b0-8723-398024073fb5
📥 Commits
Reviewing files that changed from the base of the PR and between 400d10c and 7d8b9ec.
📒 Files selected for processing (2)
  • .changeset/unpin-apiurl-return-type.md
  • packages/shared/src/apiUrlFromPublishableKey.ts
Comment threadpackages/shared/src/apiUrlFromPublishableKey.ts
Outdated

@jacekradko
jacekradkoforce-pushed
the
jacek/unpin-apiurl-return-type
branch
from
7d8b9ec to
d705eb3CompareJune 10, 2026 03:37
@jacekradkojacekradko
changed the title
refactor(shared): drop the pinned apiUrlFromPublishableKey return typedocs(shared): reframe the apiUrlFromPublishableKey return type rationaleJun 10, 2026
@jacekradko
jacekradko
merged commit b7cac0a
into
mainJun 11, 2026

50 checks passed

@jacekradko
jacekradko
deleted the

jacek/unpin-apiurl-return-type

branch
June 11, 2026 00:37
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@coderabbitaicoderabbitai[bot]coderabbitai[bot] left review comments
@wobsorianowobsorianowobsoriano approved these changes

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

2 participants

@jacekradko@wobsoriano