fix(clerk-js): Backwards compatibility with deprecated prop in PricingTable #7021

panteliselef · 2025-10-17T17:21:59Z

Description

We decided to support the old prop for the next few minors, to give the opportunity to developers who are not using a pinned clerk-js version to migrate.

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

Summary by CodeRabbit

Bug Fixes
- Extended support for the forOrganizations prop in Billing Beta with a deprecation notice for legacy syntax usage.

…gTable

changeset-bot · 2025-10-17T17:22:03Z

🦋 Changeset detected

Latest commit: 5366e22

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

This PR includes changesets to release 4 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/nextjs	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-expo	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 · 2025-10-17T17:22:04Z

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

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Oct 17, 2025 5:24pm

💡 Enable Vercel Agent with $100 free credit for automated AI reviews

coderabbitai · 2025-10-17T17:22:12Z

Walkthrough

This pull request introduces backward-compatibility support for a legacy forOrganizations prop in the PricingTable component, with deprecation warnings and context-based prop handling. Changes span a changeset file, core clerk logic, UI contexts, and comprehensive test coverage.

Changes

Cohort / File(s)	Summary
Release Notes `.changeset/thin-maps-train.md`	New changeset file documenting patch version bump for `@clerk/clerk-js` with notes on extended Billing Beta support for the `forOrganizations` prop.
Backward-Compatibility Layer `packages/clerk-js/src/core/clerk.ts`	Adds deprecation handling for legacy `forOrganizations` prop by creating a `nextProps` object with optional `forOrganizations` field, emitting a one-time warning via `logger.warnOnce()`, and passing the transformed props to PricingTable. Telemetry records using the modified props.
Context Provider `packages/clerk-js/src/ui/contexts/ClerkUIComponentsContext.tsx`	Updates `SubscriberTypeContext.Provider` value to derive from the legacy `forOrganizations` flag: if truthy, sets value to `'organization'`, otherwise uses existing `(props as PricingTableProps).for` or defaults to `'user'`. Includes backward-compatibility comment.
Test Coverage `packages/clerk-js/src/ui/components/PricingTable/__tests__/PricingTable.test.tsx`	Adds extensive test cases for legacy `forOrganizations` prop and organization contexts. Introduces new tests verifying organization plans fetching with both legacy and current prop patterns. Augments existing tests with assertions for API call arguments (`for: 'user'`, `for: 'organization'`, `orgId` values) across user, organization, and signed-out states.

Sequence Diagram

sequenceDiagram
    participant Consumer
    participant Clerk
    participant Context
    participant Component

    Consumer->>Clerk: Provide PricingTable with forOrganizations
    Note over Clerk: Legacy Prop Detected
    Clerk->>Clerk: Create nextProps with forOrganizations
    Clerk->>Clerk: Emit deprecation warning (once)
    Clerk->>Context: Pass nextProps
    Context->>Context: Derive SubscriberTypeContext value<br/>from forOrganizations flag
    Context->>Component: Render with derived context
    Component->>Component: Use SubscriberTypeContext<br/>for API calls

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

The changes follow a clear, consistent pattern focused on a single backward-compatibility concern. While test coverage is extensive, the tests apply a uniform verification pattern across multiple scenarios. The logic is straightforward—prop transformation, deprecation warning, and context value derivation—with minimal branching or complex interactions.

Poem

🐰 A legacy prop hops into view,
With gentle warnings, old yet new,
The context flows, a rabbit's care,
Backward-compatibility everywhere! 🌱

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "fix(clerk-js): Backwards compatibility with deprecated prop in PricingTable" accurately and specifically summarizes the main change in the pull request. The changeset adds backward-compatibility support for the legacy `forOrganizations` prop in the PricingTable component, which is precisely what the title conveys. The title is concise, uses conventional commit format, and avoids vague language or noise. A developer reviewing the repository history would immediately understand that this PR addresses backward compatibility for a deprecated property.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ 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 elef/hot-fix-pricing-table-compat

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

Removed patch version for '@clerk/nextjs' and updated support details.

pkg-pr-new · 2025-10-17T17:25:56Z

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@7021

@clerk/clerk-expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/clerk-react

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

@clerk/react-router

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

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@7021

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@7021

@clerk/types

npm i https://pkg.pr.new/@clerk/types@7021

@clerk/upgrade

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

@clerk/vue

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

