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: f12c7dd

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 3, 2026 7:36am
swingset	Ready	Preview	Aug 3, 2026 7:36am

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: f12c7dd

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

API Changes Report

Generated by Break Check on 2026-08-03T07:39:17.010Z

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 omits publishableKey from the Omit base type and re-adds it as an explicit optional string property (publishableKey?: string). In IsomorphicClerkOptions, publishableKey was already present (required or optional); by re-declaring it as optional in the intersection, the net effect is that publishableKey becomes optional in ClerkProviderProps. Consumers who previously passed publishableKey still can (it now accepts string), and consumers who did not pass it are now also valid. No existing well-typed call site is broken — the field's presence is now optional rather than potentially required, which is a relaxation for callers.

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 the IsomorphicClerkOptions base (where it was required or typed more strictly) and re-adds it as an explicit optional string field. This widens the type for consumers passing ClerkProviderProps (an input type): publishableKey becomes optional, so existing callers who either passed it or omitted it remain valid. No well-typed consumer code breaks.

Report generated by Break Check

_{Last ran on f12c7dd.}

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: 9e3ee72d-5010-47ea-803a-52ef36523366

📥 Commits

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

📒 Files selected for processing (3)

.changeset/calm-keys-appear.md
packages/react/src/contexts/__tests__/ClerkProvider.test.tsx
packages/react/src/types.ts

🔗 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 VITE_CLERK_PUBLISHABLE_KEY and CLERK_PUBLISHABLE_KEY as fallback sources. Type tests accept both explicit and omitted keys. A patch changeset records the update for @clerk/react.

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

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: making ClerkProvider publishableKey optional.
Description check	✅ Passed	The description directly explains the type update, runtime fallback, tests, and generated declaration changes.
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.}

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

fix(react): make ClerkProvider publishableKey optional#9314
SarahSoutoul wants to merge 1 commit into
mainfrom
ss/DOCS-11990

SarahSoutoul commented Aug 3, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Aug 3, 2026

Uh oh!

vercel Bot commented Aug 3, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Aug 3, 2026

Uh oh!

github-actions Bot commented Aug 3, 2026

Uh oh!

coderabbitai Bot commented Aug 3, 2026

Walkthrough

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

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

🦋 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

Uh oh!

github-actions Bot commented Aug 3, 2026

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

Walkthrough

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

SarahSoutoul commented Aug 3, 2026 •

edited

Loading

vercel Bot commented Aug 3, 2026 •

edited

Loading

Subpath `.`

Modified: `ClerkProviderProps`

Subpath `./types`

Modified: `ClerkProviderProps`