Merge branch 'main' into rob/eco-361-custom-pages

docs/_partials/hooks/use-auth.mdx

@@ -1,4 +1,4 @@
-The following example uses the `useAuth()` hook to access the current auth state, as well as helper methods to manage the current active session. The hook returns `userId`, which can be used to protect your routes.
+The following example uses the [`useAuth()`](/docs/references/react/use-auth) hook to access the current auth state, as well as helper methods to manage the current active session. The hook returns `userId`, which can be used to protect your routes.
 
 ```tsx {{ filename: 'example.tsx' }}
 export default function Example() {

docs/_partials/hooks/use-user.mdx

@@ -1,4 +1,4 @@
-The following example uses the `useUser()` hook to access the [`User`](/docs/references/javascript/user/user) object, which contains the current user's data such as their full name. The `isLoaded` and `isSignedIn` properties are used to handle the loading state and to check if the user is signed in, respectively.
+The following example uses the [`useUser()`](/docs/references/react/use-user) hook to access the [`User`](/docs/references/javascript/user/user) object, which contains the current user's data such as their full name. The `isLoaded` and `isSignedIn` properties are used to handle the loading state and to check if the user is signed in, respectively.
 
 ```tsx {{ filename: 'src/Example.tsx' }}
 export default function Example() {

docs/_partials/nextjs/create-first-user.mdx

@@ -1,6 +1,6 @@
 1. Run your project with the following command:
 
-   <CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
+   <CodeBlockTabs options={["npm", "yarn", "pnpm", "bun"]}>
      ```bash {{ filename: 'terminal' }}
      npm run dev
      ```
@@ -12,6 +12,10 @@
      ```bash {{ filename: 'terminal' }}
      pnpm dev
      ```
+
+     ```bash {{ filename: 'terminal' }}
+     bun dev
+     ```
    </CodeBlockTabs>
 1. Visit your app's homepage at [http://localhost:3000](http://localhost:3000).
 1. Click "Sign up" in the header and authenticate to create your first user.

docs/authentication/configuration/session-options.mdx

@@ -68,6 +68,16 @@ To enable multi-session in your application, you need to configure it in the Cle
 1. Toggle on **Multi-session handling**.
 1. Select **Save**.
 
+### Add multi-session support to your app
+
+<If sdk={['nextjs', 'react']}>
+  It's highly recommended to wrap your application in the [`<MultisessionAppSupport />`](/docs/components/control/multi-session) component. This guarantees a full rerendering cycle every time the current session and user changes.
+</If>
+
+<If sdk={["nextjs", "react", "expo", "react-router", "tanstack-start"]}>
+  You can pass the `afterMultiSessionSingleSignOutUrl` property to [`<ClerkProvider>`](/docs/components/clerk-provider) to specify where to navigate to after signing out from a currently active account in a multi-session app.
+</If>
+
 There are two main ways to add the multi-session feature to your application:
 
 - Use the [`<UserButton />`](/docs/components/user/user-button) component if you want to use a prebuilt UI.

docs/backend-requests/resources/session-tokens.mdx

@@ -11,24 +11,33 @@ Learn more about how Clerk combines session token authentication and JWT authent
 
 Every generated token has default claims that cannot be overridden by templates. Clerk's default claims include:
 
-- `azp`: authorized party - the `Origin` header that was included in the original Frontend API request made from the user. Most commonly, it will be the URL of the application. For example: `https://example.com`. This claim could be omitted if, for privacy-related reasons, `Origin` is empty or null.
-- `exp`: expiration time - the time after which the token will expire, as a Unix timestamp. Determined using the **Token lifetime** JWT template setting in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) for more information.
-- `iat`: issued at - the time at which the token was issued as a Unix timestamp. For example: `1516239022`. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) for more information.
-- `iss`: issuer - the Frontend API URL of your instance. For example: `https://clerk.your-site.com` for a production instance or `https://your-site.clerk.accounts.dev` for a development instance. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1) for more information.
-- `nbf`: not before - the time before which the token is considered invalid, as a Unix timestamp. Determined using the **Allowed Clock Skew** JWT template setting in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) for more information.
-- `sid`: session ID - the ID of the current session For example: `sess_123`.
-- `sub`: subject - the ID of the current user of the session. For example: `user_123`. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2) for more information.
-- `act`: actor - will only be included if the user is [impersonating](/docs/users/user-impersonation) another user. It's an object that contains the following properties:
-  - `iss`: issuer - the referrer of the token. For example: `https://dashboard.clerk.com`.
-  - `sid`: session ID - the session ID of the impersonated session. For example: `sess_456`.
-  - `sub`: subject - the ID of the impersonator. For example: `user_456`.
-
-The following claims are only included if the user is part of an organization:
-
-- `org_id`: organization ID - the ID of the active organization that the user belongs to.
-- `org_permissions`: organization permissions - the permissions of the user in the currently active organization.
-- `org_slug`: organization slug - the slug of the currently active organization that the user belongs to.
-- `org_role`: organization role - the role of the user in the currently active organization.
+| Claim | Abbreviation expanded | Description | Example |
+| - | - | - | - |
+| `azp` | authorized party | The `Origin` header that was included in the original Frontend API request made from the user. Most commonly, it will be the URL of the application. This claim could be omitted if, for privacy-related reasons, `Origin` is empty or null. | `https://example.com` |
+| `exp` | expiration time | The time after which the token will expire, as a Unix timestamp. Determined using the **Token lifetime** JWT template setting in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) for more information. | `1713158400` |
+| `fva` | factor verification age | Each item represents the minutes that have passed since the last time a first or second factor, respectively, was verified. | `[7, -1]` which means it has been 7 minutes since the first factor was verified, and there either is not a second factor or the second factor has never been verified. |
+| `iat` | issued at | The time at which the token was issued as a Unix timestamp. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) for more information. | `1713158400` |
+| `iss` | issuer | The Frontend API URL of your instance. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1) for more information. | `https://clerk.your-site.com` for a production instance, `https://your-site.clerk.accounts.dev` for a development instance |
+| `nbf` | not before | The time before which the token is considered invalid, as a Unix timestamp. Determined using the **Allowed Clock Skew** JWT template setting in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) for more information. | `1713158400` |
+| `sid` | session ID | The ID of the current session. | `sess_123` |
+| `sub` | subject | The ID of the current user of the session. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2) for more information. | `user_123` |
+
+The **`act` (actor) claim** is only included if the user is [impersonating](/docs/users/user-impersonation) another user. It's value is an object that contains the following properties:
+
+| Claim | Abbreviation expanded | Description | Example |
+| - | - | - | - |
+| `iss` | issuer | The referrer of the token. | `https://dashboard.clerk.com` |
+| `sid` | session ID | The session ID of the impersonated session. | `sess_456` |
+| `sub` | subject | The ID of the impersonator. | `user_456` |
+
+The following claims are only included if the user is part of an [organization](/docs/organizations/overview):
+
+| Claim | Abbreviation expanded | Description | Example |
+| - | - | - | - |
+| `org_id` | organization ID | The ID of the active organization that the user belongs to. | `org_123` |
+| `org_permissions` | organization permissions | The permissions of the user in the currently active organization. | `["org:sys_profile:manage", "org:sys_profile:delete"]` |
+| `org_slug` | organization slug | The slug of the currently active organization that the user belongs to. | `org-slug` |
+| `org_role` | organization role | The role of the user in the currently active organization. | `org:admin` |
 
 If you would like to add custom claims to your session token, you can [customize it](/docs/backend-requests/making/custom-session-token).
 

