Skip to content

feat(shared): make clerkJSUrl, clerkJSVersion, clerkUIUrl internal#7879

Open
jacekradko wants to merge 10 commits intomainfrom
jacek/remove-clerk-ui-version
Open

feat(shared): make clerkJSUrl, clerkJSVersion, clerkUIUrl internal#7879
jacekradko wants to merge 10 commits intomainfrom
jacek/remove-clerk-ui-version

Conversation

@jacekradko
Copy link
Member

@jacekradko jacekradko commented Feb 18, 2026

Summary

  • Rename clerkJSUrl, clerkJSVersion, clerkUIUrl, and clerkUIVersion to __internal_clerkJSUrl, __internal_clerkJSVersion, __internal_clerkUIUrl, and __internal_clerkUIVersion on IsomorphicClerkOptions
  • Hide internal script props from consumer-facing types (ClerkProviderProps, Vue PluginOptions, Astro AstroClerkIntegrationParams) using Omit<..., keyof InternalClerkScriptProps> — these props no longer appear in autocomplete
  • Export InternalClerkProvider from @clerk/react/internal with wider type that accepts the internal script props
  • Switch all framework SDKs (@clerk/nextjs, @clerk/react-router, @clerk/tanstack-react-start, @clerk/expo, @clerk/chrome-extension) to use InternalClerkProvider
  • Update @clerk/astro, @clerk/nuxt, and @clerk/vue types to hide internal props from consumers while preserving internal usage
  • Add migration codemod to @clerk/upgrade for the prop rename
  • Internal variable names (env reading, wire format, constants) remain unchanged

Checklist

  • pnpm build passes (21/21 packages)
  • @clerk/shared tests pass (976 tests)
  • @clerk/react tests pass (370 tests)
  • @clerk/nextjs tests pass (389 tests)
  • @clerk/react-router tests pass (23 tests)
  • @clerk/astro tests pass (2 tests)
  • @clerk/tanstack-react-start tests pass (16 tests)
  • Only intended files changed (git diff main --stat)

…xt): remove clerkUIVersion and deprecate clerkJSVersion

Remove the `clerkUIVersion` prop from all SDKs and deprecate the
`clerkJSVersion` prop with @deprecated JSDoc annotations.
…xt): rename clerkJSUrl, clerkJSVersion, clerkUIUrl to __internal_ prefix
@changeset-bot
Copy link

changeset-bot bot commented Feb 18, 2026

🦋 Changeset detected

Latest commit: f0b02fc

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

This PR includes changesets to release 20 packages
Name Type
@clerk/shared Minor
@clerk/nextjs Minor
@clerk/astro Minor
@clerk/react-router Minor
@clerk/tanstack-react-start Minor
@clerk/express Minor
@clerk/nuxt Minor
@clerk/agent-toolkit Patch
@clerk/backend Patch
@clerk/chrome-extension Patch
@clerk/clerk-js Patch
@clerk/expo-passkeys Patch
@clerk/expo Patch
@clerk/fastify Patch
@clerk/localizations Patch
@clerk/msw Patch
@clerk/react Patch
@clerk/testing Patch
@clerk/ui Patch
@clerk/vue Patch

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

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

@vercel
Copy link

vercel bot commented Feb 18, 2026

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

Project Deployment Actions Updated (UTC)
clerk-js-sandbox Ready Ready Preview, Comment Feb 20, 2026 2:01am

Request Review

@pkg-pr-new
Copy link

pkg-pr-new bot commented Feb 18, 2026

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: f0b02fc

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Feb 18, 2026

Note

Reviews paused

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

Use the following commands to manage reviews:

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

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

This pull request renames four UI configuration properties from public to internal-only across the SDKs: clerkJSUrl, clerkJSVersion, clerkUIUrl, and clerkUIVersion__internal_clerkJSUrl, __internal_clerkJSVersion, __internal_clerkUIUrl, and __internal_clerkUIVersion. Changes touch type definitions, runtime code, tests, integration templates, a codemod and its fixtures, and upgrade configuration across multiple packages. JSDoc/internal annotations mark the new keys as internal and codemods/tests cover automated migration.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately describes the main change: converting clerkJSUrl, clerkJSVersion, and clerkUIUrl from public to internal props across the Clerk SDK.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.

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


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

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

