chore(clerk-react,shared): Improve assertion error for requiring active organization (#6606)

Author: panteliselef

.changeset/plain-bottles-press.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+---
+
+Improve assertion error for requiring active organization.

packages/react/src/components/CheckoutButton.tsx

@@ -31,7 +31,7 @@ import { withClerk } from './withClerk';
  *       <CheckoutButton
  *         planId="plan_123"
  *         planPeriod="month"
- *         subscriberType="org"
+ *         for="organization"
  *         onSubscriptionComplete={() => console.log('Subscription completed!')}
  *       >
  *         <button className="custom-button">Subscribe Now</button>
@@ -42,7 +42,7 @@ import { withClerk } from './withClerk';
  * ```
  *
  * @throws {Error} When rendered outside of a `<SignedIn />` component
- * @throws {Error} When `subscriberType="org"` is used without an active organization context
+ * @throws {Error} When `for="organization"` is used without an active organization context
  */
 export const CheckoutButton = withClerk(
   ({ clerk, children, ...props }: WithClerkProp<React.PropsWithChildren<__experimental_CheckoutButtonProps>>) => {
@@ -59,11 +59,13 @@ export const CheckoutButton = withClerk(
     const { userId, orgId } = useAuth();
 
     if (userId === null) {
-      throw new Error('Ensure that `<CheckoutButton />` is rendered inside a `<SignedIn />` component.');
+      throw new Error('Clerk: Ensure that `<CheckoutButton />` is rendered inside a `<SignedIn />` component.');
     }
 
     if (orgId === null && _for === 'organization') {
-      throw new Error('Wrap `<CheckoutButton for="organization" />` with a check for an active organization.');
+      throw new Error(
+        'Clerk: Wrap `<CheckoutButton for="organization" />` with a check for an active organization. Retrieve `orgId` from `useAuth()` and confirm it is defined. For SSR, see: https://clerk.com/docs/references/backend/types/auth-object#how-to-access-the-auth-object',
+      );
     }
 
     children = normalizeWithDefaultValue(children, 'Checkout');

packages/react/src/components/SubscriptionDetailsButton.tsx

@@ -26,7 +26,7 @@ import { withClerk } from './withClerk';
  * function OrganizationSubscriptionDetails() {
  *   return (
  *     <SubscriptionDetailsButton
- *       for="org"
+ *       for="organization"
  *       onSubscriptionCancel={() => console.log('Subscription canceled')}
  *     >
  *       <button>View Organization Subscription</button>
@@ -36,7 +36,7 @@ import { withClerk } from './withClerk';
  * ```
  *
  * @throws {Error} When rendered outside of a `<SignedIn />` component
- * @throws {Error} When `for="org"` is used without an active organization context
+ * @throws {Error} When `for="organization"` is used without an active organization context
  *
  * @see https://clerk.com/docs/billing/overview
  */
@@ -53,12 +53,14 @@ export const SubscriptionDetailsButton = withClerk(
     const { userId, orgId } = useAuth();
 
     if (userId === null) {
-      throw new Error('Ensure that `<SubscriptionDetailsButton />` is rendered inside a `<SignedIn />` component.');
+      throw new Error(
+        'Clerk: Ensure that `<SubscriptionDetailsButton />` is rendered inside a `<SignedIn />` component.',
+      );
     }
 
     if (orgId === null && _for === 'organization') {
       throw new Error(
-        'Wrap `<SubscriptionDetailsButton for="organization" />` with a check for an active organization.',
+        'Clerk: Wrap `<SubscriptionDetailsButton for="organization" />` with a check for an active organization. Retrieve `orgId` from `useAuth()` and confirm it is defined. For SSR, see: https://clerk.com/docs/references/backend/types/auth-object#how-to-access-the-auth-object',
       );
     }
 

packages/react/src/components/__tests__/CheckoutButton.test.tsx

@@ -62,7 +62,9 @@ describe('CheckoutButton', () => {
             for='organization'
           />,
         ),
-      ).toThrow('Wrap `<CheckoutButton for="organization" />` with a check for an active organization.');
+      ).toThrow(
+        'Wrap `<CheckoutButton for="organization" />` with a check for an active organization. Retrieve `orgId` from `useAuth()` and confirm it is defined.',
+      );
     });
 
     it('renders successfully with authenticated user', () => {

packages/react/src/components/__tests__/SubscriptionDetailsButton.test.tsx

@@ -56,7 +56,7 @@ describe('SubscriptionDetailsButton', () => {
 
       // Expect the component to throw an error when for="organization"
       expect(() => render(<SubscriptionDetailsButton for='organization' />)).toThrow(
-        'Wrap `<SubscriptionDetailsButton for="organization" />` with a check for an active organization.',
+        'Wrap `<SubscriptionDetailsButton for="organization" />` with a check for an active organization. Retrieve `orgId` from `useAuth()` and confirm it is defined.',
       );
     });
 

packages/shared/src/react/hooks/useCheckout.ts

@@ -84,7 +84,9 @@ export const useCheckout = (options?: Params): __experimental_UseCheckoutReturn
   }
 
   if (forOrganization === 'organization' && !organization) {
-    throw new Error('Clerk: Wrap your flow with a check for an active organization');
+    throw new Error(
+      'Clerk: Ensure your flow checks for an active organization. Retrieve `orgId` from `useAuth()` and confirm it is defined. For SSR, see: https://clerk.com/docs/references/backend/types/auth-object#how-to-access-the-auth-object',
+    );
   }
 
   const manager = useMemo(