chore(clerk-js, shared): Expose useCheckout as experimental #6195

panteliselef · 2025-06-25T19:51:27Z

Description

React

Usage without provider

const {
  // Resource properties
  id,
  paymentSource,
  plan,
  externalClientSecret,
  planPeriod,
  planPeriodStart,
  totals,
  isImmediatePlanChange,
  
  // helpers
  isStarting,
  isConfirming,
  status,
  error,
  fetchStatus,
  
  
  // methods
  start,
  confirm,
  clear,
  finalize
} = useCheckout({ planId: "cplan_xxx", planPeriod: "month" });

Usage with provider

<CheckoutProvider for="user" planId="cplan_xxxx" planPeriod="month">
   <UpgragdeButton />
</CheckoutProvider>

function UpgragdeButton() {
   const checkout = useCheckout();
}

Vanilla JS

const checkout = Clek.checkout({ 
	for: "org",
	planId:"cplan_xxx",
	planPeriod: "month"
})

const { data, error} = await checkout.start()
const { data, error} = await  checkout.confirm()
checkout.finalize()
checkout.clear()
checkout.subscribe()
checkout.getState()

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

New Features
- Introduced an experimental billing and checkout experience, including a new useCheckout() hook and <CheckoutProvider/> component for managing checkout flows.
- Added an experimental checkout method for programmatic management of checkout sessions.
- Enhanced error handling and status tracking within checkout-related components.
Refactor
- Unified and simplified checkout-related components to use the new experimental hook and provider, replacing manual state and error management.
- Updated context providers to include the new checkout provider for centralized state management.
- Consolidated checkout UI stages and improved conditional rendering based on fetch status.
Tests
- Added comprehensive tests covering checkout state management, concurrency, error handling, and TypeScript type validation.
Chores
- Updated test configurations and scripts to include Vitest alongside Jest.
- Adjusted bundle size limits for UI common files.

changeset-bot · 2025-06-25T19:51:31Z

🦋 Changeset detected

Latest commit: 64c24fb

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

This PR includes changesets to release 22 packages

Name	Type
@clerk/tanstack-react-start	Minor
@clerk/react-router	Minor
@clerk/nextjs	Minor
@clerk/shared	Minor
@clerk/clerk-react	Minor
@clerk/remix	Minor
@clerk/clerk-js	Minor
@clerk/types	Minor
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/elements	Patch
@clerk/expo-passkeys	Patch
@clerk/clerk-expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nuxt	Patch
@clerk/testing	Patch
@clerk/vue	Patch
@clerk/localizations	Patch
@clerk/themes	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-06-25T19:51:32Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 11, 2025 7:10pm

panteliselef · 2025-06-26T09:13:55Z

!snapshot

clerk-cookie · 2025-06-26T09:16:30Z

Hey @panteliselef - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.1.3-snapshot.v20250626091436
@clerk/astro	2.9.3-snapshot.v20250626091436
@clerk/backend	2.2.1-snapshot.v20250626091436
@clerk/chrome-extension	2.5.1-snapshot.v20250626091436
@clerk/clerk-js	5.70.0-snapshot.v20250626091436
@clerk/elements	0.23.35-snapshot.v20250626091436
@clerk/clerk-expo	2.14.0-snapshot.v20250626091436
@clerk/expo-passkeys	0.3.12-snapshot.v20250626091436
@clerk/express	1.7.2-snapshot.v20250626091436
@clerk/fastify	2.4.2-snapshot.v20250626091436
@clerk/localizations	3.17.1-snapshot.v20250626091436
@clerk/nextjs	6.24.0-snapshot.v20250626091436
@clerk/nuxt	1.7.3-snapshot.v20250626091436
@clerk/clerk-react	5.33.0-snapshot.v20250626091436
@clerk/react-router	1.6.2-snapshot.v20250626091436
@clerk/remix	4.8.3-snapshot.v20250626091436
@clerk/shared	3.10.0-snapshot.v20250626091436
@clerk/tanstack-react-start	0.18.1-snapshot.v20250626091436
@clerk/testing	1.8.3-snapshot.v20250626091436
@clerk/themes	2.2.52-snapshot.v20250626091436
@clerk/types	4.62.0-snapshot.v20250626091436
@clerk/vue	1.8.10-snapshot.v20250626091436

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/elements

npm i @clerk/[email protected] --save-exact

@clerk/clerk-expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/clerk-react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/remix

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/themes

