feat(clerk-js,react): Add js prop for bundled clerk-js support

[jacekradko]

Summary

• Introduces a js prop for ClerkProvider that mirrors the ui prop approach
• Allows bundling clerk-js with the application instead of loading from CDN
• Server-safe via react-server conditional export

Changes

@clerk/clerk-js:

• New ./bundled export with branded js object containing ClerkJS constructor
• New ./entry export for dynamic imports
• New ./internal export for the Js type
• react-server condition exports server-safe marker (no browser code)

@clerk/react:

• Added js prop to ClerkProviderProps
• Updated isomorphicClerk to handle js prop loading

Usage

import { js } from '@clerk/clerk-js/bundled';

<ClerkProvider js={js}>
  ...
</ClerkProvider>

Test plan

• Verify pnpm build passes for clerk-js and react packages
• Test bundled import in a Next.js app (both client and server components)
• Verify CDN fallback still works when js prop is omitted

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Bundle Clerk JS via a new js prop across providers and frameworks; client will resolve bundled JS when provided.
  • New @clerk/clerk-js package offering bundled and server-safe JS exports.

• Configuration

  • Providers accept both ui and js options.
  • Added PUBLIC_CLERK_SKIP_JS_CDN env var; script inclusion/preload is now conditional.

• Tests

  • Added tests validating public exports and API shape for bundled and server JS.

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 7f4710f

[coderabbitai]

Note

Reviews paused

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

Use the following commands to manage reviews:

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

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new package @clerk/clerk-js with ESM exports ("bundled", "entry", "internal"), runtime-branded Js markers, server-safe and bundled entry modules, and tests validating public exports. Introduces an optional js prop to provider APIs (React, Next.js, Vue, Astro) and client-side lazy resolution to obtain ClerkJS when server exports omit the constructor. Astro gets PUBLIC_CLERK_SKIP_JS_CDN and adjusted script/preload emission. Tooling updates: tsdown config, ESM build step, declaration inclusion, and package.json export/script changes for clerk-js.

Possibly related PRs

• clerk/javascript PR 7664: Implements branded marker and client-side lazy resolution patterns for the UI provider surface, overlapping provider resolution and branded-object handling.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately describes the main change: adding a js prop to support bundling clerk-js, mirroring the existing ui prop pattern.

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

---

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

[coderabbitai]

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/server/build-clerk-hotload-script.ts (1)

6-83: ⚠️ Potential issue | 🟠 Major

Add explicit return type and JSDoc for the exported function.

This exported API lacks the required explicit return type and comprehensive JSDoc. Please add them to satisfy the TypeScript and public API documentation guidelines.

✅ Suggested fix

+/**
+ * Builds the Clerk hotload markup (script and/or preload link).
+ *
+ * `@param` locals - Astro API context locals.
+ * `@returns` HTML string containing the required tags.
+ * `@example`
+ * const html = buildClerkHotloadScript(ctx.locals);
+ */
-function buildClerkHotloadScript(locals: APIContext['locals']) {
+function buildClerkHotloadScript(locals: APIContext['locals']): string {

🧹 Nitpick comments (1)

packages/clerk-js/src/server.ts (1)

12-21: JSDoc example may be misleading for server export.

The example shows importing from @clerk/clerk-js/bundled, but this file is server.ts which is resolved via conditional exports for react-server. Users importing directly won't use this path explicitly. Consider updating the example to clarify the automatic resolution or showing the actual import path that resolves to this module.