fix(shared): use @clerk/ui package version for UI script URL

[nikosdouvlis]

Why this change was needed:
The clerkUiScriptUrl function was incorrectly using JS_PACKAGE_VERSION (from @clerk/clerk-js) as the fallback version when no explicit version was provided. This meant @clerk/ui scripts would be loaded using @clerk/clerk-js's version (e.g., @clerk/ui@5) instead of @clerk/ui's own version (e.g., @clerk/ui@0), causing potential version mismatches.

What changed:
Added UI_PACKAGE_VERSION build constant that reads from @clerk/ui's package.json and updated clerkUiScriptUrl to use it as the fallback instead of JS_PACKAGE_VERSION.

Description

Checklist

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

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• Chores

  • UI script loading now uses a dedicated UI package version identifier so UI assets are tracked separately from the main JS package.
  • Exposes a UI package version constant in runtime/test environments to ensure consistent version resolution.

• Tests

  • Updated tests to validate UI and JS packages use independent version values.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 62ed71b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

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

Click here to learn what changesets are, and how to add one.

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

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Dec 9, 2025 10:24pm

[coderabbitai]

Walkthrough

Introduces a new global constant UI_PACKAGE_VERSION sourced from the UI package.json and propagated into TypeScript globals, build definitions, runtime code usage, and test setup; tests and URL construction were updated to use this UI-specific version.

Changes

Cohort / File(s)	Summary
TypeScript Declarations packages/shared/global.d.ts	Added declare const UI_PACKAGE_VERSION: string
Build Configuration packages/shared/tsdown.config.mts	Imported ../ui/package.json and added UI_PACKAGE_VERSION to the build define options (sourced from clerkUiPackage.version)
Runtime Code packages/shared/src/loadClerkJsScript.ts	Updated UI script URL construction to pass UI_PACKAGE_VERSION into versionSelector
Tests & Setup packages/shared/vitest.setup.mts, packages/shared/src/__tests__/loadClerkJsScript.spec.ts	Exposed UI_PACKAGE_VERSION on globalThis (test setup) and updated tests to assert UI URLs use UI_PACKAGE_VERSION (added uiPackageMajorVersion checks)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Pay attention to:
  • Correct import and JSON typing of ../ui/package.json in tsdown.config.mts
  • Proper exposure and typing of UI_PACKAGE_VERSION in global.d.ts
  • That loadClerkJsScript.ts uses the UI constant only for UI URLs and does not affect JS package URL logic
  • Test updates in loadClerkJsScript.spec.ts for independent UI vs JS version assertions

Poem

🐇 I nibble bytes and hop on keys,
UI version carried on the breeze.
From package.json to global cheer,
A rabbit stamps the new release near. 🎉

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: introducing a new UI_PACKAGE_VERSION build constant and using it for UI script URL generation instead of JS_PACKAGE_VERSION, directly addressing the version mismatch problem.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch nikos/fix-ui-pkg-version

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 5cfc34e and 62ed71b.

📒 Files selected for processing (5)

• packages/shared/global.d.ts (1 hunks)
• packages/shared/src/__tests__/loadClerkJsScript.spec.ts (4 hunks)
• packages/shared/src/loadClerkJsScript.ts (1 hunks)
• packages/shared/tsdown.config.mts (2 hunks)
• packages/shared/vitest.setup.mts (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (5)

• packages/shared/src/loadClerkJsScript.ts
• packages/shared/src/tests/loadClerkJsScript.spec.ts
• packages/shared/vitest.setup.mts
• packages/shared/tsdown.config.mts
• packages/shared/global.d.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (28)

• GitHub Check: Publish with pkg-pr-new
• GitHub Check: Unit Tests (shared, clerk-js, RQ)
• GitHub Check: Unit Tests (**)
• GitHub Check: Static analysis
• GitHub Check: Integration Tests (quickstart, chrome, 15)
• GitHub Check: Integration Tests (quickstart, chrome, 16)
• GitHub Check: Integration Tests (nextjs, chrome, 16, RQ)
• GitHub Check: Integration Tests (machine, chrome, RQ)
• GitHub Check: Integration Tests (custom, chrome)
• GitHub Check: Integration Tests (vue, chrome)
• GitHub Check: Integration Tests (nextjs, chrome, 15)
• GitHub Check: Integration Tests (react-router, chrome)
• GitHub Check: Integration Tests (nextjs, chrome, 16)
• GitHub Check: Integration Tests (nuxt, chrome)
• GitHub Check: Integration Tests (billing, chrome)
• GitHub Check: Integration Tests (billing, chrome, RQ)
• GitHub Check: Integration Tests (machine, chrome)
• GitHub Check: Integration Tests (sessions, chrome)
• GitHub Check: Integration Tests (handshake:staging, chrome)
• GitHub Check: Integration Tests (astro, chrome)
• GitHub Check: Integration Tests (tanstack-react-start, chrome)
• GitHub Check: Integration Tests (localhost, chrome)
• GitHub Check: Integration Tests (ap-flows, chrome)
• GitHub Check: Integration Tests (handshake, chrome)
• GitHub Check: Integration Tests (generic, chrome)
• GitHub Check: Integration Tests (sessions:staging, chrome)
• GitHub Check: Integration Tests (express, chrome)
• GitHub Check: Analyze (javascript-typescript)

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 62ed71b