npm i @clerk/[email protected] --save-exact

@clerk/types

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

panteliselef · 2025-06-26T09:35:38Z

!snapshot

coderabbitai

Actionable comments posted: 1

♻️ Duplicate comments (4)

packages/shared/src/react/hooks/useCheckout.ts (3)
18-20: Replace any with proper function type constraint.

The use of any violates TypeScript best practices. Consider using a more specific function type or unknown with proper type narrowing.
-type RemoveFunctions<T> = {
-  [K in keyof T as T[K] extends (...args: any[]) => any ? never : K]: T[K];
-};
+type RemoveFunctions<T> = {
+  [K in keyof T as T[K] extends (...args: unknown[]) => unknown ? never : K]: T[K];
+};
54-54: Add JSDoc documentation for the exported public API.

This exported hook lacks comprehensive documentation. The coding guidelines require JSDoc comments for public APIs including @param, @returns, @throws, and @example.
+/**
+ * Hook for managing checkout state and actions in commerce flows.
+ * 
+ * @param options - Configuration options for the checkout
+ * @param options.for - Specifies if checkout is for 'organization' 
+ * @param options.planId - The subscription plan ID
+ * @param options.planPeriod - The plan billing period
+ * @returns Object containing checkout state and management methods
+ * @throws Error when user is not authenticated
+ * @throws Error when organization checkout is requested but no active organization
+ * @example
+ * ```tsx
+ * const { checkout } = useCheckout({
+ *   for: 'organization',
+ *   planId: 'plan_123',
+ *   planPeriod: 'monthly'
+ * });
+ * ```
+ */
 export const useCheckout = (options?: UseCheckoutOptions): __experimental_UseCheckoutReturn => {
109-110: Fix TypeScript error suppression with proper type handling.

The @ts-ignore comment suppresses TypeScript errors instead of addressing the underlying type mismatch. This violates coding guidelines and can lead to runtime issues.

The checkout: null assignment suggests a type structure issue. Consider either:

Removing the checkout property from the destructured object in the properties memoization

Properly typing the return object to handle this property
   const checkout = {
     ...properties,
     getState: manager.getState,
-    // @ts-ignore
-    checkout: null,
     start: manager.start,
If the checkout property needs to be excluded from the properties object, handle it in the destructuring:
   const {
     reload,
     confirm,
     pathRoot,
+    checkout,
     // All the above need to be removed from the properties
     ...rest
   } = managerProperties.checkout;
packages/clerk-js/src/core/modules/checkout/__tests__/manager.spec.ts (1)
510-512: Replace non-null assertion with proper type narrowing.

The non-null assertion operator ! is discouraged by the coding guidelines. Consider using proper type narrowing instead to ensure type safety.
       // Resolve the operation
-      resolveOperation!(mockCheckout);
+      if (resolveOperation) {
+        resolveOperation(mockCheckout);
+      }
       await operationPromise;

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ba655f9 and 3f97051.

📒 Files selected for processing (6)

packages/clerk-js/src/core/modules/checkout/__tests__/manager.spec.ts (1 hunks)
packages/clerk-js/src/core/modules/checkout/instance.ts (1 hunks)
packages/clerk-js/src/core/modules/checkout/manager.ts (1 hunks)
packages/shared/src/react/hooks/__tests__/useCheckout.type.spec.ts (1 hunks)
packages/shared/src/react/hooks/useCheckout.ts (1 hunks)
packages/types/src/clerk.ts (4 hunks)

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

packages/clerk-js/src/core/modules/checkout/instance.ts
packages/shared/src/react/hooks/tests/useCheckout.type.spec.ts
packages/clerk-js/src/core/modules/checkout/manager.ts
packages/types/src/clerk.ts

🧰 Additional context used

📓 Path-based instructions (10)

`**/*.{js,jsx,ts,tsx}`: All code must pass ESLint checks with the project's conf...

**/*.{js,jsx,ts,tsx}: All code must pass ESLint checks with the project's configuration
Use Prettier for consistent code formatting
Follow established naming conventions (PascalCase for components, camelCase for variables)
Maintain comprehensive JSDoc comments for public APIs
Use dynamic imports for optional features
All public APIs must be documented with JSDoc
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Validate all inputs and sanitize outputs
Implement proper logging with different levels

📄 Source: CodeRabbit Inference Engine (.cursor/rules/development.mdc)