Caution

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

⚠️ Outside diff range comments (1)
packages/astro/src/integration/create-integration.ts (1)

22-66: ⚠️ Potential issue | 🟠 Major

Missing env mapping for __internal_clerkUIUrl parameter

The __internal_clerkUIUrl parameter is defined in AstroClerkIntegrationParams and used in build-clerk-hotload-script, but it's never extracted from params or mapped to the PUBLIC_CLERK_UI_URL env variable in create-integration.ts. This inconsistency with how __internal_clerkJSUrl and __internal_clerkJSVersion are handled breaks UI URL overrides passed through integration params—the server-side code won't have access to the custom UI URL.

Add the missing extraction and env mapping:

    const clerkJSUrl = (params as any)?.__internal_clerkJSUrl as string | undefined;
    const clerkJSVersion = (params as any)?.__internal_clerkJSVersion as string | undefined;
+   const clerkUIUrl = (params as any)?.__internal_clerkUIUrl as string | undefined;
    const prefetchUI = (params as any)?.prefetchUI as boolean | undefined;
                ...buildEnvVarFromOption(clerkJSUrl, 'PUBLIC_CLERK_JS_URL'),
                ...buildEnvVarFromOption(clerkJSVersion, 'PUBLIC_CLERK_JS_VERSION'),
+               ...buildEnvVarFromOption(clerkUIUrl, 'PUBLIC_CLERK_UI_URL'),
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/astro/src/integration/create-integration.ts` around lines 22 - 66,
The integration never extracts the __internal_clerkUIUrl param nor maps it to an
env var, so the server cannot see UI URL overrides; add a const like clerkUIUrl
= (params as any)?.__internal_clerkUIUrl as string | undefined alongside
clerkJSUrl/clerkJSVersion, then include ...buildEnvVarFromOption(clerkUIUrl,
'PUBLIC_CLERK_UI_URL') in the define block inside the 'astro:config:setup' hook
(near the other buildEnvVarFromOption calls) so the value is available
server-side for code that reads PUBLIC_CLERK_UI_URL (e.g.,
build-clerk-hotload-script).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@packages/astro/src/integration/create-integration.ts`:
- Around line 22-66: The integration never extracts the __internal_clerkUIUrl
param nor maps it to an env var, so the server cannot see UI URL overrides; add
a const like clerkUIUrl = (params as any)?.__internal_clerkUIUrl as string |
undefined alongside clerkJSUrl/clerkJSVersion, then include
...buildEnvVarFromOption(clerkUIUrl, 'PUBLIC_CLERK_UI_URL') in the define block
inside the 'astro:config:setup' hook (near the other buildEnvVarFromOption
calls) so the value is available server-side for code that reads
PUBLIC_CLERK_UI_URL (e.g., build-clerk-hotload-script).

@jacekradko jacekradko changed the title feat: make clerkJSUrl, clerkJSVersion, clerkUIUrl, clerkUIVersion internal feat(shared): make clerkJSUrl, clerkJSVersion, clerkUIUrl internal Feb 18, 2026
…rop names

Update all ClerkProvider usages in integration test templates and
playground to use the renamed __internal_clerkJSUrl, __internal_clerkUIUrl,
and __internal_clerkJSVersion props. Also deduplicate pnpm-lock.yaml.
Remove @deprecated annotations from internal props and add a jscodeshift
codemod to rename clerkJSUrl, clerkJSVersion, clerkUIUrl, clerkUIVersion
to their __internal_ prefixed equivalents. Update changesets to reflect
full removal rather than deprecation.
Omit __internal_clerkJSUrl, __internal_clerkJSVersion, __internal_clerkUIUrl,
and __internal_clerkUIVersion from consumer-facing ClerkProviderProps and
framework SDK types. These props are now only accessible via
InternalClerkProvider exported from @clerk/react/internal.

- Add InternalClerkScriptProps type to @clerk/shared
- Narrow ClerkProviderProps in @clerk/react via Omit
- Export InternalClerkProvider from @clerk/react/internal with wider type
- Switch all framework SDKs to use InternalClerkProvider
- Clean up Vue PluginOptions, Astro, and Nuxt types
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

Comments