docs/components/clerk-provider.mdx

@@ -47,9 +47,9 @@ The recommended approach is to wrap your entire app with `<ClerkProvider>` at th
   <Tab>
     ```tsx {{ filename: 'index.tsx' }}
     import React from 'react'
-    import ReactDOM from 'react-dom'
+    import ReactDOM from 'react-dom/client'
+    import App from './App.tsx'
     import { ClerkProvider } from '@clerk/clerk-react'
-    import App from './App'
 
     // Import your Publishable Key
     const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
@@ -58,13 +58,12 @@ The recommended approach is to wrap your entire app with `<ClerkProvider>` at th
       throw new Error('Add your Clerk Publishable Key to the .env.local file')
     }
 
-    ReactDOM.render(
+    ReactDOM.createRoot(document.getElementById('root')!).render(
       <React.StrictMode>
-        <ClerkProvider publishableKey={PUBLISHABLE_KEY}>
+        <ClerkProvider publishableKey={PUBLISHABLE_KEY} afterSignOutUrl="/">
           <App />
         </ClerkProvider>
       </React.StrictMode>,
-      document.getElementById('root'),
     )
     ```
   </Tab>

docs/components/control/multi-session.mdx

@@ -9,28 +9,49 @@ The `<MultisessionAppSupport>` provides a wrapper for your React application tha
 
 <Tabs items={["Next.js", "React"]}>
   <Tab>
