chore(react,types): Update typedoc comments for react hooks and clerkprovider (#5457)

Co-authored-by: Lennart <lekoarts@gmail.com>

Author: alexisintech

.changeset/rare-ladybugs-chew.md

@@ -0,0 +1,6 @@
+---
+"@clerk/clerk-react": patch
+"@clerk/types": patch
+---
+
+Improve JSDoc comments

packages/react/src/hooks/useAuth.ts

@@ -12,13 +12,14 @@ import { createGetToken, createSignOut } from './utils';
 /**
  * The `useAuth()` hook provides access to the current user's authentication state and methods to manage the active session.
  *
+ * <If sdk="nextjs">
+ * By default, Next.js opts all routes into static rendering. If you need to opt a route or routes into dynamic rendering because you need to access the authentication data at request time, you can create a boundary by passing the `dynamic` prop to `<ClerkProvider>`. See the [guide on rendering modes](https://clerk.com/docs/references/nextjs/rendering-modes) for more information, including code examples.
+ * </If>
+ *
  * @param [initialAuthState] - An object containing the initial authentication state. If not provided, the hook will attempt to derive the state from the context.
  *
  * @example
  *
- * > [!NOTE]
- * > For frameworks like Next.js that support multiple ways of rendering its content, it might be preferable to use the [`auth()`](https://clerk.com/docs/references/nextjs/auth) helper instead of `useAuth()`. This depends on if you want to use React Server Components, SSR, or client-side rendering. Learn more in the [rendering modes](https://clerk.com/docs/references/nextjs/rendering-modes) guide. If you only want to access data on the client-side, `useAuth()` is sufficient.
- *
  * The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource.
  *
  * <Tabs items='React,Next.js'>

packages/react/src/types.ts

@@ -28,7 +28,7 @@ export type IsomorphicClerkOptions = Without<ClerkOptions, 'isSatellite'> & {
    */
   clerkJSUrl?: string;
   /**
-   * If your web application only uses Control components, you can set this value to `'headless'` and load a minimal ClerkJS bundle for optimal page performance.
+   * If your web application only uses [Control Components](https://clerk.com/docs/components/overview#control-components), you can set this value to `'headless'` and load a minimal ClerkJS bundle for optimal page performance.
    */
   clerkJSVariant?: 'headless' | '';
   /**

packages/types/src/clerk.ts

@@ -76,7 +76,7 @@ export type SignOutOptions = {
    */
   sessionId?: string;
   /**
-   * Specify a redirect URL to navigate after sign out is complete.
+   * Specify a redirect URL to navigate to after sign out is complete.
    */
   redirectUrl?: string;
 };
@@ -677,30 +677,30 @@ export type HandleOAuthCallbackParams = TransferableOption &
      */
     signUpUrl?: string;
     /**
-     * Full URL or path to navigate during sign in,
+     * Full URL or path to navigate to during sign in,
      * if identifier verification is required.
      */
     firstFactorUrl?: string;
     /**
-     * Full URL or path to navigate during sign in,
+     * Full URL or path to navigate to during sign in,
      * if 2FA is enabled.
      */
     secondFactorUrl?: string;
     /**
-     * Full URL or path to navigate during sign in,
+     * Full URL or path to navigate to during sign in,
      * if the user is required to reset their password.
      */
     resetPasswordUrl?: string;
     /**
-     * Full URL or path to navigate after an incomplete sign up.
+     * Full URL or path to navigate to after an incomplete sign up.
      */
     continueSignUpUrl?: string | null;
     /**
-     * Full URL or path to navigate after requesting email verification.
+     * Full URL or path to navigate to after requesting email verification.
      */
     verifyEmailAddressUrl?: string | null;
     /**
-     * Full URL or path to navigate after requesting phone verification.
+     * Full URL or path to navigate to after requesting phone verification.
      */
     verifyPhoneNumberUrl?: string | null;
   };