commit: 5366e22

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (3)

.changeset/thin-maps-train.md (1)

5-5: Clarify the changeset description.

The phrase "by a few minors" is grammatically unclear. Consider revising to something like: "[Billing Beta] Add backward-compatibility support for deprecated forOrganizations prop with deprecation warnings."
packages/clerk-js/src/ui/contexts/ClerkUIComponentsContext.tsx (1)
98-103: Consider improving type safety in backward-compatibility logic.

The use of (props as any) twice on line 101 bypasses TypeScript's type checking. While functional, this could mask type errors.

Consider one of these approaches:

Option 1: Use optional chaining with type assertion once
  <SubscriberTypeContext.Provider
    value={
      // Backward compatibility: support legacy `forOrganizations: true`
-     (props as any).forOrganizations ? 'organization' : (props as PricingTableProps).for || 'user'
+     (props as PricingTableProps & { forOrganizations?: boolean }).forOrganizations
+       ? 'organization'
+       : (props as PricingTableProps).for || 'user'
    }
  >
Option 2: Extract to a variable for clarity
+ const legacyForOrganizations = (props as PricingTableProps & { forOrganizations?: boolean }).forOrganizations;
  <SubscriberTypeContext.Provider
    value={
      // Backward compatibility: support legacy `forOrganizations: true`
-     (props as any).forOrganizations ? 'organization' : (props as PricingTableProps).for || 'user'
+     legacyForOrganizations ? 'organization' : (props as PricingTableProps).for || 'user'
    }
  >
packages/clerk-js/src/core/clerk.ts (1)
1154-1161: Improve type safety in backward-compatibility prop handling.

The dual type assertion pattern on line 1155 could be simplified for better type safety and readability.

Consider this cleaner approach:
-    // Temporary backward compatibility for legacy prop: `forOrganizations`. Will be removed in the coming minor release.
-    const nextProps = { ...(props as any) } as PricingTableProps & { forOrganizations?: boolean };
-    if (typeof (props as any)?.forOrganizations !== 'undefined') {
+    // Temporary backward compatibility for legacy prop: `forOrganizations`. Will be removed in the coming minor release.
+    const nextProps = props as PricingTableProps & { forOrganizations?: boolean };
+    if (typeof nextProps.forOrganizations !== 'undefined') {
      logger.warnOnce(
        'Clerk: [IMPORTANT] <PricingTable /> prop `forOrganizations` is deprecated and will be removed in the coming minors. Use `for="organization"` instead.',
      );
    }
This avoids unnecessary spreading and multiple as any casts while maintaining the same functionality.

📜 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 6503405 and 5366e22.

📒 Files selected for processing (4)

.changeset/thin-maps-train.md (1 hunks)
packages/clerk-js/src/core/clerk.ts (1 hunks)
packages/clerk-js/src/ui/components/PricingTable/__tests__/PricingTable.test.tsx (4 hunks)
packages/clerk-js/src/ui/contexts/ClerkUIComponentsContext.tsx (1 hunks)

🧰 Additional context used

📓 Path-based instructions (14)

packages/clerk-js/src/ui/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/clerk-js-ui.mdc)

packages/clerk-js/src/ui/**/*.{ts,tsx}: Element descriptors should always be camelCase
Use element descriptors in UI components to enable consistent theming and styling via appearance.elements
Element descriptors should generate unique, stable CSS classes for theming
Element descriptors should handle state classes (e.g., cl-loading, cl-active, cl-error, cl-open) automatically based on component state
Do not render hard-coded values; all user-facing strings must be localized using provided localization methods
Use the useLocalizations hook and localizationKeys utility for all text and error messages
Use the styled system (sx prop, theme tokens, responsive values) for custom component styling
Use useCardState for card-level state, useFormState for form-level state, and useLoadingStatus for loading states
Always use handleError utility for API errors and use translateError for localized error messages
Use useFormControl for form field state, implement proper validation, and handle loading and error states in forms
Use localization keys for all form labels and placeholders
Use element descriptors for consistent styling and follow the theme token system
Use the Card and FormContainer patterns for consistent UI structure

Files:

packages/clerk-js/src/ui/components/PricingTable/__tests__/PricingTable.test.tsx
packages/clerk-js/src/ui/contexts/ClerkUIComponentsContext.tsx

**/*.{js,jsx,ts,tsx}