fix(react): make ClerkProvider publishableKey optional by SarahSoutoul · Pull Request #9314 · clerk/javascript

SarahSoutoul · 2026-08-03T07:35:18Z

Description

clerk/javascript#7634 added the runtime fallback that allows @clerk/react to read VITE_CLERK_PUBLISHABLE_KEY or CLERK_PUBLISHABLE_KEY when publishableKey isn't passed to <ClerkProvider>. That PR also updated the React Vite templates to omit the explicit prop.

However, the corresponding public type was not updated. ClerkProviderProps continued to inherit the required publishableKey: string field from IsomorphicClerkOptions.

As a result, applications using the environment-variable fallback work correctly at runtime, but TypeScript incorrectly reports that the publishableKey prop is missing.

This PR makes publishableKey optional specifically in ClerkProviderProps, aligning the public type with the runtime behavior introduced by #7634. It also updates the type tests to cover using <ClerkProvider> without an explicit key.

The focused React tests pass with no type errors, and the generated declaration exposes publishableKey?: string.

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

changeset-bot · 2026-08-03T07:35:23Z

🦋 Changeset detected

Latest commit: 9409e1f

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

This PR includes changesets to release 7 packages

Name	Type
@clerk/react	Patch
@clerk/chrome-extension	Patch
@clerk/electron	Patch
@clerk/expo	Patch
@clerk/nextjs	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	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 · 2026-08-03T07:35:24Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 4, 2026 6:54am
swingset	Ready	Preview	Aug 4, 2026 6:54am

pkg-pr-new · 2026-08-03T07:38:32Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9314

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 9409e1f

github-actions · 2026-08-03T07:39:19Z

API Changes Report

Generated by Break Check on 2026-08-04T06:54:35.737Z

Summary

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

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

@clerk/react

Current version: 6.12.10
Recommended bump: MINOR → 6.13.0

Subpath `.`

🟡 Non-breaking Changes (1)

Modified: `ClerkProviderProps`