-    ```tsx {{ filename: 'pages/_app.tsx' }}
-    import '@/styles/globals.css'
-    import { MultisessionAppSupport, ClerkProvider } from '@clerk/nextjs/internal'
-    import { AppProps } from 'next/app'
-
-    function MyApp({ Component, pageProps }: AppProps) {
-      return (
-        <ClerkProvider {...pageProps}>
-          <MultisessionAppSupport>
-            <Component {...pageProps} />
-          </MultisessionAppSupport>
-        </ClerkProvider>
-      )
-    }
+    <CodeBlockTabs options={["App Router", "Pages Router"]}>
+      ```tsx {{ filename: 'app/layout.tsx' }}
+      import React from 'react'
+      import { ClerkProvider, MultisessionAppSupport } from '@clerk/nextjs'
 
-    export default MyApp
-    ```
+      export default function RootLayout({ children }: { children: React.ReactNode }) {
+        return (
+          <html lang="en">
+            <ClerkProvider>
+              <MultisessionAppSupport>
+                <body>{children}</body>
+              </MultisessionAppSupport>
+            </ClerkProvider>
+          </html>
+        )
+      }
+      ```
+
+      ```tsx {{ filename: 'pages/_app.tsx' }}
+      import { ClerkProvider, MultisessionAppSupport } from '@clerk/nextjs'
+      import type { AppProps } from 'next/app'
+
+      function MyApp({ Component, pageProps }: AppProps) {
+        return (
+          <ClerkProvider {...pageProps}>
+            <MultisessionAppSupport>
+              <Component {...pageProps} />
+            </MultisessionAppSupport>
+          </ClerkProvider>
+        )
+      }
+
+      export default MyApp
+      ```
+    </CodeBlockTabs>
   </Tab>
 
   <Tab>
-    ```tsx {{ filename: 'app.tsx' }}
-    import { ClerkProvider, MultisessionAppSupport } from '@clerk/clerk-react/internal'
+    ```tsx {{ filename: 'index.tsx' }}
+    import React from 'react'
+    import ReactDOM from 'react-dom/client'
+    import App from './App.tsx'
+    import { ClerkProvider, MultisessionAppSupport } from '@clerk/clerk-react'
 
     // Import your Publishable Key
     const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
@@ -39,19 +60,15 @@ The `<MultisessionAppSupport>` provides a wrapper for your React application tha
       throw new Error('Add your Clerk Publishable Key to the .env.local file')
     }
 
-    function App() {
-      return (
-        <ClerkProvider publishableKey={PUBLISHABLE_KEY}>
+    ReactDOM.createRoot(document.getElementById('root')!).render(
+      <React.StrictMode>
+        <ClerkProvider publishableKey={PUBLISHABLE_KEY} afterSignOutUrl="/">
           <MultisessionAppSupport>
-            <Page />
+            <App />
           </MultisessionAppSupport>
         </ClerkProvider>
-      )
-    }
-
-    function Page() {
-      return <div>The content</div>
-    }
+      </React.StrictMode>,
+    )
     ```
   </Tab>
 </Tabs>