@@ -980,14 +980,14 @@ export type RoutingOptions =
 
 export type SignInProps = RoutingOptions & {
   /**
-   * Full URL or path to navigate after successful sign in.
+   * Full URL or path to navigate to after successful sign in.
    * This value has precedence over other redirect props, environment variables or search params.
    * Use this prop to override the redirect URL when needed.
    * @default undefined
    */
   forceRedirectUrl?: string | null;
   /**
-   * Full URL or path to navigate after successful sign in.
+   * Full URL or path to navigate to after successful sign in.
    * This value is used when no other redirect props, environment variables or search params are present.
    * @default undefined
    */
@@ -1125,14 +1125,14 @@ export type GoogleOneTapProps = GoogleOneTapRedirectUrlProps & {
 
 export type SignUpProps = RoutingOptions & {
   /**
-   * Full URL or path to navigate after successful sign up.
+   * Full URL or path to navigate to after successful sign up.
    * This value has precedence over other redirect props, environment variables or search params.
    * Use this prop to override the redirect URL when needed.
    * @default undefined
    */
   forceRedirectUrl?: string | null;
   /**
-   * Full URL or path to navigate after successful sign up.
+   * Full URL or path to navigate to after successful sign up.
    * This value is used when no other redirect props, environment variables or search params are present.
    * @default undefined
    */
@@ -1224,7 +1224,7 @@ export type OrganizationProfileModalProps = WithoutRouting<OrganizationProfilePr
 
 export type CreateOrganizationProps = RoutingOptions & {
   /**
-   * Full URL or path to navigate after creating a new organization.
+   * Full URL or path to navigate to after creating a new organization.
    * @default undefined
    */
   afterCreateOrganizationUrl?:
@@ -1282,23 +1282,23 @@ export type UserButtonProps = UserButtonProfileMode & {
   __experimental_asStandalone?: boolean | ((opened: boolean) => void);
 
   /**
-   * Full URL or path to navigate after sign out is complete
+   * Full URL or path to navigate to after sign out is complete
    * @deprecated Configure `afterSignOutUrl` as a global configuration, either in <ClerkProvider/> or in await Clerk.load()
    */
   afterSignOutUrl?: string;
   /**
-   * Full URL or path to navigate after signing out the current user is complete.
+   * Full URL or path to navigate to after signing out the current user is complete.
    * This option applies to multi-session applications.
    * @deprecated Configure `afterMultiSessionSingleSignOutUrl` as a global configuration, either in <ClerkProvider/> or in await Clerk.load()
    */
   afterMultiSessionSingleSignOutUrl?: string;
   /**
-   * Full URL or path to navigate on "Add another account" action.
+   * Full URL or path to navigate to on "Add another account" action.
    * Multi-session mode only.
    */
   signInUrl?: string;
   /**
-   * Full URL or path to navigate after successful account change.
+   * Full URL or path to navigate to after successful account change.
    * Multi-session mode only.
    */
   afterSwitchSessionUrl?: string;
@@ -1360,28 +1360,28 @@ export type OrganizationSwitcherProps = CreateOrganizationMode &
      */
     hidePersonal?: boolean;
     /**
-     * Full URL or path to navigate after a successful organization switch.
+     * Full URL or path to navigate to after a successful organization switch.
      * @default undefined
      * @deprecated use `afterSelectOrganizationUrl` or `afterSelectPersonalUrl`
      */
     afterSwitchOrganizationUrl?: string;
     /**
-     * Full URL or path to navigate after creating a new organization.
+     * Full URL or path to navigate to after creating a new organization.
      * @default undefined
      */
     afterCreateOrganizationUrl?:
       | ((organization: OrganizationResource) => string)
       | LooseExtractedParams<PrimitiveKeys<OrganizationResource>>;
     /**
-     * Full URL or path to navigate after a successful organization selection.
+     * Full URL or path to navigate to after a successful organization selection.
      * Accepts a function that returns URL or path
      * @default undefined`
      */
     afterSelectOrganizationUrl?:
       | ((organization: OrganizationResource) => string)
       | LooseExtractedParams<PrimitiveKeys<OrganizationResource>>;
     /**
-     * Full URL or path to navigate after a successful selection of personal workspace.
+     * Full URL or path to navigate to after a successful selection of personal workspace.
      * Accepts a function that returns URL or path
      * @default undefined
      */
@@ -1417,14 +1417,14 @@ export type OrganizationSwitcherProps = CreateOrganizationMode &
 
 export type OrganizationListProps = {
   /**
-   * Full URL or path to navigate after creating a new organization.
+   * Full URL or path to navigate to after creating a new organization.
    * @default undefined
    */
   afterCreateOrganizationUrl?:
     | ((organization: OrganizationResource) => string)
     | LooseExtractedParams<PrimitiveKeys<OrganizationResource>>;
   /**
-   * Full URL or path to navigate after a successful organization selection.
+   * Full URL or path to navigate to after a successful organization selection.
    * Accepts a function that returns URL or path
    * @default undefined`
    */
@@ -1452,7 +1452,7 @@ export type OrganizationListProps = {
    */
   hidePersonal?: boolean;
   /**
-   * Full URL or path to navigate after a successful selection of personal workspace.
+   * Full URL or path to navigate to after a successful selection of personal workspace.
    * Accepts a function that returns URL or path
    * @default undefined`
    */
@@ -1466,7 +1466,7 @@ export type OrganizationListProps = {
 
 export type WaitlistProps = {
   /**
-   * Full URL or path to navigate after join waitlist.
+   * Full URL or path to navigate to after join waitlist.
    */
   afterJoinWaitlistUrl?: string;
   /**
@@ -1512,12 +1512,12 @@ export type __experimental_CheckoutProps = {
 
 export interface HandleEmailLinkVerificationParams {
   /**
-   * Full URL or path to navigate after successful magic link verification
+   * Full URL or path to navigate to after successful magic link verification
    * on completed sign up or sign in on the same device.
    */
   redirectUrlComplete?: string;
   /**
-   * Full URL or path to navigate after successful magic link verification
+   * Full URL or path to navigate to after successful magic link verification
    * on the same device, but not completed sign in or sign up.
    */
   redirectUrl?: string;
@@ -1626,7 +1626,7 @@ export interface AuthenticateWithGoogleOneTapParams {
 
 export interface NextTaskParams {
   /**
-   * Full URL or path to navigate after successfully resolving all tasks
+   * Full URL or path to navigate to after successfully resolving all tasks
    * @default undefined
    */
   redirectUrlComplete?: string;

packages/types/src/hooks.ts

@@ -37,7 +37,7 @@ export type UseAuthReturn =
        */
       sessionId: undefined;
       /**
-       * JWT Actor - [RFC8693](https://www.rfc-editor.org/rfc/rfc8693.html#name-act-actor-claim).
+       * The JWT actor for the session. Holds identifier for the user that is impersonating the current user. Read more about [impersonation](https://clerk.com/docs/users/user-impersonation).
        */
       actor: undefined;
       /**

packages/types/src/jwt.ts

@@ -82,7 +82,7 @@ export interface ClerkJWTClaims {
   act?: ActClaim;
 
   /**
-   * Active organization id.
+   * Active organization ID.
    */
   org_id?: string;
 
@@ -92,7 +92,7 @@ export interface ClerkJWTClaims {
   org_slug?: string;
 
   /**
-   * Active organization role
+   * Active organization role.
    */
   org_role?: OrganizationCustomRoleKey;
 

packages/types/src/jwtv2.ts

@@ -83,7 +83,7 @@ export interface JwtPayload extends CustomJwtSessionClaims {
   act?: ActClaim;
 
   /**
-   * Active organization id.
+   * Active organization ID.
    */
   org_id?: string;
 
@@ -93,7 +93,7 @@ export interface JwtPayload extends CustomJwtSessionClaims {
   org_slug?: string;
 
   /**
-   * Active organization role
+   * Active organization role.
    */
   org_role?: OrganizationCustomRoleKey;
 

packages/types/src/multiDomain.ts

@@ -15,7 +15,7 @@ export type MultiDomainAndOrProxy =
        */
       isSatellite?: never;
       /**
-       * The URL that Clerk will proxy requests to. Required for applications that run behind a reverse proxy. Can be either a relative path (`/__clerk`) or a full URL (`https://<your-domain>/__clerk`).
+       * **Required for applications that run behind a reverse proxy**. The URL that Clerk will proxy requests to. Can be either a relative path (`/__clerk`) or a full URL (`https://<your-domain>/__clerk`).
        */
       proxyUrl?: never | string | ((url: URL) => string);
       /**
@@ -41,7 +41,7 @@ export type MultiDomainAndOrProxyPrimitives =
        */
       isSatellite?: never;
       /**
-       * The URL that Clerk will proxy requests to. Required for applications that run behind a reverse proxy. Can be either a relative path (`/__clerk`) or a full URL (`https://<your-domain>/__clerk`).
+       * **Required for applications that run behind a reverse proxy**. The URL that Clerk will proxy requests to. Can be either a relative path (`/__clerk`) or a full URL (`https://<your-domain>/__clerk`).
        */
       proxyUrl?: never | string;
       /**
@@ -63,7 +63,7 @@ export type MultiDomainAndOrProxyPrimitives =
 export type DomainOrProxyUrl =
   | {
       /**
-       * The URL that Clerk will proxy requests to. Required for applications that run behind a reverse proxy. Can be either a relative path (`/__clerk`) or a full URL (`https://<your-domain>/__clerk`).
+       * **Required for applications that run behind a reverse proxy**. The URL that Clerk will proxy requests to. Can be either a relative path (`/__clerk`) or a full URL (`https://<your-domain>/__clerk`).
        */
       proxyUrl?: never;
       /**

packages/types/src/redirects.ts

@@ -2,14 +2,14 @@ import type { EnterpriseSSOStrategy, OAuthStrategy, SamlStrategy } from './strat
 
 export type AfterSignOutUrl = {
   /**
-   * Full URL or path to navigate after successful sign out.
+   * Full URL or path to navigate to after successful sign out.
    */
   afterSignOutUrl?: string | null;
 };
 
 export type AfterMultiSessionSingleSignOutUrl = {
   /**
-   * Full URL or path to navigate after signing out the current user is complete.
+   * Full URL or path to navigate to after signing out the current user is complete.
    * This option applies to multi-session applications.
    */
   afterMultiSessionSingleSignOutUrl?: string | null;
@@ -52,7 +52,7 @@ export type AuthenticateWithRedirectParams = {
   redirectUrl: string;
 
   /**
-   * Full URL or path to navigate after the OAuth or SAML flow completes.
+   * Full URL or path to navigate to after the OAuth or SAML flow completes.
    */
   redirectUrlComplete: string;
 
@@ -87,7 +87,7 @@ export type AuthenticateWithPopupParams = AuthenticateWithRedirectParams & { pop
 
 export type RedirectUrlProp = {
   /**
-   * Full URL or path to navigate after a successful action.
+   * Full URL or path to navigate to after a successful action.
    */
   redirectUrl?: string | null;
 };