- type ClerkProviderProps<TUi extends Ui = Ui> = Omit<IsomorphicClerkOptions, 'appearance' | keyof InternalClerkScriptProps> & {
+ type ClerkProviderProps<TUi extends Ui = Ui> = Omit<IsomorphicClerkOptions, 'appearance' | 'publishableKey' | keyof InternalClerkScriptProps> & {
    children: React$1.ReactNode;
+   publishableKey?: string;
    initialState?: InitialState;
    __internal_bypassMissingPublishableKey?: boolean;
    appearance?: ExtractAppearanceType<TUi, Appearance>;
// ... 2 unchanged lines elided ...

Static analyzer: Breaking change in type alias ClerkProviderProps: Type changed: !Omit:type<import("@clerk/shared").IsomorphicClerkOptions,'appearance'|keyof import("@clerk/shared").InternalClerkScrip… → !Omit:type<import("@clerk/shared").IsomorphicClerkOptions,'appearance'|'publishableKey'|keyof import("@clerk/shared").I…

🤖 AI review (reclassified as non-breaking) (85%): The change removes publishableKey from the Omit (where it was excluded from the spread) and re-adds it as an explicit optional publishableKey?: string property. The net effect is that publishableKey goes from being absent in the type (omitted out) to being present as an optional field. No previously-accepted consumer code is invalidated: callers who didn't pass it still don't need to, and the structural shape is at least as permissive as before. Adding a new optional property to an input type is non-breaking per rule 9.

Subpath `./types`

🟡 Non-breaking Changes (1)

Modified: `ClerkProviderProps`

- type ClerkProviderProps<TUi extends Ui = Ui> = Omit<IsomorphicClerkOptions, 'appearance' | keyof InternalClerkScriptProps> & {
+ type ClerkProviderProps<TUi extends Ui = Ui> = Omit<IsomorphicClerkOptions, 'appearance' | 'publishableKey' | keyof InternalClerkScriptProps> & {
    children: React$1.ReactNode;
+   publishableKey?: string;
    initialState?: InitialState;
    __internal_bypassMissingPublishableKey?: boolean;
    appearance?: ExtractAppearanceType<TUi, Appearance>;
// ... 2 unchanged lines elided ...

Static analyzer: Breaking change in type alias ClerkProviderProps: Type changed: !Omit:type<import("@clerk/shared").IsomorphicClerkOptions,'appearance'|keyof import("@clerk/shared").InternalClerkScrip… → !Omit:type<import("@clerk/shared").IsomorphicClerkOptions,'appearance'|'publishableKey'|keyof import("@clerk/shared").I…

🤖 AI review (reclassified as non-breaking) (85%): The change omits publishableKey from IsomorphicClerkOptions and re-adds it as an explicit optional string field (publishableKey?: string). If publishableKey was required in IsomorphicClerkOptions, this makes it optional in ClerkProviderProps (non-breaking for callers who already provided it, and now callers who didn't are also fine). If it was already optional, the structural shape is preserved. Either way, no previously well-typed consumer code that passes ClerkProviderProps is broken: the field is still accepted and remains optional.

Report generated by Break Check

_{Last ran on 9409e1f.}

coderabbitai · 2026-08-03T07:39:41Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 7ec5f5c5-d579-4651-9799-df9ec0476611

📥 Commits

Reviewing files that changed from the base of the PR and between f12c7dd and 7fccba0.

📒 Files selected for processing (2)

packages/chrome-extension/src/react/ClerkProvider.tsx
packages/chrome-extension/src/react/__tests__/ClerkProvider.test.tsx

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)

📝 Walkthrough

Walkthrough

ClerkProviderProps now allows publishableKey to be omitted and documents environment-variable fallbacks. Chrome Extension provider props require an explicit publishableKey. Type tests cover both contracts. A patch changeset records the React update.

Estimated code review effort: 2 (Simple) | ~15 minutes

Suggested reviewers: brkalow, manovotny, wobsoriano

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: making the React ClerkProvider publishableKey optional.
Description check	✅ Passed	The description accurately explains the runtime fallback, type correction, tests, and Chrome extension exception.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

❤️ Share

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

Making publishableKey optional in @clerk/react's ClerkProviderProps propagated to @clerk/chrome-extension, whose provider intersects the base type without redeclaring the field. The extension has no env-var fallback and asserts the key at runtime, so omit-and-redeclare it as required (matching the other SDK wrappers) and add a type regression test. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

manovotny · 2026-08-03T22:25:27Z

Pushed a fix directly in 7fccba0.

Making publishableKey optional in @clerk/react leaked into @clerk/chrome-extension, whose provider intersects the base props without redeclaring the field. Extensions have no env-var fallback and assert the key at runtime, so a user could drop publishableKey, get no type error, and hit a runtime throw.

Omit and redeclare publishableKey: string on ChromeExtensionClerkProviderProps so it stays required — the same pattern the Next.js, React Router, TanStack, Expo, and Electron wrappers already use.
Added a type test so it can't silently regress.
No changeset: @clerk/chrome-extension already gets a patch bump as a dependent of this PR's @clerk/react change, and the resulting type matches main.

manovotny

This LGTM, but if someone on the JS/SDK team could look, that'd be great!

wobsoriano

thanks for catching this

fix(react): make ClerkProvider publishableKey optional

f12c7dd

SarahSoutoul self-assigned this Aug 3, 2026

github-actions Bot added the react label Aug 3, 2026

SarahSoutoul marked this pull request as ready for review August 3, 2026 07:36

vercel Bot deployed to Preview – swingset August 3, 2026 07:36 View deployment

SarahSoutoul requested review from brkalow, manovotny and wobsoriano August 3, 2026 07:36

github-actions Bot added the chrome-extension label Aug 3, 2026

vercel Bot deployed to Preview – clerk-js-sandbox August 3, 2026 22:25 View deployment

manovotny approved these changes Aug 3, 2026

View reviewed changes

vercel Bot deployed to Preview – swingset August 3, 2026 22:27 View deployment

wobsoriano approved these changes Aug 4, 2026

View reviewed changes

Merge branch 'main' into ss/DOCS-11990

9409e1f

vercel Bot deployed to Preview – clerk-js-sandbox August 4, 2026 06:52 View deployment

vercel Bot deployed to Preview – swingset August 4, 2026 06:54 View deployment

SarahSoutoul merged commit bbe51ff into main Aug 4, 2026
52 checks passed

SarahSoutoul deleted the ss/DOCS-11990 branch August 4, 2026 06:57

clerk-cookie mentioned this pull request Aug 4, 2026

ci(repo): Version packages #9306

Merged

Navigation Menu

Uh oh!

fix(react): make ClerkProvider publishableKey optional - #9314

fix(react): make ClerkProvider publishableKey optional#9314
SarahSoutoul merged 3 commits into
mainfrom
ss/DOCS-11990

SarahSoutoul commented Aug 3, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Aug 3, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Aug 3, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Aug 3, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 3, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Aug 3, 2026 •

edited

Loading

Walkthrough

Uh oh!

manovotny commented Aug 3, 2026

Uh oh!

manovotny left a comment

Uh oh!

wobsoriano left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

SarahSoutoul commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

changeset-bot Bot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Changes Report

Summary

@clerk/react

Subpath .

🟡 Non-breaking Changes (1)

Modified: ClerkProviderProps

Subpath ./types

🟡 Non-breaking Changes (1)

Modified: ClerkProviderProps

Uh oh!

coderabbitai Bot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

manovotny commented Aug 3, 2026

Uh oh!

manovotny left a comment

Choose a reason for hiding this comment

Uh oh!

wobsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

SarahSoutoul commented Aug 3, 2026 •

edited

Loading

changeset-bot Bot commented Aug 3, 2026 •

edited

Loading

vercel Bot commented Aug 3, 2026 •

edited

Loading

pkg-pr-new Bot commented Aug 3, 2026 •

edited

Loading

github-actions Bot commented Aug 3, 2026 •

edited

Loading

Subpath `.`

Modified: `ClerkProviderProps`

Subpath `./types`

Modified: `ClerkProviderProps`

coderabbitai Bot commented Aug 3, 2026 •

edited

Loading